Quickstart
Create a workspace API key and make your first Postforge API request.
1. Create an API key
In the Postforge dashboard, open your workspace and go to Developers → API keys. Owners and
admins create keys; pick the scope your integration needs (read is enough to start). The key is
shown once: copy it and store it as a secret.
2. Call the API
Every request carries the key as a bearer token. The key belongs to one workspace, so you never name the workspace yourself.
curl https://api.postforge.dev/v1/orders?pageSize=10 \
-H "Authorization: Bearer $POSTFORGE_API_KEY"Lists answer one page at a time:
{
"items": [
{
"id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
"number": "#1001",
"placedAt": "2026-10-14T13:05:22.000Z",
"financialStatus": "paid",
"total": { "amount": 4950, "currency": "EUR" },
"locale": "nl-NL"
}
],
"total": 128,
"page": 1,
"pageSize": 10
}3. Write safely
Writes need a write key. Send an Idempotency-Key so a retry after a timeout can never apply the
same change twice. This unsubscribes a profile's email address, with your own form as proof:
curl -X PUT https://api.postforge.dev/v1/profiles/$PROFILE_ID/consent/email \
-H "Authorization: Bearer $POSTFORGE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"state": "unsubscribed", "proof": {"reference": "acme.com preference form"}}'4. Handle problems
Errors are problem details: show detail to people, branch on type
and code in code.
type Problem = { type: string; title: string; status: number; detail?: string; code?: string }
if (!response.ok) {
const problem: Problem = await response.json()
if (problem.code === 'scope') {
// This key can’t do it: use a key with a larger scope.
}
throw new Error(problem.detail ?? problem.title)
}{
"type": "https://postforge.dev/developers/problems/forbidden",
"title": "You can’t do this",
"status": 403,
"detail": "This needs a key with the write scope.",
"code": "scope"
}Next
- Authentication: scopes and key rotation
- Requests: pagination, filters, money and dates
- API reference: every operation