API Flow
An API flow is PostPal's automated sending engine: you submit recipients programmatically through the API, PostPal collects them and forms a batch in a recurring weekly trigger window, then sends it as a postcard mailing. Billing is based on the batch size that is actually sent. Every flow needs a linked postcard design. Designs can define Markdown areas whose content is supplied individually per API request through `content`. QR codes must be created as API QRs in the Studio when their value should be supplied per request through `qr_codes`; these `qr_codes` values must be complete scan-ready HTTP(S) URLs. Designs with Markdown areas are API-flow designs and are not offered in regular campaigns.
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
contentwhen the linked design defines Markdown areas. - Optionally, you submit recipient-specific QR values through
qr_codeswhen the linked design defines QR codes with API field names. - 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 flow is either 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 are reserved for API flows and are not available in regular campaigns.
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.
The technical API reference is available on the developer page at
https://app.getpostpal.com/developers/api; the machine-readable OpenAPI
specification is available at
https://app.getpostpal.com/developers/api/openapi.json.
Frequently asked questions
How is an API flow different from a normal campaign?
A campaign targets an existing audience. A PostPal API flow receives individual recipients continuously through the API and automatically groups them into recurring mailings, which is useful for event-based postcards.
How is an API flow billed?
PostPal bills an API flow by the actual batch size, not by a minimum quantity. The trigger threshold only controls when a weekly batch is formed.
What happens if my credit is not enough for a batch?
The flow remains configured. Open entries are retried in the next weekly run, and you are notified about the missing credit.
Do I need a design for an API flow?
Yes. Every API flow needs a linked postcard design before it can create mailings.
Can an API flow print longer individual text per recipient?
Yes, when the design contains Markdown areas. The API request must then send the matching content keys. PostPal checks syntax and physical fit synchronously before creating a flow entry.
Can an API flow print individual QR links per request?
Yes, when the design contains API QRs with API field names. The API request must then send the matching qr_codes keys as complete HTTP(S) URLs. URL QRs are configured in the design and are not part of the API contract. Unknown, missing, empty or non-fitting QR values are rejected with 422.
Where can I find the technical API documentation?
The developer page is available at https://app.getpostpal.com/developers/api. The machine-readable OpenAPI specification is available at https://app.getpostpal.com/developers/api/openapi.json.