EchtPost API v2 — AI consumer guide

This guide is written for LLM-based clients and developers wiring up integrations. Endpoints, error shapes, and examples are kept as copy-paste-ready as possible.

Base URL

https://api.echtpost.de/v2

Authentication

The API accepts two credential types — both sent in a header. Query-string parameters such as ?apikey= are not accepted on v2.

Recommended: OAuth 2.1 (user-delegated access)

Use OAuth when the integration acts on behalf of a real EchtPost user (Claude, ChatGPT, third-party apps with a UI). Tokens are short-lived, scoped to the user's chosen account, and can be revoked from the user's side without touching API keys.

Discovery URLs:

https://api.echtpost.de/.well-known/oauth-protected-resource   # RFC 9728
https://my.echtpost.de/.well-known/oauth-authorization-server  # RFC 8414

A 401 response from any v2 endpoint sets WWW-Authenticate: Bearer resource_metadata="https://api.echtpost.de/.well-known/oauth-protected-resource", which points at the protected-resource document. That document declares https://my.echtpost.de as the authorization server; clients then walk the RFC 8414 metadata there to find the authorize / token / register endpoints. Tokens must include the api scope to be accepted on the REST API. A token scoped only for mcp will be rejected here (and vice versa on the MCP server). Request scope=mcp api if you need both.

The flow is OAuth 2.1 Authorization Code with PKCE. Once you have an access token:

curl -sS -H "Authorization: Bearer $ECHTPOST_OAUTH_TOKEN" \
  "https://api.echtpost.de/v2/me"

Dynamic client registration (RFC 7591) is supported at POST https://my.echtpost.de/oauth/register if you don't want to manually register a client.

Alternative: API key (server-to-server)

Use an API key for server-side scripts and automations where there is no end-user to consent. Create keys in the EchtPost web app under Account → API keys.

Supported headers (in order of precedence):

1. X-Api-Key: <your key>
2. Authorization: Bearer <your key>

V1's X-apikey header is not accepted on v2.

curl -sS -H "X-Api-Key: $ECHTPOST_API_KEY" \
  "https://api.echtpost.de/v2/me"

Sandbox mode

An API key is created in one of two modes, visible in its prefix:

The mode is fixed at creation. A sandbox key sees only sandbox records and a live key only live records — including on GET endpoints, so a sandbox integration cannot read or cancel production cards.

Sandbox data can be wiped for the whole account from Account → API keys in the web app.

Because sandbox skips the funds check, 402 Insufficient Funds never occurs naturally there. To exercise that error path, pass simulate=insufficient_funds when creating a card:

curl -sS -X POST \
  -H "X-Api-Key: ***" \
  -H "Content-Type: application/json" \
  -d '{ "motive_id":42, "content":"Hi", "deliver_at":"tomorrow", "recipients":[{ "contact_id":123 }], "simulate":"insufficient_funds" }' \
  "https://api.echtpost.de/v2/cards"

The parameter is ignored on live keys.

The MCP server honours the same distinction — see mcp_guide.md.

Rate limits

Requests are throttled per API key. Exceeding a limit returns 429 Too Many Requests with a Retry-After header (seconds until the window resets).

Spread bulk card creation over time or batch recipients into a single card request using recipient_ids to stay within limits.

Error format (RFC 7807)

Errors use Content-Type: application/problem+json. Each response includes:

• type — stable error-type URI (match on this, not on free text)
• title — short human-readable name
• status — HTTP status code
• detail — imperative fix hint (tells the integrator how to retry)
• instance — URL path that produced the error
• request_id — for support tickets
• errors[] — optional structured field errors (path, code, message)

Example:

{
  "type": "https://api.echtpost.de/v2/errors/text-does-not-fit",
  "title": "Message does not fit on the card",
  "status": 422,
  "detail": "Shorten the message or reduce the font size; 1 line overflows.",
  "instance": "/v2/cards",
  "request_id": "req-abc123",
  "errors": [
    { "path": "message", "code": "overflow", "message": "line 17 overflows" }
  ]
}

Retry guidance

detail is phrased imperatively — it tells you exactly what to change before retrying. Treat 422 responses as recoverable after applying the fix described in detail. 401 is terminal (bad key). 402 means top-up required. 409 on card cancel means the state transition is no longer possible.

