Postflow quick start

A Postflow is a standing rule: a template, a product finish and destination, and a dispatch strategy that decides when accepted items are released to the next production run. Integrations create items in a Postflow; the platform validates, holds, releases, prints and posts them.

#1. Create the Postflow

The template needs a published version; the product follows from the template.

const postflow = await client.postflows.create({
  body: {
    name: 'Welcome card',
    templateId: template.id,
    finish: 'silk',
    destination: 'NL',
    dispatch: { strategy: 'IMMEDIATE' },
  },
  idempotencyKey: 'crm-postflow-welcome',
});

Strategies: IMMEDIATE releases at the next run, SEND_DATE targets the item's desired delivery date, MIN_COUNT_MAX_WAIT waits for minCount items or maxWaitDays.

Manage the Postflow with postflows.list, postflows.update, postflows.pause (held and ready items stay out of the cutoff while new items are still accepted), postflows.resume (items are re-evaluated at once), postflows.archive (refused while items are held, pending approval or ready unless cancelItems is true) and postflows.stats (counts by status, the next run, the oldest held item, the template version in use and recent items).

#2. Create items

const item = await client.postflows.createItem(postflow.id, {
  body: {
    recipient: {
      name: 'Anna de Vries',
      addressLine1: 'Voorbeeldstraat 12 A',
      postalCode: '1234 AB',
      city: 'Amsterdam',
      country: 'NL',
    },
    variables: { firstName: 'Anna', amount: 12.5 },
    externalId: 'crm-00123',
  },
  idempotencyKey: 'crm-00123-welcome',
});
console.log(item.status, item.warnings);

The API answers 202 with the item:

• HELD: accepted and waiting for the Postflow to release it. The recipient is returned normalised.
• NEEDS_ATTENTION: the recipient or variables have a content problem (warnings[] lists each with its field); request-level problems such as a malformed body still answer 422. Repair in the portal or through PATCH /v1/items/{id}.
• SUPPRESSED: the address is on the organisation's suppression list; nothing is printed or billed.

Test keys create test items that follow the full lifecycle without production. Item creation has its own rate limit class (itemCreate, 3,000 per minute per key).

#3. Release and approval

Held items are released by the dispatch evaluator: at once for IMMEDIATE, for the run that delivers by the send date for SEND_DATE (an item no run can serve in time goes with the next run and carries late_delivery_expected), and at the minimum count or maximum wait for MIN_COUNT_MAX_WAIT. With requiresApproval (or the organisation default) released items wait as PENDING_APPROVAL until an Approver releases them:

await client.postflows.approve(postflow.id, { body: {} }); // or { body: { itemIds: [...] } }

Approvers are reminded 24 hours before the cutoff while items are pending. Pausing a Postflow keeps its items out of the cutoff; resuming re-evaluates them at once.

#4. Follow items

const page = await client.items.list({
  query: { filter: { postflowId: postflow.id, status: 'HELD' } },
});
const history = await client.items.events(item.id);

GET /v1/items filters on status, Postflow, test flag, external id, created and send dates and a search over name, postal code and external id. Status changes arrive as webhook events (item.ready, item.scheduled, item.in_production, item.handed_to_carrier, item.completed) once deliveries start.

#5. Repair, cancel, previews and the PDF

• PATCH /v1/items/{id} repairs a NEEDS_ATTENTION item with a new recipient or variables; it is validated again and re-enters the queue. A HELD item accepts a new send date, external id and metadata. POST /v1/items/bulk-repair applies one patch to up to 500 items.
• POST /v1/items/{id}/cancel cancels until the run cutoff; after the cutoff the item is locked for production (item_locked_for_production).
• GET /v1/items/{id}/preview?side=front&dpi=150 renders the item through a render request (poll until READY for the signed image URLs); GET /v1/items/{id}/pdf answers a ten minute signed URL once the production PDF exists. Both stop after anonymisation.
• Items that stay in NEEDS_ATTENTION trigger reminders to Editors after 3 and 14 days (configurable per organisation); nothing is cancelled automatically.
• Owners and Admins export items, the suppression list (CSV) and templates with assets (zip) with POST /v1/exports; the download link lives 24 hours.