API Flow

An API flow is PostPal's automated sending engine for recipients submitted programmatically. Instead of sending an existing audience, a flow continuously receives individual entries through the PostPal API and groups them into recurring mailings.

How a flow works:

• You submit recipients through the API; they are collected as entries in the flow (states: pending, batched, skipped, failed).
• Optionally, you submit recipient-specific Markdown content through content when the linked design defines Markdown areas.
• Optionally, you submit recipient-specific QR values through qr_codes when the linked design defines QR codes with API field names.
• With Plus, supply individual pictures through images when the design defines API images. Every image field name of the shippable variants is then required, starting with the first available default name image_url_1.
• In a weekly trigger window, PostPal forms a batch from due entries and creates a postcard mailing.
• Billing is based on the actual batch size.

A new flow is a draft: PostPal saves it automatically while you set it up, and requests to it are rejected with 422. “Flow erstellen” makes it active; from then on it is active or paused and needs a linked postcard design. If credit is not sufficient for a batch, the flow remains configured and open entries are retried during the next run. Designs with Markdown areas or API images in shippable variants or variants needed by pending entries are reserved for API flows and are not available in regular campaigns.

API images: PostPal downloads public HTTPS image URLs without redirects before creating an entry and checks the file and print resolution. The image is fitted whole inside its rectangular frame using Fit; the uploaded Studio example is never printed as a fallback. Even image-only API designs are rendered per recipient. See the REST API guide for formats, limits and errors.

The image contract is fixed from the first API entry, even after that entry has been processed. Added or removed API images, renamed fields and design switches with a different image contract are rejected. A 0% variant without pending entries is excluded and may still be edited.

Numbers at the start of a Markdown line are preserved as submitted, including dates such as 20. Mai 2026 and 30. Mai 2026. Numbered lists are not automatically renumbered.

Markdown content is bound to the API field names defined in the design. In v1, every Markdown area is required and unknown keys are rejected. PostPal only accepts the supported Markdown subset and checks that the text physically fits into the defined area before storing the entry.

The example content stored for a Markdown area in the Studio is only a design preview. It is not printed as fallback content for API flows. If the design has a Markdown area with the API field name personal_note, the API request must submit content.personal_note. Line breaks are written normally in the editor, but in the API JSON string they must be sent as \n.

QR values are also bound to the API field names defined in the design. A QR code is part of the API contract only when it is created as an API QR in the Studio. URL QRs store their target URL in the design and are not supplied through qr_codes. In v1, every API QR field is required and unknown keys are rejected. The value under qr_codes.<field_name> is the complete QR target URL. PostPal checks before storing the entry that this URL is a valid HTTP(S) URL and fits into a QR code. If the design has an API QR with the API field name voucher_url_1, the API request must submit qr_codes.voucher_url_1 as a complete scan-ready URL.

Emoji in content fields and in recipient data such as the first name are printed as colour Google Noto graphics, in the preview exactly as in the final print PDF. The emoji catalogue ships with PostPal and cannot yet contain very recent characters. When such a character arrives, the entry preview states that it contains an unsupported emoji — retrying does not help there. In print the same rule applies as for other single-recipient failures: only the affected recipient is skipped and reported, while every other recipient prints normally.

The technical API reference lives in the official API documentation, and in machine-readable form in the OpenAPI file.

The available design formats, materials, finishes and payment methods in the flow form follow the published price list, including their names and discounts. Formats must also be supported by the Postcard Studio editor. Without a published price list you can start a draft but cannot complete flow creation.