Pagination

List endpoints return a JSON array. Read pagination from response headers:

• X-Total-Count — total rows
• X-Total-Pages — total pages for current per_page
• Link — RFC 5988 links with rel="next", rel="last"

Request parameters:

• page (default 1)
• per_page (default 50, max 200)

List filters (query parameters)

Use top-level query parameters only. v2 does not support nested filter[...].

List sorting

List endpoints accept optional sort (one allowed field name) and direction (asc or desc, case-insensitive). Omitted values use the defaults below. Results always include a stable tie-breaker on the row id ascending.

Unknown sort or invalid direction (when direction is sent) returns 422 with RFC 7807 application/problem+json.

¹ When no sort parameter is given, motives are ordered by relevance: account-specific motives first, then highlighted, then by popularity.

Card status in JSON

Card responses expose four statuses: pending (draft through uploaded), scheduled, sent, canceled (includes canceling). Internal workflow states are not exposed in the API.

Fonts

Three families, each with its own valid size range:

Colors: black, blue, or a hex value.

Line breaks in card content

Card content is plain text. Use \n (Unix newline) as the line-break character in your JSON strings — the API normalizes it to the internal \r\n format used by the print renderer. Sending \r\n directly is also accepted.

A card with no line breaks at all will render as one unbroken text block. The create endpoint returns a warnings array in the 201 response with a no_line_breaks entry if this is detected — treat it as a hint to add paragraph breaks before submitting.

Quick flow — one card in three calls

1. GET /v2/me — confirm balance and account metadata.
2. POST /v2/cards/preview_fit — iterate content + font until fits: true.
3. POST /v2/cards — create the mailing with recipient_ids or inline recipients.

Step 1 — check balance

curl -sS -H "X-Api-Key: $ECHTPOST_API_KEY" \
  "https://api.echtpost.de/v2/me"

Step 2 — check that the text fits

curl -sS -H "X-Api-Key: $ECHTPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST "https://api.echtpost.de/v2/cards/preview_fit" \
     -d '{
       "content": "Liebe Grüße aus Berlin,\ndas Team",
       "font": { "family": "architects_daughter", "size": 13 }
     }'

Response on success:

{ "fits": true, "lines_used": 3, "max_lines": 18 }

On overflow the response includes overflow_line and a suggested_font_size that would make the text fit:

{
  "fits": false,
  "lines_used": 20,
  "max_lines": 18,
  "overflow_line": 19,
  "suggested_font_size": 12
}

Step 3 — create the card

curl -sS -H "X-Api-Key: $ECHTPOST_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST "https://api.echtpost.de/v2/cards" \
     -d '{
       "motive_id": 42,
       "content": "{anrede},\nwir wünschen frohe Ostern.\nHerzlich, das Team",
       "font": { "family": "architects_daughter", "size": 13 },
       "recipient_ids": [101, 102]
     }'

The {anrede} token is substituted per recipient at render time with the recipient's salutation (e.g. "Sehr geehrte Frau Müller" or "Liebe Jana"). Use it anywhere in content, content_ps, or content_vertical. The canonical form is {anrede} (lowercase); casing is ignored at render time.

Endpoint quick reference

GET /v2/me

Account, user, API key, balance.

curl -sS -H "X-Api-Key: $KEY" "https://api.echtpost.de/v2/me"

GET /v2/credits

Balance plus current prices:

curl -sS -H "X-Api-Key: $KEY" "https://api.echtpost.de/v2/credits"

Contacts

# list with filter + sort
curl -sS -H "X-Api-Key: $KEY" \
  "https://api.echtpost.de/v2/contacts?country_code=de&sort=last_name&direction=asc"

# create
curl -sS -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
     -X POST "https://api.echtpost.de/v2/contacts" \
     -d '{
       "last_name":"Doe","first_name":"Jane",
       "street":"Musterstr. 1","zip":"10115","city":"Berlin","country_code":"de",
       "greeting_style":"formal"
     }'

# update
curl -sS -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
     -X PATCH "https://api.echtpost.de/v2/contacts/42" \
     -d '{ "city":"München" }'

