POST/v1/test-runs

Simulate a production run for test items

Moves READY test items (of the organisation, of one Postflow, or the listed ids) through SCHEDULED_FOR_RUN, IN_PRODUCTION, the carrier handoff and COMPLETED (or FAILED with outcome FAILED) in one call, so webhook handlers receive the full sequence. Nothing is printed, charged or handed to a carrier. Test keys and portal members only; live keys are refused.

Scope items.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

postflowIdstringmin length 1

itemIdsarray of stringmin items 1max items 500

outcomeenumdefault "COMPLETED"

COMPLETEDFAILED

limitintegermin 1max 500default 100

Returns

5 fields of the 200 answer

idstringrequired

outcomeenumrequired

COMPLETEDFAILED

countsobjectrequired

4 fields

completedintegerrequired

failedintegerrequired

suppressedintegerrequired

skippedintegerrequired

itemsarray of objectsrequired

2 fields

idstringrequired

statusenumrequired

NEEDS_ATTENTIONSUPPRESSEDHELDPENDING_APPROVALREADYSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

skippedarray of objectsrequired

3 fields

idstringrequired

statusenum or nullrequired

NEEDS_ATTENTIONSUPPRESSEDHELDPENDING_APPROVALREADYSCHEDULED_FOR_RUNIN_PRODUCTIONCOMPLETEDFAILEDCANCELLEDRETURNEDNOT_SENT

reasonenumrequired

not_foundnot_readypostflow_paused

Responses

200Success

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/test-runs \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Idempotency-Key: crm-0062p00001Xyz-signed" \ -H "Content-Type: application/json" \ -d '{ "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "itemIds": [ "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K" ], "outcome": "COMPLETED", "limit": 20 }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.testRuns.simulate({ body: { postflowId: 'pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K', itemIds: [ 'itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K', ], outcome: 'COMPLETED', limit: 20, },, idempotencyKey: 'crm-0062p00001Xyz-signed', });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.test_runs.simulate({ "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "itemIds": [ "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K", ], "outcome": "COMPLETED", "limit": 20, }, idempotency_key="crm-0062p00001Xyz-signed")

{ "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "outcome": "COMPLETED", "counts": { "completed": 1, "failed": 1, "suppressed": 1, "skipped": 1 }, "items": [ { "id": "itm_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "status": "HELD" } ], "skipped": [ { "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "status": "HELD", "reason": "not_found" } ] }

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