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 theirid(theflow_id), destination country (country) and expected keys (fields), plus collected postcards (entries) and runs (processing). Drafts are returned withstatus=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.
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.