# delete
curl -sS -H "X-Api-Key: $KEY" -X DELETE "https://api.echtpost.de/v2/contacts/42"

Groups

# list
curl -sS -H "X-Api-Key: $KEY" "https://api.echtpost.de/v2/groups"

# create
curl -sS -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
     -X POST "https://api.echtpost.de/v2/groups" -d '{ "name": "VIPs" }'

Deleting a group that still has members returns 409 Conflict.

Templates

curl -sS -H "X-Api-Key: $KEY" "https://api.echtpost.de/v2/templates"
curl -sS -H "X-Api-Key: $KEY" "https://api.echtpost.de/v2/templates/3"

Motives

Browse available postcard designs. Use the returned id as motive_id when creating cards.

# list all motives
curl -sS -H "X-Api-Key: $KEY" "https://api.echtpost.de/v2/motives"

# search by keyword
curl -sS -H "X-Api-Key: $KEY" \
  "https://api.echtpost.de/v2/motives?search=geburtstag"

# show a specific motive
curl -sS -H "X-Api-Key: $KEY" "https://api.echtpost.de/v2/motives/42"

Each motive includes feature flags (content_available, content_ps_available, vertical_text_available, qr_code_available) that indicate which content fields are supported, plus a url linking to the motive's page on echtpost.de.

Temporary API motives

Accounts enabled by support can upload one-off custom motives with POST /v2/motives using multipart/form-data:

curl -sS -X POST \
  -H "X-Api-Key: ***" \
  -F "name=API Messekarte" \
  -F "orientation=landscape" \
  -F "image=@front.jpg" \
  "https://api.echtpost.de/v2/motives"

The endpoint creates an account-owned motive with temporary: true. Use the returned id as motive_id on POST /v2/cards; API and MCP list/show motive calls include temporary motives for the same account. Temporary motives are not exposed to the regular web motive picker or template workflows.

Uploads are deliberately gated. The normal API key is still available immediately after signup; only the custom-motive upload capability needs support to enable it after account verification (know your customer). Disabled accounts receive feature-not-available with a support hint.

Accepted uploads are PNG or JPEG files up to 5 MB and must match the postcard motive pixel dimensions exactly: 1795x1287 for landscape or 1287x1795 for vertical. Invalid files return a 422 validation problem.

Temporary motive image assets are retained only for the configured card lifecycle. Cards created with a temporary motive get asset_expires_at automatically (deliver_at + 7 days by default); clients may set an ISO date between deliver_at + 7 days and deliver_at + 90 days. Once all referencing cards are past that lifecycle window and no card still needs the image for print, the image blobs are purged and assets_purged_at is set on the motive. The motive row and card/print history stay available, but the original image can no longer be listed or reused.

Cards

content_ps field

The P.S. is printed as a single line in the card footer — content_ps is limited to 40 characters. Longer values are rejected with a 422 (errors[].path: "content_ps", code: "too_long").

deliver_at field

The deliver_at field accepts several formats:

Constraints: must be a weekday; must not be a printer holiday. If omitted, the card is scheduled for the next available business day.

Natural-language strings like "in two days" are not accepted — use the numeric hyphenated form "2-days-from-now" instead.

asset_expires_at field

asset_expires_at is accepted only when motive_id points to a temporary motive. It controls how long the uploaded front image remains available after the card's print date. Omit it for the default retention (deliver_at + 7 days), or send an ISO date between deliver_at + 7 days and deliver_at + 90 days. Permanent motives reject this field with a 422 validation problem.

# list only scheduled + sent
curl -sS -H "X-Api-Key: $KEY" \
  "https://api.echtpost.de/v2/cards?status=scheduled,sent&sort=deliver_at"

# show
curl -sS -H "X-Api-Key: $KEY" \
  "https://api.echtpost.de/v2/cards/555"

# create from template
curl -sS -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
     -X POST "https://api.echtpost.de/v2/cards/from_template" \
     -d '{
       "template_id": 3,
       "recipient_ids": [101, 102],
       "deliver_at": "2026-05-12"
     }'

# cancel (async)
curl -sS -H "X-Api-Key: $KEY" -X DELETE "https://api.echtpost.de/v2/cards/555"

