POST/v1/postbatches

Create a Postbatch

A Postbatch starts in DRAFT with a published template version, the finish and the destination; the product follows from the template. Upload the CSV next.

Scope postbatches.writeIdempotent with a key

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

namestringrequiredmin length 2max length 120

campaignIdstringmin length 1max length 80

advertisingCategorystring or null

templateVersionIdstringrequiredmin length 1max length 40

finishstringrequiredmin length 1max length 40

destinationstringrequiredmin length 2max length 2

Returns

18 fields of the 201 answer

idstringrequired

namestringrequired

campaignIdstring or nullrequired

advertisingCategorystring or nullrequired

statusenumrequired

DRAFTIMPORTINGVALIDATEDPENDING_APPROVALAPPROVEDSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDCANCELLED

templateIdstringrequired

templateVersionIdstringrequired

productobjectrequired

4 fields

idstringrequired

specificationIdstringrequired

finishstringrequired

destinationstringrequired

countsobjectrequired

importIdstring or nullrequired

approvedAtdate-time or nullrequired

targetRunIdstring or nullrequired

priceSnapshotIdstring or nullrequired

itemCountAtApprovalinteger or nullrequired

cancelledAtdate-time or nullrequired

completedAtdate-time or nullrequired

createdAtdate-timerequired

updatedAtdate-timerequired

Responses

201Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

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)

curl -X POST https://api.postbuddy.nl/v1/postbatches \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Idempotency-Key: crm-0062p00001Xyz-signed" \ -H "Content-Type: application/json" \ -d '{ "name": "Welcome card", "templateVersionId": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "finish": "silk", "destination": "Ex" }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.postbatches.create({ body: { name: 'Welcome card', templateVersionId: 'tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K', finish: 'silk', destination: 'Ex', },, idempotencyKey: 'crm-0062p00001Xyz-signed', });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.postbatches.create({ "name": "Welcome card", "templateVersionId": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "finish": "silk", "destination": "Ex", }, idempotency_key="crm-0062p00001Xyz-signed")

{ "id": "pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "name": "Welcome card", "campaignId": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "advertisingCategory": "Example", "status": "COMPLETED", "templateId": "tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "templateVersionId": "tv_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "product": { "id": "prd_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "specificationId": "psp_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "finish": "silk", "destination": "Example" }, "counts": { "key": 1 }, "importId": "ipt_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "approvedAt": "2026-10-16T09:14:02.000Z", "targetRunId": "run_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "priceSnapshotId": "ps_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "itemCountAtApproval": 3, "cancelledAt": "2026-10-16T09:14:02.000Z", "completedAt": "2026-10-16T09:14:02.000Z", "createdAt": "2026-10-16T09:14:02.000Z", "updatedAt": "2026-10-16T09:14:02.000Z" }

{ "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" } ] }