Glossary

All-or-nothing — Campaign creation validates every recipient before any write. One bad row means nothing is created: no list, no recipients, no campaign. There is no partially mailed batch to reconcile.

Campaign — One send: a design plus an audience, producing one printed document per recipient. The only object in the API with physical output. Cannot be updated, deleted or cancelled. See Campaigns.

Content source — Where a campaign's design comes from. Exactly one per campaign: templateId (recommended) or a pdf file part. Raw editor content is accepted by the endpoint but is not supported for API integrations.

Cursor — An id used to page through a collection. Because ids are time-ordered, cursor paging stays stable while rows are being inserted. See Pagination.

Custom field — Any recipient attribute beyond the five required address fields, used to personalise the mail through a template placeholder. Maximum 16 per recipient; keys are alphanumeric plus underscore, ≤64 characters.

Field schema — A list's set of accepted custom fields. Unlocked until the first recipient is added, then locked and fixed. Read it with GET /api/v1/lists/:listId/schema. See Lists & recipients.

Idempotency-Key — A header on campaign create, 1–255 characters, that makes a retry return the original campaign (200) instead of printing a second batch (201). The payload is not compared. See Idempotency.

Implicit list — The list created for you when a campaign carries recipients or a recipientsFile. Named after the campaign, and a normal reusable list afterwards.

List — A named group of recipients. Append-only over the API, and deleted after 90 days without activity.

Locked schema — See field schema. Once locked, every recipient added must conform; an unexpected custom field is a 422.

Missing-value policy — What happens when a row omits a custom field the schema expects: skip (drop the row, the default), fail (reject the request), or default (substitute a value). Only settable while the schema is unlocked.

Presigned URL — A short-lived link to a stored template asset (frontContentUrl, logoUrl, images[].url). Use immediately; never store or share. Re-request the template for fresh ones.

Progress — 0–100 on a campaign, indicating how far rendering and dispatch have got.

Recipient — One postal address. Requires name, street, postCode, postTown and country. Cannot be updated or deleted over the API.

Recipient source — Where a campaign's audience comes from. Exactly one per campaign: listId, recipients (inline, ≤5000), or a recipientsFile part with a mapping.

Reserved zones — Areas of the front page where the platform draws the destination address, return address and postage band. Artwork underneath is printed over. Treat the top 77 mm as reserved. See PDF campaigns.

Return address — The sender text printed on every mail. Inherited from the template, overridable per campaign, and never empty — a platform default applies if nothing is supplied.

Skipped — A row deliberately not imported: a required field was blank, or a custom field was missing with policy skip. Not an error. Reported as skipped alongside imported, with a 200 status. A fully-skipped import returns { "imported": 0, "skipped": N }.

Slug — The permanent, globally unique identifier in a QR code's printed URL (/api/r/{slug}). Derived from the campaign name plus a random suffix. Can never be changed, because it is printed on paper.

Snapshot template — The internal, immutable copy of the content taken when a campaign is created. It is the templateId in a campaign response — not the template you passed in — and fetching it returns Template not found. It exists so editing your template cannot alter mail already sent.

Template — The design of your mail, authored and visually approved in the web app. Read-only over the API (templates:read). See Templates.

Tracking URL — The address every QR code encodes, {baseUrl}/api/r/{slug}, whatever trackingEnabled is set to. Returned only by POST /api/v1/qr-codes and inside the campaign create response; compose it from slug elsewhere.

trackingEnabled — Controls only whether each QR scan is recorded. It does not change what is printed: the code encodes the tracking URL either way, so the destination is retargetable regardless. Recorded scans cannot currently be read back through the API or the web app.

Unlocked schema — See field schema. A list with no recipients yet; the first add defines and freezes the custom fields.

Validation issue — A row-level error in a 422 body: { row, field, issue, message }. row is a 1-based data row index with the header excluded. issue is one of unexpected_field, missing_field, missing_required, duplicate_key.