Developers
Give your AI assistant the power to post letters. Claude Code, Cursor, VS Code and other MCP clients can quote, upload and order with the same keys, scopes and daily caps as the REST API.
Model Context Protocol (MCP) is the open standard that lets AI tools call outside services. modelcontextprotocol.io
Illustration: an AI assistant window connects to ModernMail, is asked to post a letter, runs the upload, address check and quote tools, asks for confirmation and places the order.
Hover or tap to replay
POST https://modernmail.co.uk/api/mcpAuthorization: Bearer mm_live_…modernmail 1.0.0The MCP server and the REST API share one service layer. A tool call does exactly what the matching endpoint does, checks the same scope, counts against the same rate limits and spend cap, and shows up in the same request log and order history (orders carry an MCP badge).
Cross-origin browser requests are refused; the server is for agent hosts and command-line clients, not web pages.
One command. Add --scope user to make it available in every project rather than just the current one.
claude mcp add --transport http modernmail https://modernmail.co.uk/api/mcp \ --header "Authorization: Bearer mm_live_…".cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project.
{ "mcpServers": { "modernmail": { "url": "https://modernmail.co.uk/api/mcp", "headers": { "Authorization": "Bearer mm_live_…" } } }}.vscode/mcp.json. The inputs entry asks for the key once and keeps it out of the file.
{ "inputs": [ { "id": "modernmail-key", "type": "promptString", "description": "ModernMail API key", "password": true } ], "servers": { "modernmail": { "type": "http", "url": "https://modernmail.co.uk/api/mcp", "headers": { "Authorization": "Bearer ${input:modernmail-key}" } } }}Claude Desktop's config file takes local commands, so bridge to the remote server with mcp-remote. The header goes through an environment variable because some hosts split arguments on spaces.
{ "mcpServers": { "modernmail": { "command": "npx", "args": [ "-y", "mcp-remote", "https://modernmail.co.uk/api/mcp", "--transport", "http-only", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer mm_live_…" } } }}Not supported yet: connectors that need OAuth or allow no authentication at all, such as the claude.ai web app's custom connectors and ChatGPT connectors. The server authenticates with a static bearer key only. If you need OAuth, email info@modernmail.co.uk.
account:read, files:write, orders:read: it can price, upload and read, but not order. Grant orders:write only to a key you want to spend.spend_cap_exceeded.insufficient_credit and a top-up link for the human.create_order tool's description tells the assistant to quote first and confirm the total and recipients with you before calling it, and to pass the quote's expectedTotalPence so a price change is refused rather than charged. A fresh idempotencyKey per attempt means a retry can never pay twice.cancel_order refunds a whole order to credit and is the only tool that undoes anything; it is marked destructive and only works while nothing on the order has been started. There is no tool to delete files or change account settings. Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so hosts can ask for your approval appropriately.Get pricing
The current rate card: postage services with prices and delivery times, envelope and paper options, colour print cost, extra page cost and volume discount tiers. All amounts are integer pence (GBP).
None.
Get account
Who this API key acts as (person or business), the prepaid credit balance, the key's scopes and its daily spend cap with today's usage. Check the balance before creating an order.
None.
Upload a document
Upload a PDF or Word document to be printed. Give either a public https URL (up to 50 MB) or base64 bytes (up to 4 MB). The file type is detected from its bytes; PDFs with scripts, actions or embedded files are refused. Returns the file id to use in letters and its page count.
Also limited to 10 per minute per key (file ingests bucket).
| Field | Type | Notes |
|---|---|---|
| url | string (uri) | Public https URL of the document (http is refused). |
| base64 | string | Base64 of the document bytes (standard or URL-safe). |
| filename | string | Name to show on the order, e.g. invoice-123.pdf. max length 200. |
Get a document
Status and page count of an uploaded file.
| Field | Type | Notes |
|---|---|---|
| fileId* | string | max length 64. |
Check a UK address
Check a UK recipient address against Royal Mail's address file before ordering. Pass the recipient fields (at least recipientPostcode). Returns status verified (as typed), corrected (use the returned address, written as Royal Mail has it), unmatched (nothing at that postcode fits; candidates lists what is there, ask the user to choose), lookup (postcode only: candidates is every address there) or postcode_unknown. Each call is a metered lookup capped per key per day; do not call it in a loop.
Also limited to 30 per minute per key (address checks bucket).
| Field | Type | Notes |
|---|---|---|
| recipientName | string | max length 200. |
| recipientAddressLine1 | string | max length 200. |
| recipientAddressLine2 | string | max length 200. |
| recipientAddressLine3 | string | max length 200. |
| recipientCity | string | max length 100. |
| recipientPostcode* | string | A UK postcode. min length 5, max length 8. |
Quote an order
Price an order without creating it. One entry per recipient: name and address, postageType (see get_pricing), colourPrint (bw|colour), paperQuality (standard|premium), envelopeStyle, quantity and the uploaded file ids (uploadIds). Returns per-letter prices, discounts, the total, whether credit covers it and the expectedTotalPence to pass to create_order.
| Field | Type | Notes |
|---|---|---|
| letters* | object[] | min 1 item, max 500 items. |
Each entry in letters is a letter object: recipient, postage, print options and the uploaded file ids.
Create and pay for an order
Create an order and pay for it from the account's prepaid credit. Spends money: confirm the total and recipients with the user first, and quote_order before calling. Pass the quote's expectedTotalPence so a price change is refused rather than charged. idempotencyKey must be a fresh unique string (UUID) per order attempt; reuse it only when retrying the same order. Pass postOn (a UK working day, YYYY-MM-DD, tomorrow to 12 months ahead) to pay now and have the order held until that day; confirm the day with the user first. Or pass deliverBy (YYYY-MM-DD, a day Royal Mail delivers on) to have the posting day worked out from each letter's postage so it arrives by then; refused with deliver_by_unreachable when a chosen service can't make it. Fails with insufficient_credit (402) when the balance is short, spend_cap_exceeded when the key's daily cap would be passed, post_on_invalid for a day we don't post on and scheduling_unavailable when scheduling is switched off.
Also limited to 5 per minute per key (order creations bucket).
| Field | Type | Notes |
|---|---|---|
| letters* | object[] | min 1 item, max 500 items. |
| expectedTotalPence | integer | From quote_order. min 0. |
| reference | string | Your own reference, shown on the order. max length 120. |
| postOn | string | Post on this UK working day (YYYY-MM-DD), tomorrow to 12 months ahead. Omit to post on the next posting day. |
| deliverBy | string | Arrive by this UK date (YYYY-MM-DD; Mon–Sat, not a bank holiday). The posting day is worked out from each letter's postage; Royal Mail's aim, not a guarantee. Not together with postOn. |
| idempotencyKey* | string | Unique per order attempt, e.g. a UUID. max length 200. |
Each entry in letters is a letter object: recipient, postage, print options and the uploaded file ids.
Cancel an order
Cancel a whole order for a full refund to the account's credit (or the card it was paid with). Only possible while the order is paid and nothing on it has been started: once printing or labelling has begun it is refused with order_not_cancellable, and the user should ask support instead. The returned order has every letter cancelled and status refunded (money returned) or cancelled. Confirm with the user before calling. Cannot be undone.
| Field | Type | Notes |
|---|---|---|
| orderId* | string | max length 64. |
Get an order
One order with its status, amounts and letters (dispatch dates and Royal Mail tracking numbers).
| Field | Type | Notes |
|---|---|---|
| orderId* | string | max length 64. |
List orders
The account's orders, newest first, with a cursor for the next page.
| Field | Type | Notes |
|---|---|---|
| status | string | One of created, paid, processing, completed, cancelled, refunded |
| reference | string | Exact match on the reference given at creation. max length 120. |
| onlyThisKey | boolean | Only orders placed with this API key. |
| limit | integer | min 1, max 100. |
| cursor | string |
created, paid, processing, completed, cancelled, refunded| URI | Title | Contents | Scope |
|---|---|---|---|
| modernmail://docs/ordering | How to order letters | Step-by-step guide to uploading, quoting and ordering. text/markdown | Any key |
| modernmail://pricing | Current pricing | Postage, envelope, print and paper prices and volume discounts. application/json | Any key |
| modernmail://account | Account | Who this key acts as, credit balance and today's spend. application/json | account:read |
modernmail://docs/ordering. Useful to know, because it is the script your agent will follow.upload_document (a public URL or base64 of a PDF or Word file). Note the returned file id and pageCount.quote_order: one entry per recipient with their address, the postage service, print options and the file ids. The quote returns expectedTotalPence and whether the account's credit covers it.cancel_order for a full refund only while nothing has been started on them (usually the same day, before printing); after that the user asks support.create_order, passing the same letters, expectedTotalPence from the quote and a fresh idempotencyKey (a UUID) you keep for retries. The order is printed and posted by ModernMail; use get_order to follow its status and tracking.To post on a later day, pass postOn to create_order: a UK working day (Mon–Fri, not a bank holiday) in YYYY-MM-DD, from tomorrow up to 12 months ahead. The order is paid now and held in the account until that morning; until then the user can change the day or cancel it for a full refund from their account. Confirm the day with the user before creating the order. A weekend or bank holiday is refused with post_on_invalid and details.nextWorkingDay.
To have a letter arrive by a date instead, pass deliverBy (YYYY-MM-DD, a day Royal Mail delivers on: Mon–Sat, not a bank holiday) in place of postOn. ModernMail works back from Royal Mail's usual aim for each letter's postage service to the last working day that still makes it and holds the order until then; the response's postOn is that day. Only services that can reach the date are accepted: a 1st Class, Tracked 24 or Special Delivery letter can arrive the next working day, 2nd Class and Tracked 48 the day after next (1st Class, 1st Class Signed For, Tracked 24 and Tracked 48 are delivered on Saturdays too; 2nd Class and Special Delivery are not). A service that can't make it is refused with deliver_by_unreachable; details.services lists each service's earliest date and details.suggestedDeliverBy the first date they all meet, so either move the date or change the service. These are Royal Mail's aims, not guarantees; Special Delivery is the guaranteed service.
Addresses: UK recipients need a valid postcode and recipientCountry: "GB" (the default); non-UK recipients must use postageType: "international_standard" with their ISO country code. When the key has the addresses:validate scope, run validate_address on each UK recipient before quoting: use a corrected address as returned, and ask the user to choose when it is unmatched. It is a metered lookup, so once per address, not in a loop. Postage services and prices are in get_pricing. Amounts are integer pence.
If create_order fails with insufficient_credit, tell the user the shortfall and give them the top-up link; do not retry until they have added credit.
A key starting mm_test_ is a sandbox key: every tool works the same, but orders are simulated (livemode: false), nothing is charged, printed or posted, and the credit shown is a daily sandbox allowance. Tell the user when you are in the sandbox.
Every MCP request counts against the key's writes bucket (30 per minute). upload_document also uses the file ingests bucket (10 per minute) create_order the order creations bucket (5 per minute) and validate_address the address checks bucket (30 per minute, plus a daily cap per key), the same as the REST endpoints they mirror.
A bad or missing key is a plain HTTP 401. Once authenticated, a refused tool call is still HTTP 200: the result has isError: true and carries the REST error body, so insufficient_scope, insufficient_credit, spend_cap_exceeded, price_changed, not_found and rate_limited (with retryAfterSeconds) mean exactly what they do over REST.
{ "isError": true, "structuredContent": { "error": { "code": "insufficient_scope", "message": "This API key does not have the orders:write scope. Ask the account owner to grant it under Account → Developers.", "details": { "required": "orders:write" } } }}Everything here is also a JSON endpoint. The REST API reference covers the ordering flow, idempotency, webhooks and every object in detail, with an OpenAPI 3.1 spec.
Read the API reference →