Cancel returns 202 Accepted when the cancellation is queued, or 409 Conflict with type: card-not-cancelable if the state transition is no longer possible (e.g. the card is already sent).

Notifications (optional on create)

"notification": { "type": "on_send", "email": "ops@acme.de", "send_on": "send" }

Stable error types

Match integrations on these type URIs:

All full URIs are prefixed with https://api.echtpost.de/v2/errors/.

Send Your First Postcard via the EchtPost API

This tutorial walks you through creating a real, printed postcard using the EchtPost REST API v2. By the end you'll have made four HTTP calls that result in a physical card in someone's mailbox.

What you need - An EchtPost account (sign up at echtpost.de) - A credential — either an OAuth access token (preferred for user-facing apps; see authentication section for the full flow) or an API key for server-to-server scripts (create one at Account → API keys in the web app) - Enough credit to send at least one card (top up under Account → Credits) - curl (any OS) or your HTTP client of choice

Set your credential in the shell. The examples below use an OAuth token, but you can substitute an API key with -H "X-Api-Key: $ECHTPOST_API_KEY" on every request:

export ECHTPOST_TOKEN=your_oauth_access_token_or_api_key

Step 1 — Confirm your account and balance

Before anything else, verify your key works and that your account has credit.

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  "https://api.echtpost.de/v2/me"

A successful response looks like this:

{
  "account": { "id": 1, "name": "Acme GmbH", "country_code": "de" },
  "user":    { "id": 7, "email": "you@acme.de" },
  "api_key": { "id": 3, "description": "CI pipeline" },
  "balance": {
    "credits_eur": "12.50",
    "cards_regular": 5,
    "cards_foreign": 0,
    "currency": "EUR"
  }
}

balance.cards_regular is the number of cards you can still send with your current credit. If it's 0, top up before continuing.

Step 2 — Pick a motive

Every postcard needs a motive_id — the front-side image. Browse the full motive gallery at echtpost.de/postkarten, or list the motives available to your account via the templates endpoint:

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  "https://api.echtpost.de/v2/templates"

Each item in the response includes id and motive_id. We'll use motive_id: 42 for the rest of this tutorial.

Step 3 — Validate text length (optional but recommended)

A postcard has a fixed printable area, and it's worth checking that your message fits before submitting — especially for longer texts or when you're building an automated flow. The preview_fit endpoint tells you exactly how many lines your content will use and suggests a smaller font size if it overflows.

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://api.echtpost.de/v2/cards/preview_fit" \
  -d '{
    "content": "Liebe {anrede},\n\nwir möchten uns herzlich bei Ihnen für Ihr Vertrauen bedanken und wünschen Ihnen eine wunderbare Zeit.\n\nMit freundlichen Grüßen,\nIhr Acme-Team",
    "font": { "family": "architects_daughter", "size": 13 }
  }'

Success — text fits: json { "fits": true, "lines_used": 14, "max_lines": 18 }

max_lines depends on the font family and size — it ranges from 10 (reenie_beanie at 17) to 19 (architects_daughter at 12).

Text overflows — a longer message sent with "size": 14: json { "fits": false, "lines_used": 20, "max_lines": 17, "overflow_line": 18, "suggested_font_size": 12 }

If fits is false, you have two easy options: trim the text a little, or pass the suggested_font_size as size in your create request — the API will handle the rest.

Valid font options are:

Colors: black, blue, or any hex value (e.g. "#1a2b3c").

Tip: Pass "sample_greeting": "Sehr geehrte Frau Müller" to preview_fit for an accurate line-count when your content starts with {anrede}.

Step 4 — Create the card

There are two ways to create a card via the API. Choose based on how much control you need over the content.

The easy path: send from a saved template

If the postcard content stays the same and you just want to trigger a send via the API — perhaps on a schedule or from an external system — use the from-template endpoint. Design the card once in the EchtPost editor, save it as a template, then reference its ID here. No message text, no font settings, no length checks needed.

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://api.echtpost.de/v2/cards/from_template" \
  -d '{
    "template_id": 3,
    "deliver_at": "2026-05-12",
    "recipient_ids": [101, 102]
  }'

