API v1
PostBuddy API
Send printed mail from your own software. Create items, follow their status and receive webhooks when they reach PostNL.
https://api.postbuddy.nl/v1Create an item
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")PostBuddyClient.CreateItemRequest request = new PostBuddyClient.CreateItemRequest();
request.postflowId = 'pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K';
request.recipientName = 'Sanne de Vries';
request.addressLine1 = 'Oudegracht 112';
request.postalCode = '3511 AX';
request.city = 'Utrecht';
request.variables.put('first_name', 'Sanne');
request.idempotencyKey = 'crm-0062p00001Xyz-signed';
PostBuddyClient.Result result = PostBuddyClient.createItem(request);
System.debug(result.status); // HELD
AuthenticationAPI keys, scopes and live or test mode.
WebhooksStatus changes for every item, signed.
SalesforceSend from a Flow, write status back.
SDKsTypeScript and Python, from the OpenAPI spec.
PostBuddy sends printed postcards and letters through an API: you keep templates with variables, hand us recipients and variables per item, and the platform renders, prints and posts. This site covers the public API (/v1), the SDKs for TypeScript and Python, webhooks and the error codes.
Start here
- Authentication: API keys, scopes, test and live mode.
- Templates quick start: create a template, publish a version, render a preview and a proof PDF.
- Fonts: the library, every Google Font through PostBuddy and your own uploads.
- Postflow quick start: a standing rule that releases items from your integration to the next run.
- Postbatch quick start: a one-off mailing from a CSV with the review, the quote and the approval.
- Idempotency, pagination and filters, rate limits and errors: the conventions every endpoint follows.
- SDKs:
@postbuddy/sdkon npm andpostbuddyon PyPI. - Webhooks and the event catalogue.
- API reference: every operation, generated from the OpenAPI document.
- Status and support:
GET /v1/status, the status page, maintenance and how to get help.