REST endpoints v1

The REST API v1 is the programmatic interface for technical integrations.

Important endpoints:

• POST /api/v1/campaigns - create campaigns programmatically.
• POST /api/v1/postcards - submit postcard requests.

Every request needs an account API token. Check payload structure and required fields precisely in these resources:

• Official API documentation
• OpenAPI file
• Postman collection

When the linked API flow design contains Markdown areas, POST /api/v1/postcards also expects a content object. Its keys must exactly match the Markdown API field names defined in the design. Supported syntax is limited to paragraphs, line breaks, bold, italic, bullet lists and numbered lists. Unsupported syntax, missing or unknown keys, and content that does not fit the area are rejected with 422; fit errors include additional details in meta.markdown_fit_errors.

Example text from the Studio is not an API fallback. API clients must always send Markdown content in the content object. Normal editor line breaks are sent as \n in the JSON payload, for example "Hallo **Max**,\n\n- Persönlicher Vorteil".

Emoji are allowed in content fields and in recipient data such as to.first_name, and are printed as colour Google Noto graphics. The emoji catalogue ships with PostPal and cannot yet contain very recent characters. Such a character does not cause a 422 on the request: it only surfaces at render time. The entry preview then points it out, and in print only the affected recipient is skipped and reported.

When the linked API flow design contains API QRs with API field names, POST /api/v1/postcards also expects a qr_codes object. Its keys must exactly match the QR API field names defined in the design. Each value must be a non-empty string with at most 2048 characters and must already be the complete scan-ready HTTP(S) URL. Missing, unknown, empty or non-fitting QR values are rejected with 422; fit errors include additional details in meta.qr_fit_errors. URL QRs store their target URL in the design and are not submitted in the qr_codes object.

A simple qr_codes fragment looks like this:

{
  "qr_codes": {
    "voucher_url_1": "https://example.com/voucher/1",
    "voucher_url_2": "https://example.com/voucher/2"
  }
}

Rate limit: Each account API token may call POST /api/v1/postcards up to 600 times per minute and POST /api/v1/campaigns up to 60 times per minute. Exceeding the limit returns status 429 with the X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After headers, the latter indicating how many seconds to wait before retrying. Check the API logs for the history and exact error message.