Find your template_id via GET /v2/templates (Step 2), or copy it from the template URL in the EchtPost editor. The same recipient options apply as below — recipient_ids, group_ids, and inline recipients can all be combined in a single request.

deliver_at formats — the field accepts more than just ISO dates:

Value	Meaning
"YYYY-MM-DD"	Exact date, e.g. "2026-05-12"
"today" or "asap"	Today's date
"tomorrow"	Tomorrow
"N-days-from-now"	N calendar days ahead, e.g. "5-days-from-now"

The chosen date must be a weekday and not a printer holiday. Omitting deliver_at schedules the card for the next available business day.

The flexible path: compose content inline

Use this when the card content varies per send — for example, a dynamic message generated by your system. This is where preview_fit (Step 3) is worth running first.

{anrede} is optional. If you include it in content, the API replaces it per recipient with their personalised salutation at print time (e.g. "Sehr geehrte Frau Müller" or "Lieber Max") — pulled from the contact's name and greeting_style. You don't have to use it at all: for a single inline recipient where you're composing the greeting yourself, simply write it out directly in content. {anrede} becomes most valuable in mailings (Option B or C) where the greeting needs to differ for each recipient without you having to generate personalised texts yourself.

Option A: Inline recipients (no prior contact needed)

Best for one-off sends or when recipient data comes from an external system.

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://api.echtpost.de/v2/cards" \
  -d '{
    "motive_id": 42,
    "content": "{anrede},\n\nwir wünschen Ihnen alles Gute.\n\nHerzlich,\nIhr Acme-Team",
    "font": { "family": "architects_daughter", "size": 13, "color": "black" },
    "deliver_at": "2026-05-12",
    "recipients": [
      {
        "first_name": "Maria",
        "last_name": "Müller",
        "street": "Musterstraße 1",
        "zip": "10115",
        "city": "Berlin",
        "country_code": "de",
        "greeting_style": "formal"
      }
    ]
  }'

Option B: Saved contacts (by ID)

Use this when the recipient already exists in your EchtPost contacts.

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://api.echtpost.de/v2/cards" \
  -d '{
    "motive_id": 42,
    "content": "{anrede},\n\nwir bedanken uns für Ihr Vertrauen.\n\nHerzlich,\nIhr Team",
    "font": { "family": "architects_daughter", "size": 13 },
    "recipient_ids": [101, 102, 103]
  }'

Option C: An entire contact group

Perfect for mailings — send to everyone in a group with a single call.

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://api.echtpost.de/v2/cards" \
  -d '{
    "motive_id": 42,
    "content": "{anrede},\n\nwir freuen uns, Sie als Kunden begrüßen zu dürfen.\n\nMit freundlichen Grüßen,\nIhr Acme-Team",
    "font": { "family": "architects_daughter", "size": 13 },
    "group_ids": [7]
  }'

You can combine recipient_ids, group_ids, and inline recipients in a single request. Add "deduplicate_recipients": true to avoid sending duplicate cards if contacts appear in multiple groups.

Successful response (HTTP 201)

{
  "id": "a1b2c3d4-0000-0000-0000-111122223333",
  "status": "pending",
  "type": "CardSingle",
  "motive_id": 42,
  "content": "{anrede},\n\nwir wünschen Ihnen alles Gute.\n\nHerzlich,\nIhr Acme-Team",
  "font": { "family": "architects_daughter", "size": 13, "color": "black" },
  "contacts_count": 1,
  "deliver_at": "2026-05-12T00:00:00Z",
  "cancelable": true,
  "created_at": "2026-04-28T09:00:00Z",
  "warnings": []
}

Save the id — you'll need it to check status or cancel the card.

warnings array: A no_line_breaks warning means your content has no \n characters. The card will render but may look like a wall of text. Add paragraph breaks for better readability.

Step 5 — Verify the card

Poll the card at any time to check its status:

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  "https://api.echtpost.de/v2/cards/a1b2c3d4-0000-0000-0000-111122223333"

The status field follows this lifecycle:

pending → scheduled → sent
               ↓
           canceled

A card is cancelable as long as it hasn't reached the print queue. Cancel it with a DELETE request:

curl -sS \
  -H "Authorization: Bearer $ECHTPOST_TOKEN" \
  -X DELETE \
  "https://api.echtpost.de/v2/cards/a1b2c3d4-0000-0000-0000-111122223333"

