ModernMail REST API

The API is versioned in the path (/v1). Fields are added over time but never removed or retyped without a new version prefix, so a client written today keeps working. Every response carries cache-control: no-store except the public pricing and spec endpoints.

Orders placed here appear in the customer's account like any other, with an API badge, and go through the same print and posting run. Cancellation, refunds and address lookup are not available through the API yet; use your account for those.

1. Sign in (or create a free account), verify your email, then open Account → Developers. In a business, the primary user and admins can create keys that act for the business.
2. Create a key: give it a name, choose its scopes, set a daily spend cap and an optional expiry. You retype your password to confirm.
3. The key (mm_live_…) is shown once. We store only a keyed hash of it. The account owner is emailed whenever a key is created or revoked.

Send it on every request:

A missing, malformed, unknown, expired or revoked key always gets the same 401 unauthorized, so a probe learns nothing about which keys exist. A key stops working the moment it is revoked, its owner's account is suspended or closed, or its owner leaves the business it was created in. Keys never appear in our request logs.

A call without the right scope gets 403 insufficient_scope with details.required naming the missing one. The MCP server enforces the same scopes.

Optionally first: POST /addresses/validate with a letter's recipient fields checks a UK address against Royal Mail's address file and hands it back as Royal Mail writes it, or lists what is at the postcode. It is a paid lookup on our side, so it needs the addresses:validate scope and is capped per key per day.

1. POST /files for each document. You get a file id and its page count.
2. POST /quotes with your letters. You get per-letter prices, discounts, the total and expectedTotalPence, plus whether your credit covers it.
3. POST /orders with the same letters, the expectedTotalPence and an Idempotency-Key. The order is created and paid in one step.
4. GET /orders/{id} to follow status, dispatch dates and Royal Mail tracking numbers, or register a webhook and let us tell you.

A letter is one recipient plus the documents to print for them. Up to 500 letters per order, 100 copies per letter and 50 documents per letter. Allowed postageType and envelopeStyle values, with prices and delivery aims, come from GET /pricing. Non-UK recipients use postageType: "international_standard" with an ISO 3166-1 alpha-2 recipientCountry.

Top up at Account → Credit before you order. When the balance is short the order is refused with 402 insufficient_credit, and details carries the total, the balance, the shortfall and a top-up link. Nothing is charged.

Pass the quote's expectedTotalPence on POST /orders. If prices or discounts have moved since the quote you get 409 price_changed rather than a surprise charge; quote again and resend.

Every key has a daily spend cap (default £50, counted per Europe/London calendar day). An order that would pass it fails with 403 spend_cap_exceeded. Personal accounts may set up to £5,000; a business's primary user up to £50,000. Business members' own monthly limits still apply.

Volume and account discounts apply exactly as they do on the website. There is no per-call fee: you pay the letter prices and nothing else.

When you create a key, choose Sandbox and it starts mm_test_… instead of mm_live_…. Every endpoint and MCP tool accepts it. Uploads, quotes and validation are real; orders are simulated and come back with livemode: false and a TEST- order number. They never reach our print room and never touch your credit.

• Credit is a pretend balance of £1,000 per sandbox key per London day, drawn down by sandbox orders and refilled each morning. The key's daily spend cap applies to it too.
• Status moves on its own. A sandbox order is paid for 2 minutes, processing until 10 minutes, then completed with each letter posted and, for tracked services, a TT…GB tracking number. A scheduled sandbox order waits as paid until 07:00 on its posting day.
• Cancel works while the order is paid, so you have 2 minutes to exercise it; after that it is refused with 409 order_not_cancellable, as a live order would be once we had started.
• Force a refusal by setting reference to sandbox:insufficient_credit, sandbox:spend_cap_exceeded, sandbox:price_changed or sandbox:internal. The order is refused with that error and nothing is stored.
• Webhooks fire for order.paid on creation and order.status_changed on cancellation, to your own endpoints only, with livemode: false in the payload. The timed moves to processing and posted do not send events.
• Sandbox orders are listed by GET /orders with a sandbox key and never by a live one. They are kept for 30 days.

Idempotency, rate limits, scopes and error shapes are identical in both modes, so an integration that passes against the sandbox needs only a live key to go live.

POST /orders requires an Idempotency-Key header: any unique string up to 200 printable characters (use a UUID). Keys are kept for 24 hours.

• Same key, same body: the stored response is replayed with an idempotent-replayed: true header.
• Same key, different body: 409 idempotency_key_reused.
• Same key while the first request is still running: 409 idempotency_in_progress with retry-after: 2.

The link between the key and the paid order is committed in the same database transaction as the credit debit, so even a crash mid-response cannot double-charge. Outcomes you can fix are not stored: 402, 403 spend_cap_exceeded, 409 price_changed and server errors release the key, so you can top up or re-quote and retry with the same one.

Responses carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (Unix seconds). A refused request is 429 rate_limited with a retry-after header.

Register endpoints at Account → Developers or with POST /webhooks (webhooks:manage). Up to 50 per account, https only. The signing secret is returned once, on creation.

Each delivery is a POST with a JSON body { id, type, createdAt, data }. data carries the event's own fields (for example the letter, its postage and tracking numbers) plus an order summary with the order number, status and your reference. Headers: x-modernmail-event (the type), x-modernmail-delivery (a unique id to de-duplicate on), x-modernmail-signature and User-Agent: ModernMail-Webhooks/1.0.

Any 2xx within 10 seconds counts as delivered. Failures retry with exponential backoff for up to 6 attempts. After 25 consecutive failures the endpoint is switched off and the owner emailed; re-enable it from Developers, where you can also send a test event.

x-modernmail-signature: t=<unix seconds>,v1=<hex> where v1 is HMAC-SHA256 of "<t>.<raw body>" under your endpoint's secret. Reject deliveries whose t is more than five minutes off, compare in constant time, and de-duplicate on id.

Deprecated: the older x-modernmail-signature-legacy header (HMAC of the body alone, with no timestamp) is still sent until 31 December 2026 and then dropped. It cannot tell a replay from a fresh delivery, so verify x-modernmail-signature instead.

• PDF or Word (.doc, .docx). The type is detected from the bytes, not trusted from the header or filename.
• Inline uploads (multipart or base64) up to 4 MB. Larger files, up to 50 MB, go by url (fetched by us) or presign (you PUT the bytes to storage, then call finalize).
• PDFs containing JavaScript, launch actions, open actions, embedded files or rich media are refused with 415.
• URL fetches must be https, are blocked for private and local addresses and time out after 20 seconds; up to five redirects are followed, each hop checked against the same rules.
• Page counts come from the file itself; the first pages included free and the per-page price follow the rate card.

Stuck, or need something the API does not do yet? Email info@modernmail.co.uk with the time of the request and the x-modernmail-delivery or order id, and we will look at the log. We never store request bodies or keys, so include what you sent.