API, mail merge & e-mail sending

Send letters straight from your software – via REST API, as a mail merge or simply by e-mail. The Claude connector uses the same functions.

Authentication

Create a key under Account → API keys and send it as a bearer token. Each request only charges that account's balance.

curl -H "Authorization: Bearer mbx_…" https://mcpbrief.de/api/v1/balance

OpenAPI description: https://mcpbrief.de/openapi.json

Endpoints

GET	/balance	Balance, prices, sender, daily limit
POST	/letter/price	Check address, build letter, pages and price + PDF preview (sends nothing)
POST	/letter/send	Send a letter (text, PDF, DOCX, image; enclosures, duplex, cost centre)
GET	/letter/{id}	Status and tracking number
POST	/letter/{id}/cancel	Cancel before printing (refund)
POST	/letter/{id}/resend	Send again
GET	/letters?limit=&status=&since=&cost_center=&batch_id=	List of your letters, filterable
POST	/letters/batch/price	Check a mail merge: all addresses, placeholders, total price
POST	/letters/batch/send	Send a mail merge (max. 200 recipients)

Example: registered mail with enclosure

curl -X POST https://mcpbrief.de/api/v1/letter/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipient": {"name": "Muster GmbH", "street": "Ringstraße 5",
                "zip": "1010", "city": "Wien", "country": "AT"},
  "subject": "Rechnung 2026-17",
  "content": "Sehr geehrte Damen und Herren,\n\nanbei …",
  "attachments": [{"file_base64": "JVBERi0…", "file_name": "rechnung.pdf"}],
  "delivery": "registered", "duplex": true, "cost_center": "VERTRIEB",
  "idempotency_key": "7d1c2f0e-…"
}'

Example: mail merge

curl -X POST https://mcpbrief.de/api/v1/letters/batch/send \
  -H "Authorization: Bearer mbx_…" -H "Content-Type: application/json" \
  -d '{
  "recipients": [
    {"name": "Muster GmbH", "street": "Ringstraße 5", "zip": "1010",
     "city": "Wien", "country": "AT", "anrede": "Sehr geehrte Frau Huber"},
    {"name": "Beispiel AG", "street": "Hauptstraße 1", "zip": "10115",
     "city": "Berlin", "country": "DE", "anrede": "Sehr geehrte Damen und Herren"}
  ],
  "subject": "Preisanpassung 2027",
  "content": "{{anrede}},\n\nab 1. Jänner gelten neue Preise …",
  "delivery": "standard", "idempotency_key": "batch-2027-01"
}'

Letters by e-mail

No programming needed: every account has a personal order address. PDFs you send from your account e-mail to this address go out as letters.

Each PDF attachment = one letter, address in the window area (DIN 5008)
The subject controls options: Registered, Priority, Colour, Duplex, Ref: …, Country: …
“Enclosure” in the subject: all files are combined into one letter
“Test” in the subject: check only and get the price by e-mail – nothing is sent

Status values

The status endpoint, the list and the e-mail notification show the current state.

`pending`	queued
`processing`	printing & enveloping
`mailed`	handed over to the postal service
`failed`	not sent
`cancelled`	cancelled
`undeliverable`	undeliverable
`rejected`	rejected