This returns 202 Accepted — cancellation is asynchronous. If the card is already past the cancelable window, you'll get a 409 Conflict.

Handling errors

All errors use Content-Type: application/problem+json. Always match on the type URI — the detail field is a human-readable, imperative hint telling you exactly what to fix before retrying.

Example error response:

{
  "type": "https://api.echtpost.de/v2/errors/text-does-not-fit",
  "title": "Message does not fit on the card",
  "status": 422,
  "detail": "Shorten the message or reduce the font size; 1 line overflows.",
  "instance": "/v2/cards",
  "request_id": "req-abc123"
}

Optional: get notified when the card is sent

Add a notification object to the create request:

"notification": {
  "type": "on_send",
  "email": "ops@acme.de",
  "send_on": "send"
}

Full reference

• Interactive API explorer: api.echtpost.de/v2/docs
• OpenAPI 3.1 spec: GET https://api.echtpost.de/v2/openapi.json
• Account & API keys: my.echtpost.de

EchtPost MCP server — AI consumer guide

This guide is for developers and AI agents connecting to the EchtPost Model Context Protocol (MCP) server. It exposes the same postcard capabilities as the REST API v2 (account, contacts, groups, templates, cards) — but as MCP tools that AI clients (Claude, Mistral, or any MCP-compatible host) can call directly.

If you are integrating from your own backend, prefer the REST API v2 (see the AI consumer guide tab). Use the MCP server when you want an LLM-driven client to send EchtPost postcards as part of a chat or agent workflow.

Endpoint

https://mcp.echtpost.de

Transport: Streamable HTTP (MCP spec 2025-06-18). The MCP server runs on its own subdomain; the OAuth authorization server lives at https://my.echtpost.de (where the user consent screen needs the session).

Authentication

The MCP server accepts two credential types. Use whichever fits your client:

Recommended: OAuth 2.1 (user-delegated access)

Use OAuth when the MCP client acts on behalf of a real EchtPost user — this is the standard for Claude, ChatGPT, and any client that enforces user consent. Tokens are short-lived, scoped to one account, and revocable without touching API keys.

An unauthenticated request returns 401 Unauthorized with a WWW-Authenticate header pointing to the protected-resource metadata document on the MCP server's own origin:

WWW-Authenticate: Bearer realm="EchtPost MCP",
  resource_metadata="https://mcp.echtpost.de/.well-known/oauth-protected-resource"

MCP clients that support OAuth (Claude, ChatGPT) follow the discovery chain automatically:

1. Fetch https://mcp.echtpost.de/.well-known/oauth-protected-resource (RFC 9728) — declares https://my.echtpost.de as the authorization server.
2. Fetch https://my.echtpost.de/.well-known/oauth-authorization-server (RFC 8414) — returns authorization_endpoint, token_endpoint, registration_endpoint, revocation_endpoint, supported scopes, PKCE methods, etc.
3. Walk the Authorization Code + PKCE flow against those endpoints.
4. Attach the resulting token as Authorization: Bearer <token> on subsequent MCP requests.

