POST/v1/postflows/{id}/items

Create an item in a Postflow

Accepted with 202: the item starts HELD, or NEEDS_ATTENTION with warnings when the recipient or variables have content problems (repair in the portal or through PATCH), or SUPPRESSED when the address is on the suppression list. Test keys create test items.

Scope items.writeIdempotent with a keyRate limit class itemCreate

Path parameters

idstringrequired

Headers

Idempotency-Keystringmax length 255

Up to 255 characters, scoped to the organisation and the endpoint, kept for 24 hours: a repeat with the same body replays the stored response with Idempotent-Replayed: true (API-004).

Body

recipientobjectrequired

6 fields

namestringmax length 200

addressLine1stringmax length 200

addressLine2stringmax length 200

postalCodestringmax length 20

citystringmax length 120

countrystringmax length 40

variablesobjectdefault {}

sendDatedate

externalIdstringmin length 1max length 200

metadataobject

advertisingCategorystring or null

Returns

29 fields of the 202 answer

idstringrequired

statusenumrequired

NEEDS_ATTENTIONSUPPRESSEDHELDPENDING_APPROVALREADYSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

customerStatusenumrequired

NEEDS_ATTENTIONSUPPRESSEDSCHEDULEDIN_PRODUCTIONHANDED_TO_CARRIERCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

needsAttentionbooleanrequired

warningsarray of objectsrequired

3 fields

codeenumrequired

address_invalidpostal_code_invalidhouse_number_missingcity_missingcountry_not_supporteddestination_not_supportedvariable_missingvariable_type_invalidvariable_too_longimage_fetch_failedimage_resolution_lowtext_overflowexpression_invalidlate_delivery_expectedwaiting_for_fundssuppressedcarrier_codes_missingexcluded_from_run

fieldstringrequired

messagestringrequired

sourceenumrequired

POSTFLOWPOSTBATCHSAMPLE

postflowIdstring or nullrequired

postbatchIdstring or nullrequired

templateVersionIdstring or nullrequired

productobjectrequired

4 fields

idstringrequired

specificationIdstringrequired

finishstringrequired

destinationstringrequired

advertisingCategorystring or nullrequired

isTestbooleanrequired

isSamplebooleanrequired

recipientobject or nullrequired

6 fields

namestringrequired

addressLine1stringrequired

addressLine2string or nullrequired

postalCodestringrequired

citystringrequired

countrystringrequired

variablesobject or nullrequired

sendDatedate or nullrequired

externalIdstring or nullrequired

metadataobject or nullrequired

createdAtdate-timerequired

updatedAtdate-timerequired

readyAtdate-time or nullrequired

scheduledAtdate-time or nullrequired

handedToCarrierAtdate-time or nullrequired

completedAtdate-time or nullrequired

failedAtdate-time or nullrequired

cancelledAtdate-time or nullrequired

anonymisedAtdate-time or nullrequired

qrobject or nullrequired

4 fields

shortUrlstringrequired

scanCountintegerrequired

firstScannedAtdate-time or nullrequired

lastScannedAtdate-time or nullrequired

priceobject or nullrequired

11 fields

idstringrequired

unitPriceCentsintegerrequired

listUnitPriceCentsintegerrequired

currencystringrequired

discountPercentnumber or nullrequired

tierQuantityintegerrequired

tierBasisenumrequired

postbatchrolling30d

basisQuantityintegerrequired

vatTreatmentstringrequired

vatRateintegerrequired

computedAtdate-timerequired

Responses

202Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

409A request with this Idempotency-Key is still in progress (idempotency_in_progress)

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

Request

curl -X POST https://api.postbuddy.nl/v1/postflows/pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K/items \
  -H "Authorization: Bearer $POSTBUDDY_API_KEY" \
  -H "Idempotency-Key: crm-0062p00001Xyz-signed" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": {
      "name": "Sanne de Vries",
      "addressLine1": "Oudegracht 112",
      "postalCode": "3511 AX",
      "city": "Utrecht",
      "country": "NL"
    },
    "variables": {
      "first_name": "Sanne"
    }
  }'

