EN
Open PostPal app
API

REST endpoints v1

The PostPal REST API v1 provides production endpoints for programmatic campaigns and postcards. The most relevant endpoints are currently POST /api/v1/campaigns, GET /api/v1/flows and POST /api/v1/postcards. Every request needs a valid account API token and is recorded in the API logs. Postcard requests for API flows can also include design-bound Markdown content, API QR values and API images. Each account API token is limited to 600 postcard and 60 campaign requests per minute; exceeding the limit returns status 429. You can use the official API documentation, the OpenAPI file and the Postman collection.

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

Important endpoints:

  • POST /api/v1/campaigns - create campaigns programmatically.
  • GET /api/v1/flows - list active and paused API flows with their id (the flow_id), destination country (country) and expected keys (fields), plus collected postcards (entries) and runs (processing). Drafts are returned with status=draft; a page holds up to 250 flows (page, links.next).
  • POST /api/v1/postcards - submit postcard requests.

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

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 Design Editor 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".

Destination country: The recipient in to.country must be the destination country of the API flow. For a flow whose destination is Austria the value is AT. Other countries are rejected with 422. The sender in from.country is not affected.

{
  "flow_id": "FLOW_ID",
  "to": {
    "first_name": "Max",
    "address_line1": "Musterstraße 42",
    "zip": "1010",
    "city": "Wien",
    "country": "AT"
  }
}

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"
  }
}

When the Plus design contains API images, an images object is also required. It must contain exactly the image field names of all shippable variants; the object is prohibited without API images. The first automatically allocated name is usually image_url_1:

{
  "images": {
    "image_url_1": "https://example.com/image/1"
  }
}

Each value is a non-empty public HTTPS URL without redirects or credentials, up to 2048 characters. PostPal downloads the image before creating the entry and verifies that it fully decodes as PNG, JPEG or WebP. The limits are 20 MB, 16 megapixels and at least 300 dpi in every print frame using that field. All images of one request together may total at most 50 MB. Unknown or missing keys, disallowed URLs, invalid images and insufficient resolution return 422; resolution errors also appear in meta.image_resolution_errors. The whole image is centred proportionally inside its rectangular frame (Fit/contain). Remaining space stays empty; the image is neither cropped nor stretched. The example uploaded in the Design Editor is exclusively a preview.

Rate limit: Each account API token may call POST /api/v1/postcards up to 600 times per minute, POST /api/v1/campaigns and GET /api/v1/flows up to 60 times per minute each. 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.

Open in PostPal

Frequently asked questions

Which REST endpoints are available?

The v1 API provides endpoints for campaigns, API flows and postcards: POST /api/v1/campaigns, GET /api/v1/flows and POST /api/v1/postcards.

How do I find the flow_id for POST /api/v1/postcards?

Use GET /api/v1/flows. Without parameters it lists the active and paused API flows of your account. For each flow it returns id (the flow_id), name, status, country (the only recipient country) and fields: the keys the design expects under content, qr_codes and images. Live and test tokens both work; the limit is 60 requests per minute.

How do I get drafts and further pages from GET /api/v1/flows?

Drafts are returned only with the status parameter, for example status=draft or status=draft,active,paused; they have accepts_postcards false because they do not accept postcards yet. A page holds up to 250 flows. Read further pages with page, or follow links.next until it is null. An unknown status or an invalid page returns 422.

Can I see through the API how many postcards a flow has collected and when it runs?

Yes. GET /api/v1/flows returns, per flow, the number of collected (pending), processed (batched) and failed postcards under entries, and the minimum quantity (trigger_threshold), the next run (next_processing_at) and the last run (last_processed_at) under processing. A run creates a mailing only when the collected postcards reach the minimum quantity. With a test token these values refer to test postcards. meta holds the number of all flows per status (status_counts) and the earliest next run of the active flows.

How do I authenticate API requests?

Use an account API token from the PostPal API settings.

Is there machine-readable documentation?

Yes. The official API documentation, the OpenAPI file and the Postman collection are available.

Can POST /api/v1/postcards include longer individual text?

Yes, when the linked API flow design defines Markdown areas. The matching content keys must be submitted; mismatched, missing or overflowing content is rejected with 422.

Which country can POST /api/v1/postcards send to?

Only to the destination country of the API flow. Possible destinations are Germany (DE), Austria (AT), the Netherlands (NL), Switzerland (CH), Italy (IT) and France (FR). The recipient in the to.country field must be the flow's destination country, as the code (DE) or a common name (Deutschland, Germany); other countries are rejected with 422. The sender (from) is not affected.

Can POST /api/v1/postcards include individual QR targets?

Yes, when the linked API flow design defines API QRs with API field names. The matching qr_codes keys must be submitted as complete HTTP(S) URLs. URL QRs are configured in the design and are not submitted in the qr_codes object.

Can POST /api/v1/postcards include individual images?

Yes, when the Plus design defines API images. Send exactly the image field names of every shippable variant in the images object, for example image_url_1. Each value must be a publicly reachable HTTPS URL without redirects. PNG, JPEG and WebP are fully decoded before acceptance; the limits are 20 MB, 16 megapixels and at least 300 dpi at the printed size, and at most 50 MB for all images of one request together. Missing or unknown keys, invalid files and insufficient resolution return 422. The image is fitted whole inside its frame using Fit; the Design Editor example is never printed as a fallback.

Can I send emoji in content fields and recipient data?

Yes. Common Unicode emoji are printed as colour Google Noto graphics and never as a question mark. The emoji catalogue ships with PostPal and cannot yet contain very recent characters; such a value is not rejected on the request, but the entry preview points it out, and in print only that one recipient is skipped and reported.

In which language does the API answer errors?

In English, like the API documentation. This applies to every endpoint of the v1 API and to the hints in meta, such as suggested_action. Names from the PostPal interface such as “Flow erstellen” appear in a message the way you see them in the app. You also find the messages in the API logs.

Is there a rate limit on the REST API?

Yes. POST /api/v1/postcards allows up to 600 requests per minute per account API token, POST /api/v1/campaigns and GET /api/v1/flows allow up to 60 requests per minute each. Exceeding the limit returns status 429 with the X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After headers.