Dynamic client registration (RFC 7591) — clients can self-register instead of requiring a pre-shared client_id. The exact URL is advertised by the authorization-server metadata as registration_endpoint (currently https://my.echtpost.de/oauth/register).

Key details:

• Grant type: authorization_code with PKCE (S256)
• Scope: mcp (the authorization server also advertises api for REST API access — request the scope that matches your use case)
• Token format: opaque Bearer token
• Tokens resolve to an account-scoped user; revoking the token, removing the user from the account, or deactivating the account all take effect immediately
• Users with multiple accounts see an account picker during authorization

Alternative: API key (server-to-server)

Use an API key for server-side scripts, automations, or clients that don't support OAuth (e.g. Mistral). Two header formats are accepted:

Create keys in the EchtPost web app under Account → API keys. Keys are tied to a single account and user; both must be active.

Sandbox. A key created in sandbox mode (ep_test_ prefix, see llm_guide.md) puts the whole connection into sandbox: every tool reads and writes sandbox records only, and create_card produces a card that is neither billed nor printed. Motives and templates are shared between the modes.

OAuth connections are always live — the mode travels in the key prefix, and an OAuth token has none. To test through an OAuth client, address a card to yourself and cancel it with cancel_card before it goes to print.

Connecting an MCP client

Claude (Desktop / Code / API) — OAuth (recommended)

Claude supports OAuth-based MCP servers natively. Just provide the URL — Claude handles discovery, registration, and the consent flow:

{
  "mcpServers": {
    "echtpost": {
      "type": "http",
      "url": "https://mcp.echtpost.de"
    }
  }
}

On first connection Claude will open a browser for you to log in and authorize access. No API key needed.

Claude Code (CLI):

claude mcp add --transport http echtpost https://mcp.echtpost.de

Claude Code (CLI) — API key

If you prefer a static key (no browser consent flow):

claude mcp add --transport http echtpost https://mcp.echtpost.de \
  --header "Authorization: Bearer $ECHTPOST_API_KEY"

Claude API / Desktop config — API key

{
  "mcpServers": {
    "echtpost": {
      "type": "http",
      "url": "https://mcp.echtpost.de",
      "headers": {
        "Authorization": "Bearer YOUR_ECHTPOST_API_KEY"
      }
    }
  }
}

Mistral

Provide the URL https://mcp.echtpost.de. Mistral reads the WWW-Authenticate: Bearer header from the 401 response and prompts for a key automatically.

Quick connectivity check (raw HTTP)

# 401 — confirms the server is reachable and auth is required
curl -i https://mcp.echtpost.de

# Tool list — confirms your key works (API key or OAuth token)
curl -sS \
  -H "Authorization: Bearer $ECHTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST https://mcp.echtpost.de \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Tools

All tools resolve through the same business logic as the REST API v2, so concepts such as recipients, fonts, delivery dates, and error types behave identically. Where this guide is silent, fall back to the AI consumer guide tab on this page — it is the canonical reference.

Account

Contacts

Groups

Templates

Motives

Cards

Temporary motives uploaded through the REST API can be used as motive_id in create_card. The returned card includes asset_expires_at: for temporary motives it defaults to seven days after deliver_at, and clients may set an ISO date between seven and ninety days after deliver_at. EchtPost purges the temporary image assets only after every referencing card has passed its retention window and no card still needs the image for print; the motive row and card/print history stay available. Permanent motives reject asset_expires_at.

Recipient specification

create_card and create_card_from_template accept three recipient sources, all combinable; at least one must yield ≥ 1 contact:

• recipient_ids — array of existing contact IDs, e.g. [12, 34]
• group_ids — array of contact group IDs; all members are added
• recipients — inline address objects (each needs last_name, street, zip, city, country_code; optional first_name, gender, title, company_name, department, state_code, greeting_style, custom_salutation, external_id)

Group membership on update_contact

• group_ids — replaces memberships with exactly this list (pass [] to clear all groups)
• group_names — adds the contact to each named group, creating it if missing
• Omit both to leave groups unchanged

Fonts

Colors: black (default) or blue.

Delivery dates

The deliver_at field accepts:

Must be a weekday and not a printer holiday. Natural-language strings like "in two days" are not accepted — use the numeric hyphenated form.

Errors

Tool errors are returned as MCP tool results with isError: true and a human-readable message in the content text. The underlying error categories mirror the REST API's stable error types — for example a message that overflows the card maps to the same overflow shape and includes a suggested_font_size. See the REST AI consumer guide's Stable error types section for the full list.

401 Unauthorized is terminal: the credential (API key or OAuth token) is missing, invalid, expired, or the account/user is deactivated. For OAuth tokens, the client should attempt a token refresh or re-run the authorization flow. For API keys, verify the key in the EchtPost web app.

Rate limits

Rate limits are shared with the REST API v2 and applied per credential (API key or OAuth token). The strict limits (10/min on card creation, 30/min on preview_fit) apply to the matching MCP tools (create_card, create_card_from_template, preview_fit). Spread bulk runs over time or batch recipients with recipient_ids / group_ids on a single card call.

See also

• REST AI consumer guide — recipients, fonts, error types, card lifecycle (canonical reference).
• OpenAPI spec — machine-readable schema for the equivalent REST endpoints.