import { PostBuddyClient } from '@postbuddy/sdk';

const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! });

const result = await client.postflows.createItem('pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K', {
  body: {
    recipient: {
      name: 'Sanne de Vries',
      addressLine1: 'Oudegracht 112',
      postalCode: '3511 AX',
      city: 'Utrecht',
      country: 'NL',
    },
    variables: {
      first_name: 'Sanne',
    },
  },,
  idempotencyKey: 'crm-0062p00001Xyz-signed',
});

import os
from postbuddy import Client

client = Client(os.environ["POSTBUDDY_API_KEY"])

result = client.postflows.create_item("pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K", {
    "recipient": {
        "name": "Sanne de Vries",
        "addressLine1": "Oudegracht 112",
        "postalCode": "3511 AX",
        "city": "Utrecht",
        "country": "NL",
    },
    "variables": {
        "first_name": "Sanne",
    },
}, idempotency_key="crm-0062p00001Xyz-signed")

Response

{
  "id": "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "status": "HELD",
  "customerStatus": "SCHEDULED",
  "needsAttention": false,
  "warnings": [],
  "source": "POSTFLOW",
  "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "postbatchId": "pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "templateVersionId": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "product": {
    "id": "prd_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "specificationId": "psp_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "finish": "silk",
    "destination": "Example"
  },
  "advertisingCategory": "Example",
  "isTest": false,
  "isSample": false,
  "recipient": {
    "name": "Sanne de Vries",
    "addressLine1": "Oudegracht 112",
    "addressLine2": "2nd floor",
    "postalCode": "3511 AX",
    "city": "Utrecht",
    "country": "NL"
  },
  "variables": {
    "first_name": "Sanne"
  },
  "sendDate": "2026-11-02",
  "externalId": "crm-0062p00001Xyz",
  "metadata": {
    "crmRecordId": "0062p00001Xyz"
  },
  "createdAt": "2026-10-16T09:14:02.000Z",
  "updatedAt": "2026-10-16T09:14:02.000Z",
  "readyAt": "2026-10-16T09:14:02.000Z",
  "scheduledAt": "2026-10-16T09:14:02.000Z",
  "handedToCarrierAt": "2026-10-16T09:14:02.000Z",
  "completedAt": "2026-10-16T09:14:02.000Z",
  "failedAt": "2026-10-16T09:14:02.000Z",
  "cancelledAt": "2026-10-16T09:14:02.000Z",
  "anonymisedAt": "2026-10-16T09:14:02.000Z",
  "qr": {
    "shortUrl": "https://example.com/r/Fq3ZtR8w",
    "scanCount": 3,
    "firstScannedAt": "2026-10-16T09:14:02.000Z",
    "lastScannedAt": "2026-10-16T09:14:02.000Z"
  },
  "price": {
    "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
    "unitPriceCents": 1250,
    "listUnitPriceCents": 1250,
    "currency": "EUR",
    "discountPercent": 3,
    "tierQuantity": 1,
    "tierBasis": "postbatch",
    "basisQuantity": 1,
    "vatTreatment": "Example",
    "vatRate": 1,
    "computedAt": "2026-10-16T09:14:02.000Z"
  }
}

{
  "type": "https://docs.postbuddy.nl/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Not found",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}

{
  "type": "https://docs.postbuddy.nl/errors/idempotency_in_progress",
  "title": "Request with this idempotency key in progress",
  "status": 409,
  "code": "idempotency_in_progress",
  "detail": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}

{
  "type": "https://docs.postbuddy.nl/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "Validation failed",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "errors": [
    {
      "field": "recipient.postalCode",
      "code": "invalid_string",
      "message": "Invalid postal code"
    }
  ]
}