Platform

Contacts, webhooks, keys, and the rest. Every call is on this page.

Keys and permissions

Every call below names the capability it needs. An API key holds a scope: Full access, Sending, Read only, or a custom capability list on paid plans, and no key can manage keys, the team, the workspace or billing. People get the same permissions through their role. What each scope and role covers: API keys and Team.

Contacts

Manage the people you email. Create and update contacts one at a time or import thousands in the background, with standard and custom field values that templates can reference as variables.

List contacts

GET/api/v1/contacts

GET /contacts
curl -X GET 'https://www.unitpost.com/api/v1/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact",
      "id": "id_123",
      "email": "customer@example.com",
      "phone": "string",
      "first_name": "string",
      "last_name": "string",
      "unsubscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z",
      "unsubscribe_reason": "USER",
      "custom_fields": {},
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of the contacts in your workspace, newest-first and cursor-paginated. Each row includes the contact's core fields, its SMS number (phone) and any custom field values. Narrow the list with q (email, first or last name, and 3+ digits of a phone number), status, phone, segment_id (members of a segment; also requires segments:read) and, for a static segment, segment_subscription. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. Use a contact's id (or email) with Retrieve a contact for the full record, add contacts with Create a contact, or bring a list in bulk with Start an async contact import. Requires the contacts:read capability.

Parameters8 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
qstring · querySearch email, first and last name (case-insensitive); with 3 or more digits it also matches the SMS number. At most 200 characters.
statusstring · query`subscribed` or `unsubscribed`: the contact-level marketing opt-out.
phonestring · query`has`: contacts with an SMS number; `none`: without one.
segment_idstring · queryOnly members of this segment: a static segment's members, or the contacts a dynamic segment's filter matches. Also requires `segments:read` (without it, or for an unknown segment, the filter is ignored with a warning; refused under `Unitpost-Strict`).
segment_subscriptionstring · queryWith a static `segment_id`: `subscribed` or `opted_out` of that segment's sends. A dynamic segment has no per-segment opt-out (422).
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200401403404422503

Create a contact

POST/api/v1/contacts

POST /contacts
curl -X POST 'https://www.unitpost.com/api/v1/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace"
  }'
Response · 200
{
  "object": "contact",
  "id": "id_123",
  "email": "customer@example.com",
  "phone": "string",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "unsubscribe_reason": "USER",
  "custom_fields": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Add a single contact to your workspace. Set an email plus any standard or custom field values, and optionally its SMS number (phone). A number is contact data, not consent: record SMS consent with Record SMS consent. Custom fields must already exist (define them with Create a custom contact field). Emails are unique per workspace, so creating one that already exists returns 409 — use Update a contact to change an existing contact, or Start an async contact import to add many at once. A sync that can't know which of the two it is can send update_if_exists: true: the contact that already has the email is updated with the fields in the body instead of the 409, and the response is 200 rather than 201. Requires the contacts:write capability.

Request body7 fields
FieldTypeDescription
emailrequiredstring—
phonestring | null—
first_namestring—
last_namestring—
unsubscribedboolean—
custom_fieldsobject—
update_if_existsboolean`true` updates the contact that already has this email instead of answering `409`: the fields you send are merged onto it (what you leave out is untouched, and `custom_fields` merges key by key), and the response is `200` rather than the `201` of a real create. Default `false`: a duplicate email is a `409`. It is not a way around an opt-out — `unsubscribed: false` on a suppressed address is still refused.
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200201401409422

Export contacts

POST/api/v1/contacts/export

POST /contacts/export
curl -X POST 'https://www.unitpost.com/api/v1/contacts/export' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "subscribed"
  }'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Export contacts to a CSV file, as the Contacts page's Export does: every contact, or the ones the list's filters match (q, status, phone, segment_id, segment_subscription, as on List contacts). It runs as a background job: follow it with Retrieve a job, then fetch the file with Download a job's file. One export runs at a time: another while it runs is a 409 job_in_progress naming it (Location). segment_id also needs segments:read. Requires the contacts:read capability.

Request body5 fields
FieldTypeDescription
qstringFree text: email, first and last name, and with 3+ digits the SMS number.
statusenumsubscribed | unsubscribed—
phoneenumhas | none—
segment_idstringMembers of this segment. Also needs `segments:read`.
segment_subscriptionenumsubscribed | opted_outWith a static `segment_id`: its per-segment opt-out.
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422429502

Set a field on many contacts

POST/api/v1/contacts/set-field

POST /contacts/set-field
curl -X POST 'https://www.unitpost.com/api/v1/contacts/set-field' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Set one custom field to the same value on many contacts, as the Contacts page's Set field does: the contacts you list (contact_ids or emails, up to 1,000, each a contact of this workspace) or every member of a segment (segment_id, however many; also needs segments:read). Send exactly one. key names a field that exists (Create a custom contact field); value is typed against it the way an import types it, and null clears it. With only_empty: true a contact that has its own value keeps it (a contact that only shows the field's default_value has none, so it is filled). Each contact whose value changes gets a contact.updated webhook (changed_fields) and an activity row naming your key; one that already has the value is left as it is. Subscriptions, topics and SMS consent are never touched. It always runs as a background job (202, Location); follow it with Retrieve a job. Listed contacts are checked first: the first that isn't one of yours is a 404 naming it (details), and nothing starts. One bulk operation runs per field at a time, and five bulk contact edits per workspace (409 job_in_progress). Starting one counts against a limit of 30 bulk contact edits a minute per workspace by default (a 429 started nothing; retry after Retry-After). Pass an Idempotency-Key so a retry answers the same job instead of starting another. To give different contacts different values, update each with Update a contact or import them with Start an async contact import. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body6 fields
FieldTypeDescription
keyrequiredstringThe custom field's key (`plan`). It must exist: create it with POST /contact-fields first.
valuerequiredstring | number | boolean | nullThe value, typed against the field the way an import types it: a number field takes `42` or `"42"`, a boolean `true` / `"yes"`, a date an ISO 8601 date. `null` clears the field.
only_emptybooleanDefault false: overwrite every value. True: set it only where the contact has no value of its own (the key is missing or null; a contact that shows the field's default has none). Not with `value: null`.
contact_idsstring[]Contacts of this workspace (`con_…`), up to 1,000.
emailsstring[]Contacts of this workspace by email address, up to 1,000.
segment_idstringEvery member of this segment (`seg_…`), however many. Also needs `segments:read`.
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422429502

Retrieve a contact

GET/api/v1/contacts/{id}

GET /contacts/{id}
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "contact",
  "id": "id_123",
  "email": "customer@example.com",
  "phone": "string",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "unsubscribe_reason": "USER",
  "custom_fields": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single contact and all of its field values. The {id} path segment accepts either the contact's id or its email address, so you can look a contact up without storing our id. Change it with Update a contact, or see which subscription topics it's opted into with List a contact's topic subscriptions. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a contact

PATCH/api/v1/contacts/{id}

PATCH /contacts/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/contacts/con_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "unsubscribed": true
  }'
Response · 200
{
  "object": "contact",
  "id": "id_123",
  "email": "customer@example.com",
  "phone": "string",
  "first_name": "string",
  "last_name": "string",
  "unsubscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z",
  "unsubscribe_reason": "USER",
  "custom_fields": {},
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a contact's standard or custom field values. Top-level fields you omit are left as-is, but custom_fields REPLACES the contact's whole map: read the contact first and send every key you want to keep. phone sets the contact's SMS number (consent is recorded separately); phone: null removes every SMS number it has, with Unitpost-Strict: true (without it the numbers are kept and Unitpost-Warning says so). Unknown keys are ignored. The {id} accepts a contact id or email. To manage a contact's subscription preferences instead, use Set a contact's topic preference. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body5 fields
FieldTypeDescription
phonestring | null—
first_namestring | null—
last_namestring | null—
unsubscribedboolean—
custom_fieldsobject—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring | null—
phonestring | null—
first_namerequiredstring | null—
last_namerequiredstring | null—
unsubscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
unsubscribe_reasonrequiredenum | null—
custom_fieldsrequiredobject—
created_atrequiredstring—
updated_atrequiredstring—
200401404409422

Delete a contact

DELETE/api/v1/contacts/{id}

DELETE /contacts/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/contacts/con_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Permanently delete a contact and its field values. This also removes the contact from every segment it belonged to, including the audience of any unfinished campaign. To stop mailing someone without deleting them, unsubscribe them from a topic with Set a contact's topic preference or add them to your suppression list instead. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404

List a contact's addresses

GET/api/v1/contacts/{id}/addresses

GET /contacts/{id}/addresses
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/addresses' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_address",
      "channel": "string",
      "address": "string",
      "primary": false,
      "status": "queued",
      "country": "string",
      "verified_at": "2026-01-01T00:00:00.000Z",
      "consented_at": "2026-01-01T00:00:00.000Z",
      "consent_source": "string",
      "consent_purpose": "string",
      "carrier_opt_out_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Every address the contact can be reached at: its email addresses and SMS numbers, each with its status and, for a number, its SMS consent state. The contact's phone is its primary number; this lists all of them, including numbers the person texted in from. The full consent history is Get a contact's SMS consent. The {id} accepts a contact id or email. Not paginated. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
channelrequiredstring`email` for an email address, `sms` for a phone number.
addressrequiredstringThe email address, or the phone number in E.164.
primaryrequiredbooleanThe address sends use for this channel.
statusrequiredstring`active`, or why it can't be used (e.g. `opted_out`, `bounced`).
countryrequiredstring | nullISO country of a phone number.
verified_atrequiredstring | null—
consented_atrequiredstring | nullWhen SMS consent was recorded (see `/contacts/{id}/sms-consent`).
consent_sourcerequiredstring | null—
consent_purposerequiredstring | null—
carrier_opt_out_atrequiredstring | nullWhen the carrier last refused a text to this number because it opted out at the carrier. Not a consent record.
created_atrequiredstring—
200401403404

List a contact's recent messages

GET/api/v1/contacts/{id}/activity

GET /contacts/{id}/activity
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/activity' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_activity",
      "message_id": "message_123",
      "channel": "string",
      "direction": "outbound",
      "subject": "Welcome to Acme",
      "status": "queued",
      "campaign_id": "campaign_123",
      "created_at": "2026-01-01T00:00:00.000Z",
      "sent_at": "2026-01-01T00:00:00.000Z",
      "error": "string",
      "error_code": "string"
    }
  ]
}

The contact's most recent messages across channels, newest first: the emails sent to them, and texts both ways. Emails also require emails:read and texts sms:read; without one, those rows are left out. Returns up to limit (1–100, default 25) with no cursor: for the full history page List sent emails or List SMS messages with contact_id. The {id} accepts a contact id or email. Requires the contacts:read capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryHow many recent messages (1–100, default 25).
Response · 200 fields11 fields
FieldTypeDescription
objectrequiredstring—
message_idrequiredstringAn email (`email_…`) or text (`sms_…`) id; read it with its own get operation.
channelrequiredstring`email` or `sms`.
directionrequiredenumoutbound | inbound—
subjectrequiredstring | nullAn email's subject, or the start of a text.
statusrequiredstringThe message's `status` as its own object reports it (`GET /email/{id}`, `GET /sms/{id}`).
campaign_idrequiredstring | null—
created_atrequiredstring—
sent_atrequiredstring | null—
errorrequiredstring | nullTexts only: why it wasn't delivered, in plain words.
error_coderequiredstring | null—
200401403404422

List a contact's segments

GET/api/v1/contacts/{id}/segments

GET /contacts/{id}/segments
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_segment",
      "segment_id": "segment_123",
      "name": "Example",
      "type": "static",
      "subscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The segments the contact is in: static segments by membership, with its per-segment opt-out (subscribed), and dynamic segments whose filter it matches now. Not paginated. From the segment's side, see List segment members. The {id} accepts a contact id or email. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
segment_idrequiredstring—
namerequiredstring—
typerequiredenumstatic | dynamicA dynamic segment's members come from its filter; they can't be added or removed by hand.
subscribedrequiredbooleanWhether this segment's sends reach the contact (a static segment can be opted out of on its own).
unsubscribed_atrequiredstring | null—
200401403404503

List contact imports

GET/api/v1/contacts/imports

GET /contacts/imports
curl -X GET 'https://www.unitpost.com/api/v1/contacts/imports' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_import",
      "id": "id_123",
      "status": "pending",
      "total": 1,
      "imported": 0,
      "updated": 0,
      "skipped": 0,
      "failed": 0,
      "invalid": [
        {
          "row": 0,
          "reason": "string"
        }
      ],
      "error": "string",
      "update_existing": false,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your bulk contact-import jobs, newest-first and cursor-paginated. Each row is a reference to one import and its current progress. Start a new one with Start an async contact import, or drill into a single job with Retrieve a contact import. Requires the contacts:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
200401422

Start an async contact import

POST/api/v1/contacts/imports

POST /contacts/imports
curl -X POST 'https://www.unitpost.com/api/v1/contacts/imports' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 202
{
  "object": "contact_import",
  "id": "id_123",
  "status": "pending",
  "total": 1,
  "imported": 0,
  "updated": 0,
  "skipped": 0,
  "failed": 0,
  "invalid": [
    {
      "row": 0,
      "reason": "string"
    }
  ],
  "error": "string",
  "update_existing": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Import a batch of contacts (up to 5,000 per request) in the background. The call returns immediately with an import job you poll for progress and per-row results — new contacts are created and, by default, existing ones (matched by email) are skipped, not changed. To fill names and custom fields onto contacts you already have, send update_existing: true: each existing contact gets the names its row carries and its custom_fields merged key by key, and is counted in updated. An import never changes an existing contact's subscription. Contacts that already exist don't count against your plan's contact limit. Track it with Retrieve a contact import, or see all your imports via List contact imports. To add a single contact synchronously, use Create a contact. Requires the contacts:write capability.

Request body2 fields
FieldTypeDescription
contactsrequiredobject[]—
update_existingbooleanUpdate contacts that already exist instead of skipping them. A row whose email belongs to a contact sets the `first_name` and `last_name` it carries (a blank one is ignored) and merges its `custom_fields` key by key: keys the row leaves out keep their values. The contact's subscription is never changed (`unsubscribed` applies only to contacts the import creates). Counted in `updated`; a row that changes nothing is counted in `skipped`. Default `false`: existing contacts are skipped.
Response · 202 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
202401422502

Retrieve a contact import

GET/api/v1/contacts/imports/{id}

GET /contacts/imports/{id}
curl -X GET 'https://www.unitpost.com/api/v1/contacts/imports/imp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "contact_import",
  "id": "id_123",
  "status": "pending",
  "total": 1,
  "imported": 0,
  "updated": 0,
  "skipped": 0,
  "failed": 0,
  "invalid": [
    {
      "row": 0,
      "reason": "string"
    }
  ],
  "error": "string",
  "update_existing": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a bulk import job by id to check its status and per-row results — how many contacts were created, updated, or skipped, and why any rows failed. Poll this while an import runs. Start one with Start an async contact import. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Cancel a contact import

POST/api/v1/contacts/imports/{id}/cancel

POST /contacts/imports/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/contacts/imports/imp_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "contact_import",
  "id": "id_123",
  "status": "pending",
  "total": 1,
  "imported": 0,
  "updated": 0,
  "skipped": 0,
  "failed": 0,
  "invalid": [
    {
      "row": 0,
      "reason": "string"
    }
  ],
  "error": "string",
  "update_existing": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Stop a pending or processing import job. A running import stops at its next chunk of rows; contacts it already imported are kept. The job's status becomes canceled. A job that has already finished returns 409. Check its progress first with Retrieve a contact import. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409

Retry a contact import

POST/api/v1/contacts/imports/{id}/retry

POST /contacts/imports/{id}/retry
curl -X POST 'https://www.unitpost.com/api/v1/contacts/imports/imp_123/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "object": "contact_import",
  "id": "id_123",
  "status": "pending",
  "total": 1,
  "imported": 0,
  "updated": 0,
  "skipped": 0,
  "failed": 0,
  "invalid": [
    {
      "row": 0,
      "reason": "string"
    }
  ],
  "error": "string",
  "update_existing": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Re-run a failed import from the rows stored on the job, without uploading them again. Rows that landed in the failed run are skipped as duplicates, so a retry only adds what is missing (an update_existing import keeps that setting; changes already made count as skipped). Any other state is a 409 (a second retry while the first runs finds the job pending), and so is a job whose rows are no longer kept: start a new import. Same rate limit as starting an import. No body; track it with Retrieve a contact import. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 202 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | processing | completed | failed | canceled—
totalrequirednumber—
importedrequirednumber—
updatedrequirednumber—
skippedrequirednumber—
failedrequirednumber—
invalidrequiredobject[]—
errorrequiredstring | null—
update_existingrequiredboolean—
created_atrequiredstring—
updated_atrequiredstring—
202400401403404409422429502

Contact fields

Define the typed custom attributes (text, number, date, …) your contacts carry — usable in templates as per-recipient variables.

List custom contact fields

GET/api/v1/contact-fields

GET /contact-fields
curl -X GET 'https://www.unitpost.com/api/v1/contact-fields' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_field",
      "id": "id_123",
      "key": "string",
      "label": "string",
      "type": "text",
      "default_value": "string",
      "position": 0,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of the custom contact fields defined in your workspace, cursor-paginated. These are the typed attributes (text, number, date, boolean, and so on) you can set on any contact and reference as template variables. Define a new one with Create a custom contact field. Requires the contacts:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200401422

Create a custom contact field

POST/api/v1/contact-fields

POST /contact-fields
curl -X POST 'https://www.unitpost.com/api/v1/contact-fields' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "plan",
    "label": "Plan",
    "type": "text"
  }'
Response · 201
{
  "object": "contact_field",
  "id": "id_123",
  "key": "string",
  "label": "string",
  "type": "text",
  "default_value": "string",
  "position": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Define a new typed custom field that can then be set on any contact and used as a template variable (e.g. plan, signup_date). An optional default_value is the value used for any contact that has none: when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. The key and type are fixed once created — rename the key later with Rename a custom field's key, or change the label with Update a custom contact field. See existing fields via List custom contact fields. Requires the contacts:write capability.

Request body4 fields
FieldTypeDescription
keyrequiredstring—
labelrequiredstring—
typeenumtext | number | boolean | date—
default_valuestring | nullThe value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value.
Response · 201 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
201401409422

Retrieve a custom contact field

GET/api/v1/contact-fields/{id}

GET /contact-fields/{id}
curl -X GET 'https://www.unitpost.com/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "contact_field",
  "id": "id_123",
  "key": "string",
  "label": "string",
  "type": "text",
  "default_value": "string",
  "position": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single custom contact field by id, including its key, type, and label. Update its label with Update a custom contact field, or rename the key with Rename a custom field's key. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a custom contact field

PATCH/api/v1/contact-fields/{id}

PATCH /contact-fields/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "contact_field",
  "id": "id_123",
  "key": "string",
  "label": "string",
  "type": "text",
  "default_value": "string",
  "position": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a custom field's editable metadata, such as its display label or default_value. A changed default takes effect at once, for sends and for segment membership, because it is never stored on contacts. The key and type are immutable here — to change the key (and migrate every contact's stored value) use Rename a custom field's key instead. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body4 fields
FieldTypeDescription
labelstring—
typeenumtext | number | boolean | date—
positioninteger—
default_valuestring | nullThe value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200401404422

Delete a custom contact field

DELETE/api/v1/contact-fields/{id}

DELETE /contact-fields/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/contact-fields/cf_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Permanently delete a custom field definition and strip its stored value from every contact. Any template variable that referenced it will resolve to empty. On more than 5,000 contacts the strip runs as a background job and the response is 202 with the job's progress instead of 204. This can't be undone — recreate the field with Create a custom contact field if you need it back. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202204401404409

Rename a custom field's key

POST/api/v1/contact-fields/{id}/rename

POST /contact-fields/{id}/rename
curl -X POST 'https://www.unitpost.com/api/v1/contact-fields/cf_123/rename' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "subscription_plan"
  }'
Response · 200
{
  "object": "contact_field",
  "id": "id_123",
  "key": "string",
  "label": "string",
  "type": "text",
  "default_value": "string",
  "position": 0,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Change a custom field's key, migrating the stored value on every contact so no data is lost. Because the key is how templates and the API reference the field, update any template variables that used the old key. To change only the display label, use Update a custom contact field. Requires the contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
keyrequiredstring—
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
keyrequiredstring—
labelrequiredstring—
typerequiredenumtext | number | boolean | date—
default_valuerequiredstring | nullThe value used for any contact that has none for this field (key missing or null): when an email is sent (merge tags) and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once. Stored as a string and coerced to the field's type; null means no default. In segment filters, is_set / is_not_set check whether the contact itself has a value.
positionrequirednumber—
created_atrequiredstring—
updated_atrequiredstring—
200202401404409422

Jobs

Background jobs for operations too large for one request — a custom-field delete or rename over thousands of contacts. Such a call answers 202 with a job; follow it here until it finishes.

Retrieve a job

GET/api/v1/jobs/{id}

GET /jobs/{id}
curl -X GET 'https://www.unitpost.com/api/v1/jobs/job_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a background job by id to follow its progress. An operation that touches more contacts than fits in one request (for example Delete a custom contact field or Rename a custom field's key above 5,000 holders, or a campaign validation over more than 5,000 recipients) answers 202 with a job. Poll this until status is COMPLETED, FAILED or CANCELED; processed of total is the progress. A failed job keeps the work it finished; resume it with Retry a job. Reading a job takes the read capability of the resource it changes (contacts:read for a custom-field job or a contacts export, campaigns:read for a campaign check, topics:read for a topic opt-out). Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
200401403404

List jobs

GET/api/v1/jobs

GET /jobs
curl -X GET 'https://www.unitpost.com/api/v1/jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "job",
      "id": "id_123",
      "kind": "string",
      "status": "QUEUED",
      "total": 1,
      "processed": 0,
      "failed": 0,
      "error": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "completed_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Your background jobs, newest first and cursor-paginated, as Settings → Bulk operations lists them: the kinds an API operation starts that your key may read. Filter with status or kind. Requires the contacts:read capability.

Parameters5 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
statusstring · queryQUEUED, RUNNING, COMPLETED, FAILED or CANCELED.
kindstring · queryOne kind, e.g. `contacts.export`, `contact_field.delete` or `contacts.topic_opt_out`.
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
200401403422

Cancel a job

POST/api/v1/jobs/{id}/cancel

POST /jobs/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/jobs/job_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Stop a queued or running job. A running job stops after the part in flight; the work already done stays. A kind that can't stop half-way (a custom-field rename) is a 409 saying why. Takes no body. Needs the capability that starts the kind (contacts:write for a custom-field job, contacts:read for an export, topics:write for a topic opt-out). Requires the contacts:read or contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
200400401403404409422

Retry a job

POST/api/v1/jobs/{id}/retry

POST /jobs/{id}/retry
curl -X POST 'https://www.unitpost.com/api/v1/jobs/job_123/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "object": "job",
  "id": "id_123",
  "kind": "string",
  "status": "QUEUED",
  "total": 1,
  "processed": 0,
  "failed": 0,
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Resume a FAILED job from where it stopped: nothing it already processed runs again, but the rest does (a custom-field delete finishes removing the field from every contact). Any other status is a 409. Takes no body. Needs the capability that starts the kind (contacts:write for a custom-field job, contacts:read for an export, topics:write for a topic opt-out). Requires the contacts:read or contacts:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 202 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
kindrequiredstring—
statusrequiredenumQUEUED | RUNNING | COMPLETED | FAILED | CANCELED—
totalrequiredinteger | null—
processedrequiredinteger—
failedrequiredinteger—
errorrequiredstring | null—
created_atrequiredstring—
completed_atrequiredstring | null—
202400401403404409422502

Download a job's file

GET/api/v1/jobs/{id}/download

GET /jobs/{id}/download
curl -X GET 'https://www.unitpost.com/api/v1/jobs/job_123/download' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "job_download",
  "job_id": "job_123",
  "url": "https://example.com",
  "filename": "string",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

A finished job's file (a contacts export's CSV) as a signed url that expires in 5 minutes. A job that isn't COMPLETED, or a kind with no file, is a 409. Needs the kind's capability now: the file holds that data. Requires the contacts:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredstring—
job_idrequiredstring—
urlrequiredstringA signed URL to the file; it expires in 5 minutes.
filenamerequiredstring—
expires_atrequiredstring—
200401403404409422503

Library images

The images your templates embed. Upload from a URL, as base64, or as a file (file_id); a template takes an image's path (/img/…). A delete is refused while something uses the image, unless you force it.

List images

GET/api/v1/library-images

GET /library-images
curl -X GET 'https://www.unitpost.com/api/v1/library-images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "library_image",
      "id": "id_123",
      "path": "string",
      "url": "https://example.com",
      "filename": "string",
      "content_type": "string",
      "size": 1,
      "width": 0,
      "height": 0,
      "alt": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The workspace's image library, newest first: the images a template embeds. Each image's path (/img/…) is what a template's <Image src> (or <img src>) takes; url is its public address. Requires the templates:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
pathrequiredstringPut this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
urlrequiredstringThe image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
filenamerequiredstring—
content_typerequiredstring—
sizerequiredintegerBytes.
widthrequiredinteger | null—
heightrequiredinteger | null—
altrequiredstring | nullThe alt text suggested when the image is inserted.
created_atrequiredstring—
updated_atrequiredstring—
200401403422

Upload an image

POST/api/v1/library-images

POST /library-images
curl -X POST 'https://www.unitpost.com/api/v1/library-images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "library_image",
  "id": "id_123",
  "path": "string",
  "url": "https://example.com",
  "filename": "string",
  "content_type": "string",
  "size": 1,
  "width": 0,
  "height": 0,
  "alt": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Add an image to the library from a public https url (fetched once, no redirects, no private addresses), base64 data with its content_type, or a file_id (a file made with purpose image, e.g. an upload session for a local image): PNG, JPEG, GIF or WebP up to 5 MB and 16,384 px a side (50 megapixels at most), counted against the plan's image storage (403 limit_reached). Send an Idempotency-Key so a retried upload stores one image. Requires the templates:write capability.

Parameters1 field
FieldTypeDescription
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body6 fields
FieldTypeDescription
urlstringA public https image to fetch (no redirects, no private addresses). PNG, JPEG, GIF or WebP, up to 5 MB and 16,384 px a side (50 megapixels at most); anything else is a 422 naming `url`.
datastringThe image bytes, base64 (no `data:` prefix), up to 5 MB of image. Base64 grows bytes by a third, and a request body may be up to 30 MB. At most 16,384 px a side and 50 megapixels; anything else is a 422 naming `data`.
file_idstringA file made with `POST /files` and purpose `image` (`file_…`): how an agent hands over a local image without base64 (an upload session), or an image up to 5 MB. Checked by its bytes when it was made, and again here.
content_typeenumimage/png | image/jpeg | image/gif | image/webpRequired with `data`; refused with `url` and `file_id` (the server reads the type from the bytes).
filenamestringShown in the library. Defaults to the URL's file name, or `image`.
altstring | nullAlt text suggested when the image is inserted.
Response · 201 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
pathrequiredstringPut this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
urlrequiredstringThe image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
filenamerequiredstring—
content_typerequiredstring—
sizerequiredintegerBytes.
widthrequiredinteger | null—
heightrequiredinteger | null—
altrequiredstring | nullThe alt text suggested when the image is inserted.
created_atrequiredstring—
updated_atrequiredstring—
201400401403409413422429502503

Retrieve an image

GET/api/v1/library-images/{id}

GET /library-images/{id}
curl -X GET 'https://www.unitpost.com/api/v1/library-images/img_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "library_image",
  "id": "id_123",
  "path": "string",
  "url": "https://example.com",
  "filename": "string",
  "content_type": "string",
  "size": 1,
  "width": 0,
  "height": 0,
  "alt": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

One library image. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
pathrequiredstringPut this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
urlrequiredstringThe image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
filenamerequiredstring—
content_typerequiredstring—
sizerequiredintegerBytes.
widthrequiredinteger | null—
heightrequiredinteger | null—
altrequiredstring | nullThe alt text suggested when the image is inserted.
created_atrequiredstring—
updated_atrequiredstring—
200401403404422

Update an image

PATCH/api/v1/library-images/{id}

PATCH /library-images/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/library-images/img_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "library_image",
  "id": "id_123",
  "path": "string",
  "url": "https://example.com",
  "filename": "string",
  "content_type": "string",
  "size": 1,
  "width": 0,
  "height": 0,
  "alt": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Change the alt text the image suggests when it's inserted. Requires the templates:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
altrequiredstring | nullThe new alt text; `null` or `""` clears it.
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
pathrequiredstringPut this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
urlrequiredstringThe image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
filenamerequiredstring—
content_typerequiredstring—
sizerequiredintegerBytes.
widthrequiredinteger | null—
heightrequiredinteger | null—
altrequiredstring | nullThe alt text suggested when the image is inserted.
created_atrequiredstring—
updated_atrequiredstring—
200400401403404422

Delete an image

DELETE/api/v1/library-images/{id}

DELETE /library-images/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/library-images/img_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Remove an image from the library. While a template, a campaign or sent mail uses it, the answer is 409 resource_in_use naming them (details[]); force=true deletes it anyway, as the dashboard's "Delete anyway" does: those emails then show a broken image wherever it isn't cached yet. Requires the templates:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
forcestring · query`true` deletes an image that's in use.
204401403404409422

Files

Hand the API a file for one purpose, then use it by file_id: SMS opt-in evidence and company documents, images for templates and branding. From a URL, as base64, or with an upload session (a presigned PUT) for a local file an agent can't put in a request. Checked by their bytes, private, kept 24 hours.

List files

GET/api/v1/files

GET /files
curl -X GET 'https://www.unitpost.com/api/v1/files' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "file",
      "id": "id_123",
      "purpose": "sms_opt_in_evidence",
      "status": "awaiting_upload",
      "filename": "string",
      "content_type": "string",
      "size_bytes": 1,
      "sha256": "string",
      "failure_reason": "string",
      "upload": {
        "url": "https://example.com",
        "method": "PUT",
        "headers": {},
        "expires_at": "2026-01-01T00:00:00.000Z"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "expires_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The workspace's unexpired files, newest first, of the purposes this credential may use (sms:manage: the SMS purposes; templates:write or branding:write: image). purpose narrows it. Requires the sms:manage or templates:write or branding:write capability.

Parameters4 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
purposestring · queryOnly files of this purpose.
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
purposerequiredenumsms_opt_in_evidence | sms_document | imageWhat the file is for: `sms_opt_in_evidence` (PNG, up to 400 KB), `sms_document` (PDF, PNG or JPEG, up to 3 MB), `image` (PNG, JPEG, GIF or WebP, up to 5 MB).
statusrequiredenumawaiting_upload | ready | failed`ready`: checked and usable by `file_id`. `awaiting_upload`: an upload session whose bytes haven't been PUT yet (reading the file checks again). `failed`: the uploaded bytes were refused (`failure_reason` says why).
filenamerequiredstring—
content_typerequiredstringThe type the file's bytes carry (checked by their contents), or, before an upload session's bytes arrive, the type declared.
size_bytesrequiredinteger—
sha256requiredstring | nullThe hex SHA-256 of the bytes once `ready`.
failure_reasonrequiredstring | null—
uploadrequiredobject | nullAn upload session's PUT, in the create response only (null otherwise).
created_atrequiredstring—
expires_atrequiredstringThe file is deleted at this time, 24 hours after it was created, whether or not it was used. An operation that used it keeps its own copy.
200401403422

Create a file

POST/api/v1/files

POST /files
curl -X POST 'https://www.unitpost.com/api/v1/files' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "file",
  "id": "id_123",
  "purpose": "sms_opt_in_evidence",
  "status": "awaiting_upload",
  "filename": "string",
  "content_type": "string",
  "size_bytes": 1,
  "sha256": "string",
  "failure_reason": "string",
  "upload": {
    "url": "https://example.com",
    "method": "PUT",
    "headers": {},
    "expires_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

Hand the API a file for one purpose, then pass its id as file_id (or the field an operation names) to what uses it: a brand document, a toll-free number's opt-in evidence, a 10DLC campaign's screenshot, a library image, the logo. Three ways in, one per call: a public https url (fetched once, no redirects, no private addresses); base64 data with content_type (a request body may be up to 30 MB); or an upload session, for a local file: send content_type and size_bytes without url or data, then PUT the bytes to upload.url with upload.headers within 15 minutes (curl -T file -H "Content-Type: image/png" "<upload.url>"). The bytes are checked by their contents against the purpose (sms_opt_in_evidence: PNG up to 400 KB; sms_document: PDF, PNG or JPEG up to 3 MB; image: PNG, JPEG, GIF or WebP up to 5 MB), never by the label. Files are private, never served back, and expire 24 hours after they're made: what uses one keeps its own copy. Send an Idempotency-Key so a retry makes one file. Requires the sms:manage or templates:write or branding:write capability.

Parameters1 field
FieldTypeDescription
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body6 fields
FieldTypeDescription
purposerequiredenumsms_opt_in_evidence | sms_document | imageWhat the file is for, which sets what it may be: `sms_opt_in_evidence` (PNG, up to 400 KB), `sms_document` (PDF, PNG or JPEG, up to 3 MB), `image` (PNG, JPEG, GIF or WebP, up to 5 MB). The bytes decide the type, never the name or the label.
urlstringA public https address to fetch the file from (no redirects, no private addresses, 12 seconds). One of `url`, `data`, or neither (an upload session).
datastringThe bytes, base64 (no `data:` prefix), with `content_type`. Base64 grows bytes by a third, and a request body may be up to 30 MB. A `url` or an upload session carries no bytes in the request.
content_typeenumimage/png | application/pdf | image/jpeg | image/gif | image/webpRequired with `data` and for an upload session (it is signed into the PUT); refused with `url`.
size_bytesintegerAn upload session only: the exact size of the file you'll PUT, in bytes (signed into the PUT). Within the purpose's maximum.
filenamestringA name for the file (shown on what uses it). Defaults to the URL's last path part, or `file.<ext>`.
Response · 201 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
purposerequiredenumsms_opt_in_evidence | sms_document | imageWhat the file is for: `sms_opt_in_evidence` (PNG, up to 400 KB), `sms_document` (PDF, PNG or JPEG, up to 3 MB), `image` (PNG, JPEG, GIF or WebP, up to 5 MB).
statusrequiredenumawaiting_upload | ready | failed`ready`: checked and usable by `file_id`. `awaiting_upload`: an upload session whose bytes haven't been PUT yet (reading the file checks again). `failed`: the uploaded bytes were refused (`failure_reason` says why).
filenamerequiredstring—
content_typerequiredstringThe type the file's bytes carry (checked by their contents), or, before an upload session's bytes arrive, the type declared.
size_bytesrequiredinteger—
sha256requiredstring | nullThe hex SHA-256 of the bytes once `ready`.
failure_reasonrequiredstring | null—
uploadrequiredobject | nullAn upload session's PUT, in the create response only (null otherwise).
created_atrequiredstring—
expires_atrequiredstringThe file is deleted at this time, 24 hours after it was created, whether or not it was used. An operation that used it keeps its own copy.
201400401403404409413415422429503

Retrieve a file

GET/api/v1/files/{id}

GET /files/{id}
curl -X GET 'https://www.unitpost.com/api/v1/files/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "file",
  "id": "id_123",
  "purpose": "sms_opt_in_evidence",
  "status": "awaiting_upload",
  "filename": "string",
  "content_type": "string",
  "size_bytes": 1,
  "sha256": "string",
  "failure_reason": "string",
  "upload": {
    "url": "https://example.com",
    "method": "PUT",
    "headers": {},
    "expires_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

One file's metadata (the bytes are never served back). For an upload session this checks whether the bytes arrived and pass the purpose's checks: ready, failed (failure_reason), or still awaiting_upload. Requires the sms:manage or templates:write or branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
purposerequiredenumsms_opt_in_evidence | sms_document | imageWhat the file is for: `sms_opt_in_evidence` (PNG, up to 400 KB), `sms_document` (PDF, PNG or JPEG, up to 3 MB), `image` (PNG, JPEG, GIF or WebP, up to 5 MB).
statusrequiredenumawaiting_upload | ready | failed`ready`: checked and usable by `file_id`. `awaiting_upload`: an upload session whose bytes haven't been PUT yet (reading the file checks again). `failed`: the uploaded bytes were refused (`failure_reason` says why).
filenamerequiredstring—
content_typerequiredstringThe type the file's bytes carry (checked by their contents), or, before an upload session's bytes arrive, the type declared.
size_bytesrequiredinteger—
sha256requiredstring | nullThe hex SHA-256 of the bytes once `ready`.
failure_reasonrequiredstring | null—
uploadrequiredobject | nullAn upload session's PUT, in the create response only (null otherwise).
created_atrequiredstring—
expires_atrequiredstringThe file is deleted at this time, 24 hours after it was created, whether or not it was used. An operation that used it keeps its own copy.
200401403404422

Delete a file

DELETE/api/v1/files/{id}

DELETE /files/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/files/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Delete a file and its bytes before its 24 hours are up. What already used it keeps its copy. Requires the sms:manage or templates:write or branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404422

Branding

The look marketing emails' footer and the hosted unsubscribe page share, with the same options as Settings → Brand, and the logo. Writes need branding:write, which no key preset includes.

Retrieve branding

GET/api/v1/branding

GET /branding
curl -X GET 'https://www.unitpost.com/api/v1/branding' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "branding",
  "company_name": "string",
  "company_address": "string",
  "logo_url": "https://example.com",
  "has_brand_logo": false,
  "colors": {
    "background": "string",
    "footer_background": "string",
    "text": "string",
    "accent": "string",
    "button_text": "string"
  },
  "font": "string",
  "hide_unitpost_branding": false,
  "unitpost_branding_hidden": false,
  "can_hide_unitpost_branding": false,
  "unsubscribe_page": {
    "title": "string",
    "description": "string",
    "confirm": false,
    "collect_reason": false,
    "show_address": false,
    "show_topics": false,
    "save_label": "string",
    "global_label": "string",
    "global_note": "string",
    "topics_heading": "string"
  },
  "footer": {
    "intro_text": "string",
    "unsubscribe_label": "string"
  }
}

The look marketing emails' footer and the hosted unsubscribe page share, as Settings → Brand shows it: colors, the font, the company name and postal address, the page's copy and behavior, the footer's labels, the logo, and whether the "Sent with Unitpost" mark shows. null means the default; company_name falls back to the workspace's name, so send it only to pin a different one. Requires the templates:read capability.

Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
company_namerequiredstring | nullThe name the footer shows; the workspace's name unless one was set.
company_addressrequiredstring | null—
logo_urlrequiredstring | nullThe logo emails and the unsubscribe page show: the brand logo, else the workspace image, else none.
has_brand_logorequiredboolean—
colorsrequiredobject—
fontrequiredstring | null—
hide_unitpost_brandingrequiredbooleanThe stored choice.
unitpost_branding_hiddenrequiredbooleanWhether recipients see no mark now: the choice, the plan and the account together.
can_hide_unitpost_brandingrequiredbooleanWhether the plan allows hiding the mark.
unsubscribe_pagerequiredobject—
footerrequiredobject—
200401403422

Update branding

PATCH/api/v1/branding

PATCH /branding
curl -X PATCH 'https://www.unitpost.com/api/v1/branding' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "branding",
  "company_name": "string",
  "company_address": "string",
  "logo_url": "https://example.com",
  "has_brand_logo": false,
  "colors": {
    "background": "string",
    "footer_background": "string",
    "text": "string",
    "accent": "string",
    "button_text": "string"
  },
  "font": "string",
  "hide_unitpost_branding": false,
  "unitpost_branding_hidden": false,
  "can_hide_unitpost_branding": false,
  "unsubscribe_page": {
    "title": "string",
    "description": "string",
    "confirm": false,
    "collect_reason": false,
    "show_address": false,
    "show_topics": false,
    "save_label": "string",
    "global_label": "string",
    "global_note": "string",
    "topics_heading": "string"
  },
  "footer": {
    "intro_text": "string",
    "unsubscribe_label": "string"
  }
}

Change branding with the same options Settings → Brand offers; only the fields you send change, and null restores a default. The footer every marketing email carries is built from these at send (it always keeps the unsubscribe link and the postal address). Hiding the "Sent with Unitpost" mark needs a paid plan (403 limit_reached). No key preset includes this capability: tick it on the key. Requires the branding:write capability.

Request body7 fields
FieldTypeDescription
company_namestring | nullShown in the footer (`{{company_name}}`).
company_addressstring | nullThe postal address every marketing email carries (`{{company_address}}`).
colorsobject—
fontenum | nullOne of: System default, Arial, Helvetica, Verdana, Tahoma, Trebuchet MS, Georgia, Times New Roman, Courier New.
hide_unitpost_brandingbooleanHide the "Sent with Unitpost" mark. Paid plans only (403 `limit_reached`).
unsubscribe_pageobject—
footerobject—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
company_namerequiredstring | nullThe name the footer shows; the workspace's name unless one was set.
company_addressrequiredstring | null—
logo_urlrequiredstring | nullThe logo emails and the unsubscribe page show: the brand logo, else the workspace image, else none.
has_brand_logorequiredboolean—
colorsrequiredobject—
fontrequiredstring | null—
hide_unitpost_brandingrequiredbooleanThe stored choice.
unitpost_branding_hiddenrequiredbooleanWhether recipients see no mark now: the choice, the plan and the account together.
can_hide_unitpost_brandingrequiredbooleanWhether the plan allows hiding the mark.
unsubscribe_pagerequiredobject—
footerrequiredobject—
200400401403422

Workspace

The workspace's name and image (writes need branding:write), who is calling (GET /whoami, any credential), and the activity log (GET /activity, activity:read: no key preset includes it).

Who am I

GET/api/v1/whoami

GET /whoami
curl -X GET 'https://www.unitpost.com/api/v1/whoami' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "whoami",
  "workspace": {
    "id": "id_123",
    "name": "Example",
    "slug": "string"
  },
  "organization": {
    "id": "id_123",
    "name": "Example"
  },
  "credential": {
    "type": "api_key",
    "id": "id_123",
    "name": "Example",
    "prefix": "string",
    "scope": "full",
    "created_at": "2026-01-01T00:00:00.000Z",
    "last_used_at": "2026-01-01T00:00:00.000Z",
    "client_id": "client_123",
    "client_name": "string",
    "user": "string"
  },
  "capabilities": [
    "string"
  ],
  "rate_limit": {
    "limit": 1,
    "window_seconds": 0
  }
}

The calling credential: its workspace, the API key (name, prefix, scope preset) or the OAuth sign-in (the app and the member it acts for), the capabilities it may use after every clamp, and the workspace's rate limit. Call it first to plan within what the credential may do instead of learning by 403. Never returns the secret. Requires no capability: any valid credential may call it.

Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
workspacerequiredobject—
organizationobjectThe organization the workspace belongs to. A key still reaches only its own workspace.
credentialrequiredobjectNever the secret.
capabilitiesrequiredstring[]What this credential may do, after every clamp: a call that needs another one answers 403 `insufficient_scope`.
rate_limitrequiredobject—
200401404422

List activity

GET/api/v1/activity

GET /activity
curl -X GET 'https://www.unitpost.com/api/v1/activity' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "activity",
      "id": "id_123",
      "type": "string",
      "subject": "contact",
      "subject_id": "subject_123",
      "subject_label": "string",
      "contact_id": "contact_123",
      "campaign_id": "campaign_123",
      "actor": {
        "name": "Example",
        "via": {
          "surface": "api",
          "credential": "api_key",
          "api_key_id": "api_key_123"
        }
      },
      "metadata": {},
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The workspace activity log, newest first and cursor-paginated: what changed, when, and who changed it (actor.name: a teammate, System, Ask Unit) and, for a change made over the API, MCP or Ask Unit, how (actor.via, with the API key). The rows the dashboard's Activity page and each record's timeline show. Narrow with subject (and subject_id), contact_id, campaign_id, q (the record's name or the actor) and channel=email. Needs activity:read, which no key preset includes: the log names your teammates. Requires the activity:read capability.

Parameters9 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
subjectstring · queryOnly changes to this kind of record.
subject_idstring · queryWith `subject`: one record's changes (its id, e.g. `dom_…`).
contact_idstring · queryOne contact's timeline (`con_…`).
campaign_idstring · queryA campaign's changes and what it led to (e.g. unsubscribes through it) (`cmp_…`).
qstring · queryPart of the record's name or the actor's (case-insensitive). At most 200 characters.
channelstring · query`email`: without SMS rows.
Response · 200 fields11 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
typerequiredstringWhat happened, e.g. `contact_created`, `campaign_sent`, `domain_verified`.
subjectrequiredenumcontact | segment | topic | field | template | component | campaign | email | domain | sender_email | library_image | api_key | webhook | suppression | message | handle | workspaceThe kind of record it happened to.
subject_idrequiredstring | nullThe record's id (prefixed where the record has a public id).
subject_labelrequiredstring | nullThe record's name at the time: a contact's email, a segment's name, …; a phone number is masked (`+1••••••7755`).
contact_idrequiredstring | null—
campaign_idrequiredstring | nullThe campaign the change is attributed to (e.g. an unsubscribe through its link).
actorrequiredobject—
metadatarequiredobjectDetail for the change, varying by `type`: a segment's or topic's name, a status before and after, a renamed field's keys, related ids (`campaign_id`, …). Descriptive keys only: addresses, URLs and error text stay in the dashboard.
created_atrequiredstring—
200401403422503

Rename the workspace

PATCH/api/v1/workspace

PATCH /workspace
curl -X PATCH 'https://www.unitpost.com/api/v1/workspace' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "image_url": "https://example.com"
}

Change the workspace's name. Deleting the workspace stays in the dashboard. Requires the branding:write capability.

Request body1 field
FieldTypeDescription
namerequiredstringThe workspace's new name.
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
slugrequiredstring—
image_urlrequiredstring | nullThe workspace image (its avatar in the dashboard).
200400401403422

Set the workspace image

PUT/api/v1/workspace/image

PUT /workspace/image
curl -X PUT 'https://www.unitpost.com/api/v1/workspace/image' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "image_url": "https://example.com"
}

Replace the workspace image (its avatar in the dashboard, and the email logo when there's no brand logo), from a public https url or base64 data (PNG, JPEG, GIF or WebP, up to 5 MB and 16,384 px a side). Requires the branding:write capability.

Request body5 fields
FieldTypeDescription
urlstringA public https image to fetch (no redirects, no private addresses). PNG, JPEG, GIF or WebP, up to 5 MB and 16,384 px a side (50 megapixels at most); anything else is a 422 naming `url`.
datastringThe image bytes, base64 (no `data:` prefix), up to 5 MB of image. Base64 grows bytes by a third, and a request body may be up to 30 MB. At most 16,384 px a side and 50 megapixels; anything else is a 422 naming `data`.
file_idstringA file made with `POST /files` and purpose `image` (`file_…`): how an agent hands over a local image without base64 (an upload session), or an image up to 5 MB. Checked by its bytes when it was made, and again here.
content_typeenumimage/png | image/jpeg | image/gif | image/webpRequired with `data`; refused with `url` and `file_id` (the server reads the type from the bytes).
filenamestringShown in the library. Defaults to the URL's file name, or `image`.
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
slugrequiredstring—
image_urlrequiredstring | nullThe workspace image (its avatar in the dashboard).
200400401403422429502503

Remove the workspace image

DELETE/api/v1/workspace/image

DELETE /workspace/image
curl -X DELETE 'https://www.unitpost.com/api/v1/workspace/image' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "image_url": "https://example.com"
}

Clear the workspace image. Requires the branding:write capability.

Response · 200 fields5 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
slugrequiredstring—
image_urlrequiredstring | nullThe workspace image (its avatar in the dashboard).
200401403

Segments

Named groups of contacts used to target campaigns. Segments decide who a campaign goes to; topics (below) decide what recipients can opt out of.

List segments

GET/api/v1/segments

GET /segments
curl -X GET 'https://www.unitpost.com/api/v1/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "segment",
      "id": "id_123",
      "name": "Example",
      "description": "string",
      "type": "static",
      "filter": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of the segments in your workspace, cursor-paginated. A segment is a saved group of contacts you can target when sending a campaign. Create one with Create a segment, or list a segment's members with List segment members. Deleted (archived) segments are hidden; pass ?archived=true to list only archived ones, which can be restored for 30 days. Requires the segments:read capability.

Parameters4 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
archivedboolean · queryWhen true, list only archived segments instead of active ones.
Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200401422

Create a segment

POST/api/v1/segments

POST /segments
curl -X POST 'https://www.unitpost.com/api/v1/segments' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Active customers"
  }'
Response · 201
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a segment — a named group of contacts you can target when sending a campaign. Once created, add contacts with Add a member and target it from Create a campaign. A dynamic segment's filter is evaluated live: a condition on a custom field uses the field's default_value for any contact that has no value, and is_set / is_not_set check whether the contact itself has a value. To let recipients opt out of a category of mail instead, see Create a topic. Requires the segments:write capability.

Request body4 fields
FieldTypeDescription
namerequiredstring—
descriptionstring—
typeenumstatic | dynamic—
filterobjectDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
Response · 201 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
201401422

Retrieve a segment

GET/api/v1/segments/{id}

GET /segments/{id}
curl -X GET 'https://www.unitpost.com/api/v1/segments/seg_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single segment by id, including its name and member count. To page through the contacts inside it, use List segment members. Requires the segments:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a segment

PATCH/api/v1/segments/{id}

PATCH /segments/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/segments/seg_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a segment's editable metadata, such as its name. To change who's in the segment, add or remove members with Add a member and Remove a member. Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
namestring—
descriptionstring | null—
filterobjectDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200401404422

Delete a segment

DELETE/api/v1/segments/{id}

DELETE /segments/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/segments/seg_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Delete a segment. The contacts themselves are untouched — only the grouping is removed. This is blocked with 409 while an active campaign still targets the segment; cancel or finish that campaign first (see List campaigns). Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404409

List segment members

GET/api/v1/segments/{id}/contacts

GET /segments/{id}/contacts
curl -X GET 'https://www.unitpost.com/api/v1/segments/seg_123/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "segment_member",
      "contact_id": "contact_123",
      "subscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve the contacts in a segment, cursor-paginated. Add a contact with Add a member or take one out with Remove a member. Requires the segments:read capability.

Parameters4 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
subscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
200401404422

Add a member

POST/api/v1/segments/{id}/contacts

POST /segments/{id}/contacts
curl -X POST 'https://www.unitpost.com/api/v1/segments/seg_123/contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": "customer@example.com"
  }'
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "segment_member",
      "contact_id": "contact_123",
      "subscribed": false,
      "unsubscribed_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "has_more": false,
  "added": 0
}

Add a contact to a static segment, referenced by contact id or email (contact), or many at once: contact_ids or emails, up to 1,000 in one call. Send exactly one of the three. The operation is idempotent — adding a contact that's already a member is a no-op that keeps its per-segment subscription and still succeeds. Each contact that joins gets a segment.joined webhook and an activity row. A list is checked first: the first contact that isn't one of yours is a 404 naming it (details), and nobody is added. One contact answers 201 with its membership; a list answers 200 with each listed contact's membership in the order sent and added, how many joined now. Adding a list counts against a limit of 30 bulk contact edits a minute per workspace by default (a 429 added nobody; retry after Retry-After). For more than 1,000 contacts, call it once per 1,000. See the current members with List segment members. Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body4 fields
FieldTypeDescription
contactstringOne contact: its id (`con_…`) or email.
contact_idsstring[]Many contacts of this workspace by id (`con_…`), up to 1,000.
emailsstring[]Many contacts of this workspace by email address, up to 1,000.
subscribedbooleanA new member's per-segment subscription (default true). A contact that is already a member keeps its own.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
subscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
200201401404422429

Opt a member in or out

PATCH/api/v1/segments/{id}/contacts/{contact}

PATCH /segments/{id}/contacts/{contact}
curl -X PATCH 'https://www.unitpost.com/api/v1/segments/seg_123/contacts/con_456' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscribed": false
  }'
Response · 200
{
  "object": "segment_member",
  "contact_id": "contact_123",
  "subscribed": false,
  "unsubscribed_at": "2026-01-01T00:00:00.000Z"
}

Opt a member out of this segment's sends without removing it (subscribed: false), or back in, as the members table's toggle and the preference page do. It stays a member. A dynamic segment has no per-segment opt-out (422). Requires the segments:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
contactrequiredstring · pathA contact id or email.
Request body1 field
FieldTypeDescription
subscribedrequiredboolean`false` opts the contact out of this segment's sends without removing it; `true` opts it back in.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
subscribedrequiredboolean—
unsubscribed_atrequiredstring | null—
200400401403404422

Remove a member

DELETE/api/v1/segments/{id}/contacts/{contact}

DELETE /segments/{id}/contacts/{contact}
curl -X DELETE 'https://www.unitpost.com/api/v1/segments/seg_123/contacts/con_456' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Remove a contact from a segment, referenced by contact id or email. The contact itself is not deleted — only its membership. Add it back any time with Add a member. Requires the segments:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
contactrequiredstring · pathA contact id or email.
204401404

Preview a filter

POST/api/v1/segments/preview

POST /segments/preview
curl -X POST 'https://www.unitpost.com/api/v1/segments/preview' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter": {
      "match": "all",
      "conditions": [
        {
          "field": "plan",
          "operator": "eq",
          "value": "pro"
        }
      ]
    }
  }'
Response · 200
{
  "object": "segment_preview",
  "segment_id": "segment_123",
  "archived": false,
  "member_count": 1,
  "subscribed_count": 1,
  "sample": [
    {
      "id": "id_123",
      "email": "customer@example.com",
      "first_name": "string",
      "last_name": "string"
    }
  ]
}

Count an unsaved dynamic filter before you create the segment, as the segment dialog's live count does: how many contacts match, how many of them a campaign would mail, and a sample (which also needs contacts:read). It reads with the same filter builder the send uses. Nothing is saved. Requires the segments:read capability.

Request body1 field
FieldTypeDescription
filterrequiredobjectThe filter to count, as a dynamic segment's `filter`. Dynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
segment_idrequiredstring | nullThe saved segment, or null for an unsaved filter.
archivedrequiredboolean | nullWhether the saved segment is archived (a campaign can't target it); null for an unsaved filter.
member_countrequiredintegerContacts that match (or are members).
subscribed_countrequiredintegerOf those, the ones a campaign would mail: not unsubscribed. 0 means an empty send.
samplerequiredobject[]Up to 3 of the subscribed set. Empty without `contacts:read`.
200400401403422

Preview a segment

GET/api/v1/segments/{id}/preview

GET /segments/{id}/preview
curl -X GET 'https://www.unitpost.com/api/v1/segments/seg_123/preview' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "segment_preview",
  "segment_id": "segment_123",
  "archived": false,
  "member_count": 1,
  "subscribed_count": 1,
  "sample": [
    {
      "id": "id_123",
      "email": "customer@example.com",
      "first_name": "string",
      "last_name": "string"
    }
  ]
}

How many contacts a saved segment reaches: its members, the subscribed set a campaign would mail (0 means a campaign would send nothing), and a sample (which also needs contacts:read). Requires the segments:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
segment_idrequiredstring | nullThe saved segment, or null for an unsaved filter.
archivedrequiredboolean | nullWhether the saved segment is archived (a campaign can't target it); null for an unsaved filter.
member_countrequiredintegerContacts that match (or are members).
subscribed_countrequiredintegerOf those, the ones a campaign would mail: not unsubscribed. 0 means an empty send.
samplerequiredobject[]Up to 3 of the subscribed set. Empty without `contacts:read`.
200401403404422

Get the all-contacts segment

POST/api/v1/segments/all-contacts

POST /segments/all-contacts
curl -X POST 'https://www.unitpost.com/api/v1/segments/all-contacts' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "segment",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "type": "static",
  "filter": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

The workspace's managed "All subscribed contacts" segment, made the first time it's asked for: the dashboard's "Everyone subscribed" campaign target. Repeating the call returns the same segment. Takes no body. Requires the segments:write capability.

Response · 200 fields8 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
typerequiredenumstatic | dynamic—
filterrequired__schema0 | nullDynamic segments only: the saved filter, evaluated live. A condition on a custom field uses the field's default_value for any contact with no value (key missing or null), the same value merge tags use; defaults are never written onto contacts. is_set / is_not_set check whether the contact itself has a value.
created_atrequiredstring—
updated_atrequiredstring—
200201400401403409422

Webhooks

Register HTTPS endpoints that receive signed event deliveries (delivered, bounced, opened, clicked, …). The signing secret is returned once on create; verify the signature on every delivery.

List webhook endpoints

GET/api/v1/webhooks

GET /webhooks
curl -X GET 'https://www.unitpost.com/api/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook",
      "id": "id_123",
      "name": "Example",
      "url": "https://example.com",
      "events": [
        "email.sent"
      ],
      "status": "enabled",
      "include_text": false,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "backlog": {
        "queued": 0,
        "failed": 0
      }
    }
  ]
}

Retrieve a list of your webhook endpoints, cursor-paginated, with each endpoint's URL, subscribed events, and status. Signing secrets are never returned here — they're shown exactly once by Create a webhook endpoint. Check an endpoint's wiring end-to-end with Send a test event. Requires the webhooks:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
200401403422

Create a webhook endpoint

POST/api/v1/webhooks

POST /webhooks
curl -X POST 'https://www.unitpost.com/api/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhooks/unitpost",
    "events": [
      "email.delivered",
      "email.bounced"
    ]
  }'
Response · 201
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  },
  "signing_secret": "string"
}

Register an https URL to receive event notifications (deliveries, bounces, opens, clicks, and more) and choose which events it subscribes to. The response includes the signing_secret exactly once — store it now, as it can never be retrieved again; use it to verify each delivery's signature. Confirm the endpoint works with Send a test event, and adjust its URL or events later with Update a webhook endpoint. Requires the webhooks:manage capability.

Request body4 fields
FieldTypeDescription
urlrequiredstring—
eventsrequiredenum | string[]—
namestring—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
Response · 201 fields11 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
signing_secretrequiredstringThe HMAC signing secret. Shown exactly once — store it now; it can never be retrieved again. Use it to verify the signature on every delivery to this endpoint.
201401403409422

Retrieve a webhook endpoint

GET/api/v1/webhooks/{id}

GET /webhooks/{id}
curl -X GET 'https://www.unitpost.com/api/v1/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  }
}

Retrieve a single webhook endpoint by id — its URL, subscribed events, and status. The signing secret is never included; it's returned exactly once when the endpoint is created. backlog counts the deliveries Deliver the backlog would send: queued while the endpoint was paused, and failed. Requires the webhooks:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
200401403404503

Update a webhook endpoint

PATCH/api/v1/webhooks/{id}

PATCH /webhooks/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      "email.delivered"
    ]
  }'
Response · 200
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  }
}

Update a webhook endpoint's url, subscribed events, name, and/or status (use status to pause and re-enable deliveries without deleting the endpoint). The signing secret is never changed by an update. Verify your changes with Send a test event. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body5 fields
FieldTypeDescription
urlstring—
eventsenum | string[]—
namestring—
statusenumenabled | disabled—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
200401403404409422

Delete a webhook endpoint

DELETE/api/v1/webhooks/{id}

DELETE /webhooks/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Permanently delete a webhook endpoint and its delivery log. Deliveries stop immediately. The operation is idempotent — deleting an already-deleted endpoint still returns 204. To stop deliveries temporarily instead, set status via Update a webhook endpoint. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403

Rotate a webhook's signing secret

POST/api/v1/webhooks/{id}/rotate-secret

POST /webhooks/{id}/rotate-secret
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/rotate-secret' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  },
  "signing_secret": "string",
  "previous_secret_expires_at": "2026-01-01T00:00:00.000Z"
}

Mint a new signing secret for the endpoint. The response carries the new signing_secret exactly once, as Create a webhook endpoint does. For 24 hours (until previous_secret_expires_at) every delivery is signed with the new and the old secret, so switch your receiver to the new one inside that window without dropping a delivery. Rotating again inside the window retires the older secret at once. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields1 field
FieldTypeDescription
previous_secret_expires_atrequiredstringUntil this time deliveries are signed with the new AND the old secret, so switch your receiver to the new one before then.
200401403404409

List a webhook's deliveries

GET/api/v1/webhooks/{id}/deliveries

GET /webhooks/{id}/deliveries
curl -X GET 'https://www.unitpost.com/api/v1/webhooks/wh_123/deliveries' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook_delivery",
      "id": "id_123",
      "svix_id": "svix_123",
      "webhook_id": "webhook_123",
      "event_id": "event_123",
      "event_type": "string",
      "status": "pending",
      "attempt": 0,
      "response_status": 0,
      "error": "string",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "next_attempt_at": "2026-01-01T00:00:00.000Z",
      "delivered_at": "2026-01-01T00:00:00.000Z",
      "event_created_at": "2026-01-01T00:00:00.000Z",
      "data": {}
    }
  ]
}

The endpoint's delivery log, newest first and cursor-paginated: one row per event delivered (or being delivered) to it, with its status, attempts, your endpoint's last HTTP status and error, and the event's type and data. Use it to see why deliveries fail; Send a test event probes the endpoint without adding a row. Narrow it with status and event_type. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. Requires the webhooks:read capability.

Parameters6 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
statusstring · queryOne or more delivery statuses, comma-separated: `pending`, `queued`, `retrying`, `succeeded`, `failed`, `exhausted` (e.g. `failed,exhausted`).
event_typestring · queryOnly deliveries of this event type, e.g. `email.bounced`.
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredenumwebhook_delivery—
idrequiredstringThe delivery id (`msg_…`).
svix_idrequiredstringThe `svix-id` header this delivery's requests carried; retries reuse it, so dedupe on it.
webhook_idrequiredstring—
event_idrequiredstringThe event (`evt_…`). The delivered payload's `event_id` is the same id without the `evt_` prefix.
event_typerequiredstring—
statusrequiredenumpending | queued | retrying | succeeded | failed | exhausted`queued`: held while the endpoint is disabled. `retrying`: an attempt failed and another is scheduled at `next_attempt_at`. `exhausted`: every retry failed.
attemptrequiredintegerAttempts made so far.
response_statusrequiredintegerYour endpoint's last HTTP status, or null before an attempt or on a network error.
errorrequiredstring—
scheduled_atrequiredstring—
next_attempt_atrequiredstring—
delivered_atrequiredstring—
event_created_atrequiredstring—
datarequiredobjectThe event's `data`, as delivered.
200401403404422

Replay a delivery

POST/api/v1/webhooks/{id}/deliveries/{delivery}/replay

POST /webhooks/{id}/deliveries/{delivery}/replay
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/deliveries/msg_123/replay' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "object": "webhook_delivery_replay",
  "webhook_id": "webhook_123",
  "delivery_id": "delivery_123",
  "replayed": true
}

Deliver one event to the endpoint again, as the dashboard's Replay does. The same event goes out with the same id, so a receiver that dedupes on it treats the replay as the delivery it already has. The webhook must be enabled: re-enable a disabled or suspended one with Update a webhook endpoint first. Find deliveries with List a webhook's deliveries. Takes no body. Requires the webhooks:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
deliveryrequiredstring · pathThe delivery's id (`msg_…`).
Response · 202 fields4 fields
FieldTypeDescription
objectrequiredenumwebhook_delivery_replay—
webhook_idrequiredstring—
delivery_idrequiredstring—
replayedrequiredenumtrue—
202400401403404409422429502

Deliver a webhook's backlog

POST/api/v1/webhooks/{id}/flush

POST /webhooks/{id}/flush
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/flush' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "include_failed": true
  }'
Response · 202
{
  "object": "webhook_flush",
  "webhook_id": "webhook_123",
  "flushed": 0
}

Deliver the deliveries held while the webhook was suspended (queued), as the dashboard's "Retry queued" does; with include_failed also the ones that failed for good (failed, exhausted). The webhook must be enabled: re-enable it with Update a webhook endpoint first. Re-enabling never delivers the backlog on its own. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
include_failedbooleanAlso deliver the `failed` and `exhausted` deliveries again. Default false: only the `queued` ones (held while the webhook was suspended).
Response · 202 fields3 fields
FieldTypeDescription
objectrequiredenumwebhook_flush—
webhook_idrequiredstring—
flushedrequiredintegerHow many deliveries were handed back for delivery (0 when the backlog was empty).
202400401403404409422429502

Send a test event

POST/api/v1/webhooks/{id}/test

POST /webhooks/{id}/test
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/test' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "webhook_test",
  "delivered": false,
  "response_status": 0,
  "event_type": "string",
  "error": "string"
}

Fire a sample event at the endpoint synchronously and return the receiver's response so you can debug your handler end-to-end. The probe is signed exactly like a real delivery (verify it the same way) but is not persisted to the delivery log. Configure the endpoint itself with Update a webhook endpoint. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredenumwebhook_test—
deliveredrequiredbooleanWhether the endpoint accepted the probe (2xx).
response_statusrequiredintegerThe HTTP status the endpoint returned, or null on a transport error.
event_typerequiredstringThe sample event type that was sent.
errorrequiredstringA transport/error message when delivery failed, else null.
200401403404

Organizations

For platforms that give each customer a workspace: an organization key creates, lists, closes and restores the organization's workspaces and mints their keys, and registers webhook endpoints that receive every workspace's events, each naming its workspace (workspace_id, external_id). Staff approve each organization first. To change the plan of a workspace the organization pays for, quote it (POST …/plan-quotes), show the price, then confirm the quote within 10 minutes; that takes organizations:billing, which only an organization Owner gives a key. Creates and plan changes stay within the Owner's API rules: the plans they allow, up to their largest plan price (with none set, each plan's lowest price). An organization can also ask for shared usage (Organization → Billing, Request access): one Starter or Growth plan whose allowance its workspaces share, turned on by Unitpost on request. GET …/shared-plan reads it; PUT, PATCH and DELETE …/shared-plan/workspaces/{workspace_id} add a workspace, set its cap and take it off (organizations:billing). Buying, upgrading and ending it stay in the dashboard.

List the organization's workspaces

GET/api/v1/organizations/{id}/workspaces

GET /organizations/{id}/workspaces
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "workspace",
      "id": "id_123",
      "name": "Example",
      "slug": "string",
      "external_id": "external_123",
      "plan": "string",
      "paid_by": "workspace",
      "requires_paid_plan": false,
      "sms_purchases_cap_cents": 0,
      "closed_at": "2026-01-01T00:00:00.000Z",
      "restorable_until": "2026-01-01T00:00:00.000Z",
      "deletes_at": "2026-01-01T00:00:00.000Z",
      "shared_plan": {
        "cap_cents": 0,
        "joined_at": "2026-01-01T00:00:00.000Z"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "hosted_invoice_url": "https://example.com"
    }
  ]
}

The organization's workspaces, newest first and cursor-paginated (limit, after, before). external_id narrows to the workspace you gave that id. Takes an organization key (ok_live_…) with organizations:read.

Parameters5 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
limitinteger · query—
afterstring · query—
beforestring · query—
external_idstring · query—
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredenumworkspace—
idrequiredstring`ws_…`
namerequiredstring—
slugrequiredstring—
external_idrequiredstringYour own id for it, unique in the organization.
planrequiredstring`free`, or the paid plan's key.
paid_byrequiredenumworkspace | organization—
requires_paid_planrequiredbooleanNo free allowance: the Owner already has a free workspace, so it sends once a plan is bought.
sms_purchases_cap_centsintegerThe workspace's monthly cap on SMS purchases by API, in cents (ADR-0114). Null: none, so every API purchase is refused with `api_spend_cap_not_set`.
closed_atrequiredstring—
restorable_untilrequiredstringOnce closed: the last moment it can be restored, 30 days after `closed_at`. Null while open.
deletes_atstringOnce closed: when it is deleted unless restored, the later of `restorable_until` and 7 days after the end of the billing period it closed in (so that period's usage stays readable). Its SMS numbers are released then. Null while open.
shared_planobjectOn the organization's shared plan: its cap on what it draws each period (`cap_cents`, null: none) and when it joined. Null when it isn't on it. Its usage is on `GET /organizations/{id}/shared-plan/workspaces`.
created_atrequiredstring—
hosted_invoice_urlstringOn create only: the card asked for authentication; paying here starts the plan.
200401403404429

Create a workspace

POST/api/v1/organizations/{id}/workspaces

POST /organizations/{id}/workspaces
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Bakery",
    "external_id": "cust_42"
  }'
Response · 201
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "external_id": "external_123",
  "plan": "string",
  "paid_by": "workspace",
  "requires_paid_plan": false,
  "sms_purchases_cap_cents": 0,
  "closed_at": "2026-01-01T00:00:00.000Z",
  "restorable_until": "2026-01-01T00:00:00.000Z",
  "deletes_at": "2026-01-01T00:00:00.000Z",
  "shared_plan": {
    "cap_cents": 0,
    "joined_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com"
}

Create a workspace in the organization. Its Owner is the person who made the key. The plan follows the Owner's API rules (Organization → API): free, or a paid plan they allowed at a price no higher than their largest plan price (with none set, the plan's lowest), billed to the organization's card within its workspace limit. Idempotency-Key is required; a retry with it returns the first result. sms_purchases_cap_cents sets the workspace's monthly SMS purchases cap, at most the Owner's largest; left out, a paid workspace starts with the Owner's default and a free one with none. shared_plan: true makes it straight onto the organization's shared plan instead of a plan of its own (it also needs organizations:billing, like PUT /organizations/{id}/shared-plan/workspaces/{workspace_id}); a refused join makes nothing. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
Idempotency-Keyrequiredstring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body6 fields
FieldTypeDescription
namerequiredstring—
external_idstring—
planstringDefault: the Owner's default plan, else `free`. A paid plan is billed to the organization's card at once.
tier_indexintegerThe paid plan's tier (default 0). Its price must be within the Owner's largest plan price (Organization → API); with none set, only tier 0.
sms_purchases_cap_centsintegerThe monthly SMS purchases cap, in cents, at most the Owner's largest. Above 0 only on a paid plan or the shared plan (billed to the organization). Left out: the Owner's default there, else none; null: none.
shared_planbooleanMake it straight onto the organization's shared plan: it draws on the shared allowance, has no plan of its own and is paid by the organization's card. Needs `organizations:billing`; not with `plan` or `tier_index`. Set a cap afterwards with `PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`.
Response · 201 fields15 fields
FieldTypeDescription
objectrequiredenumworkspace—
idrequiredstring`ws_…`
namerequiredstring—
slugrequiredstring—
external_idrequiredstringYour own id for it, unique in the organization.
planrequiredstring`free`, or the paid plan's key.
paid_byrequiredenumworkspace | organization—
requires_paid_planrequiredbooleanNo free allowance: the Owner already has a free workspace, so it sends once a plan is bought.
sms_purchases_cap_centsintegerThe workspace's monthly cap on SMS purchases by API, in cents (ADR-0114). Null: none, so every API purchase is refused with `api_spend_cap_not_set`.
closed_atrequiredstring—
restorable_untilrequiredstringOnce closed: the last moment it can be restored, 30 days after `closed_at`. Null while open.
deletes_atstringOnce closed: when it is deleted unless restored, the later of `restorable_until` and 7 days after the end of the billing period it closed in (so that period's usage stays readable). Its SMS numbers are released then. Null while open.
shared_planobjectOn the organization's shared plan: its cap on what it draws each period (`cap_cents`, null: none) and when it joined. Null when it isn't on it. Its usage is on `GET /organizations/{id}/shared-plan/workspaces`.
created_atrequiredstring—
hosted_invoice_urlstringOn create only: the card asked for authentication; paying here starts the plan.
201400401403404409422429

List usage by workspace

GET/api/v1/organizations/{id}/usage

GET /organizations/{id}/usage
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/usage' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "workspace_usage",
      "workspace_id": "workspace_123",
      "external_id": "external_123",
      "name": "Example",
      "closed_at": "2026-01-01T00:00:00.000Z",
      "plan": "string",
      "period_start": "string",
      "period_end": "string",
      "emails": {
        "sent": 0
      },
      "spend": {
        "total_cents": 1,
        "email_cents": 0,
        "sms_cents": 0,
        "sms_carrier_fees_cents": 0,
        "other_cents": 0,
        "refunds_cents": 0,
        "included_cents": 0,
        "purchased_credit_cents": 0,
        "overage_cents": 0,
        "credits_added_cents": 0
      },
      "sms": {
        "messages": 0,
        "segments": 0,
        "send_cents": 0,
        "received": 0,
        "received_cents": 0,
        "monthly_fees_cents": 0,
        "one_time_fees_cents": 0,
        "refunds_cents": 0,
        "countries": [
          {
            "country": "string",
            "messages": 0,
            "segments": 0,
            "price_per_segment_cents": 0,
            "price_per_segment_cents_decimal": "string",
            "cost_cents": 0
          }
        ],
        "received_countries": [
          {
            "country": "string",
            "received": 0,
            "segments": 0,
            "cost_cents": 0
          }
        ]
      },
      "on_shared_plan": false
    }
  ]
}

Usage and spend for each of the organization's workspaces, one row per workspace, newest first and cursor-paginated by workspace (limit 1 to 25, default 10; after and before take a ws_… id). A limit above 25 is a 422, not a shorter page; read more with after. Each workspace renews on its own date, so a row covers that workspace's own billing period: period=current (the default) is its open period, and an ISO 8601 instant is its period that contains that instant. A workspace with no recorded period at that instant (it did not exist yet, or nothing was used in that period) has period_start and period_end null and every number 0. spend, sms, emails.sent, plan and the period are built as GET /usage builds them, so for the open period a row equals that workspace's GET /usage; amounts are integer USD cents rounded per workspace, and the organization's total is the sum of the rows. Closed workspaces are listed, with closed_at, until they are deleted. external_id narrows to the workspace you gave that id. Takes an organization key (ok_live_…) with organizations:read.

Parameters6 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
periodstring · query`current` (default), or an ISO 8601 instant with `Z` or an offset (`2026-10-15T00:00:00Z`); a date alone is UTC midnight.
limitinteger · queryWorkspaces a page (default 10, max 25).
afterstring · queryThe next page: the last row's `workspace_id` (`ws_…`).
beforestring · queryThe previous page: the first row's `workspace_id` (`ws_…`). Not with `after`.
external_idstring · queryOnly the workspace you gave this id.
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
workspace_idrequiredstring—
external_idrequiredstring | null—
namerequiredstring—
closed_atrequiredstring | null—
planrequiredstring—
period_startrequiredstring | null—
period_endrequiredstring | null—
emailsrequiredobject—
spendrequiredobject—
smsrequiredobject—
on_shared_planboolean—
200401403404422429

Get a workspace

GET/api/v1/organizations/{id}/workspaces/{workspace_id}

GET /organizations/{id}/workspaces/{workspace_id}
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "external_id": "external_123",
  "plan": "string",
  "paid_by": "workspace",
  "requires_paid_plan": false,
  "sms_purchases_cap_cents": 0,
  "closed_at": "2026-01-01T00:00:00.000Z",
  "restorable_until": "2026-01-01T00:00:00.000Z",
  "deletes_at": "2026-01-01T00:00:00.000Z",
  "shared_plan": {
    "cap_cents": 0,
    "joined_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com"
}

One of the organization's workspaces. Takes an organization key (ok_live_…) with organizations:read.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredenumworkspace—
idrequiredstring`ws_…`
namerequiredstring—
slugrequiredstring—
external_idrequiredstringYour own id for it, unique in the organization.
planrequiredstring`free`, or the paid plan's key.
paid_byrequiredenumworkspace | organization—
requires_paid_planrequiredbooleanNo free allowance: the Owner already has a free workspace, so it sends once a plan is bought.
sms_purchases_cap_centsintegerThe workspace's monthly cap on SMS purchases by API, in cents (ADR-0114). Null: none, so every API purchase is refused with `api_spend_cap_not_set`.
closed_atrequiredstring—
restorable_untilrequiredstringOnce closed: the last moment it can be restored, 30 days after `closed_at`. Null while open.
deletes_atstringOnce closed: when it is deleted unless restored, the later of `restorable_until` and 7 days after the end of the billing period it closed in (so that period's usage stays readable). Its SMS numbers are released then. Null while open.
shared_planobjectOn the organization's shared plan: its cap on what it draws each period (`cap_cents`, null: none) and when it joined. Null when it isn't on it. Its usage is on `GET /organizations/{id}/shared-plan/workspaces`.
created_atrequiredstring—
hosted_invoice_urlstringOn create only: the card asked for authentication; paying here starts the plan.
200401403404429

Update a workspace

PATCH/api/v1/organizations/{id}/workspaces/{workspace_id}

PATCH /organizations/{id}/workspaces/{workspace_id}
curl -X PATCH 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Bakery & Cafe"
  }'
Response · 200
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "external_id": "external_123",
  "plan": "string",
  "paid_by": "workspace",
  "requires_paid_plan": false,
  "sms_purchases_cap_cents": 0,
  "closed_at": "2026-01-01T00:00:00.000Z",
  "restorable_until": "2026-01-01T00:00:00.000Z",
  "deletes_at": "2026-01-01T00:00:00.000Z",
  "shared_plan": {
    "cap_cents": 0,
    "joined_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com"
}

Rename a workspace, change its external_id (null clears it), or set its monthly SMS API spend cap (sms_purchases_cap_cents, null clears it). A cap above 0 needs a workspace the organization pays for and is at most the Owner's largest (Organization → API); 0 or null is always allowed. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Request body3 fields
FieldTypeDescription
namestring—
external_idstring—
sms_purchases_cap_centsintegerThe monthly SMS purchases cap, in cents; null clears it. Above 0 only on a workspace the organization pays for, and at most the Owner's largest.
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredenumworkspace—
idrequiredstring`ws_…`
namerequiredstring—
slugrequiredstring—
external_idrequiredstringYour own id for it, unique in the organization.
planrequiredstring`free`, or the paid plan's key.
paid_byrequiredenumworkspace | organization—
requires_paid_planrequiredbooleanNo free allowance: the Owner already has a free workspace, so it sends once a plan is bought.
sms_purchases_cap_centsintegerThe workspace's monthly cap on SMS purchases by API, in cents (ADR-0114). Null: none, so every API purchase is refused with `api_spend_cap_not_set`.
closed_atrequiredstring—
restorable_untilrequiredstringOnce closed: the last moment it can be restored, 30 days after `closed_at`. Null while open.
deletes_atstringOnce closed: when it is deleted unless restored, the later of `restorable_until` and 7 days after the end of the billing period it closed in (so that period's usage stays readable). Its SMS numbers are released then. Null while open.
shared_planobjectOn the organization's shared plan: its cap on what it draws each period (`cap_cents`, null: none) and when it joined. Null when it isn't on it. Its usage is on `GET /organizations/{id}/shared-plan/workspaces`.
created_atrequiredstring—
hosted_invoice_urlstringOn create only: the card asked for authentication; paying here starts the plan.
200401403404409422429

Close a workspace

POST/api/v1/organizations/{id}/workspaces/{workspace_id}/close

POST /organizations/{id}/workspaces/{workspace_id}/close
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123/close' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "external_id": "external_123",
  "plan": "string",
  "paid_by": "workspace",
  "requires_paid_plan": false,
  "sms_purchases_cap_cents": 0,
  "closed_at": "2026-01-01T00:00:00.000Z",
  "restorable_until": "2026-01-01T00:00:00.000Z",
  "deletes_at": "2026-01-01T00:00:00.000Z",
  "shared_plan": {
    "cap_cents": 0,
    "joined_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com"
}

The workspace stops working at once: its keys are revoked, every request to it is refused and its campaigns pause. Its SMS numbers renew nothing while it is closed. It can be restored for 30 days. Unless restored, it is deleted once those 30 days are over and 7 days have passed since the end of the billing period it closed in (so that period's usage stays readable with GET /organizations/{id}/usage), and its numbers are released then. Closing twice changes nothing. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredenumworkspace—
idrequiredstring`ws_…`
namerequiredstring—
slugrequiredstring—
external_idrequiredstringYour own id for it, unique in the organization.
planrequiredstring`free`, or the paid plan's key.
paid_byrequiredenumworkspace | organization—
requires_paid_planrequiredbooleanNo free allowance: the Owner already has a free workspace, so it sends once a plan is bought.
sms_purchases_cap_centsintegerThe workspace's monthly cap on SMS purchases by API, in cents (ADR-0114). Null: none, so every API purchase is refused with `api_spend_cap_not_set`.
closed_atrequiredstring—
restorable_untilrequiredstringOnce closed: the last moment it can be restored, 30 days after `closed_at`. Null while open.
deletes_atstringOnce closed: when it is deleted unless restored, the later of `restorable_until` and 7 days after the end of the billing period it closed in (so that period's usage stays readable). Its SMS numbers are released then. Null while open.
shared_planobjectOn the organization's shared plan: its cap on what it draws each period (`cap_cents`, null: none) and when it joined. Null when it isn't on it. Its usage is on `GET /organizations/{id}/shared-plan/workspaces`.
created_atrequiredstring—
hosted_invoice_urlstringOn create only: the card asked for authentication; paying here starts the plan.
200401403404429

Restore a workspace

POST/api/v1/organizations/{id}/workspaces/{workspace_id}/restore

POST /organizations/{id}/workspaces/{workspace_id}/restore
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123/restore' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "workspace",
  "id": "id_123",
  "name": "Example",
  "slug": "string",
  "external_id": "external_123",
  "plan": "string",
  "paid_by": "workspace",
  "requires_paid_plan": false,
  "sms_purchases_cap_cents": 0,
  "closed_at": "2026-01-01T00:00:00.000Z",
  "restorable_until": "2026-01-01T00:00:00.000Z",
  "deletes_at": "2026-01-01T00:00:00.000Z",
  "shared_plan": {
    "cap_cents": 0,
    "joined_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com"
}

Reopen a closed workspace within 30 days. Its old keys stay revoked: mint new ones. An SMS number renewal that fell due while it was closed is charged once, for the period in progress, and any grace resumes with the time it had left. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredenumworkspace—
idrequiredstring`ws_…`
namerequiredstring—
slugrequiredstring—
external_idrequiredstringYour own id for it, unique in the organization.
planrequiredstring`free`, or the paid plan's key.
paid_byrequiredenumworkspace | organization—
requires_paid_planrequiredbooleanNo free allowance: the Owner already has a free workspace, so it sends once a plan is bought.
sms_purchases_cap_centsintegerThe workspace's monthly cap on SMS purchases by API, in cents (ADR-0114). Null: none, so every API purchase is refused with `api_spend_cap_not_set`.
closed_atrequiredstring—
restorable_untilrequiredstringOnce closed: the last moment it can be restored, 30 days after `closed_at`. Null while open.
deletes_atstringOnce closed: when it is deleted unless restored, the later of `restorable_until` and 7 days after the end of the billing period it closed in (so that period's usage stays readable). Its SMS numbers are released then. Null while open.
shared_planobjectOn the organization's shared plan: its cap on what it draws each period (`cap_cents`, null: none) and when it joined. Null when it isn't on it. Its usage is on `GET /organizations/{id}/shared-plan/workspaces`.
created_atrequiredstring—
hosted_invoice_urlstringOn create only: the card asked for authentication; paying here starts the plan.
200401403404409429

Mint a workspace key

POST/api/v1/organizations/{id}/workspaces/{workspace_id}/api-keys

POST /organizations/{id}/workspaces/{workspace_id}/api-keys
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123/api-keys' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production",
    "scope": "sending"
  }'
Response · 201
{
  "object": "api_key",
  "id": "id_123",
  "key": "string",
  "prefix": "string",
  "scope": "full",
  "capabilities": [
    "string"
  ],
  "workspace_id": "workspace_123"
}

A workspace key for one of the organization's workspaces: it reaches only that workspace, can't manage keys, and is revoked with the organization key that minted it. The secret is returned once. opt_in_capabilities: ["sms:purchase"] adds SMS purchases (quote, then confirm), which no scope grants: only on a workspace the organization pays for that has an SMS purchases cap. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Request body3 fields
FieldTypeDescription
namerequiredstring—
scopeenumfull | sending | read_only—
opt_in_capabilitiesenum[]Capabilities no scope grants, added to the scope's. `sms:purchase` only on a workspace the organization pays for that has an SMS purchases cap.
Response · 201 fields7 fields
FieldTypeDescription
objectrequiredenumapi_key—
idrequiredstring`key_…`
keyrequiredstringThe secret, shown once.
prefixrequiredstring—
scoperequiredenumfull | sending | read_only—
capabilitiesrequiredstring[]—
workspace_idrequiredstring—
201401403404422429

Quote a plan change

POST/api/v1/organizations/{id}/workspaces/{workspace_id}/plan-quotes

POST /organizations/{id}/workspaces/{workspace_id}/plan-quotes
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123/plan-quotes' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "plan_quote",
  "id": "id_123",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "status": "open",
  "kind": "upgrade",
  "current": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "target": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "due_now_cents": 0,
  "carryover_cents": 0,
  "effective": "now",
  "effective_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com",
  "moves_to_organization": false,
  "pending_change": {
    "plan": "string",
    "tier_index": 0,
    "effective_at": "2026-01-01T00:00:00.000Z"
  },
  "confirm_token": "string"
}

What moving a workspace to plan and tier_index would do; nothing is changed or charged. kind is upgrade (now: the new price is charged in full, the billing period restarts, unused allowance carries over), downgrade (at the end of the period already paid), lateral (now), start (from free: now, on the organization's card), cancel (to free: the plan ends at the period end) or noop. The answer has the prices before and after, due_now_cents, effective_at and a single-use confirm_token, returned only here. A quote lasts 10 minutes. pending_change shows a downgrade already scheduled for the period end; with one, a quote for the current plan and tier is a noop whose confirm cancels it, so the workspace keeps its plan. On a workspace the organization pays for; or on a free workspace that pays for itself, a paid plan is a start billed to the organization (moves_to_organization: true), only while organization billing is on. Within the Owner's API rules: an allowed plan at a price no higher than their largest plan price (with none set, the lowest price of each allowed plan). The key's creator must still be an organization Owner. Takes an organization key (ok_live_…) with organizations:billing.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Request body2 fields
FieldTypeDescription
planrequiredstring`free`, or a paid plan the Owner's API rules allow.
tier_indexintegerThe stop on the paid plan's price ladder (default 0, its lowest price). Ignored for `free`.
Response · 201 fields19 fields
FieldTypeDescription
objectrequiredenumplan_quote—
idrequiredstring`pq_…`
workspace_idrequiredstring`ws_…`
external_idrequiredstringThe workspace's `external_id` when quoted.
statusrequiredenumopen | confirmed | expired`open` until confirmed or 10 minutes pass; `confirmed` once a confirm used it.
kindrequiredenumupgrade | downgrade | lateral | start | cancel | noop`upgrade`: now, charged in full, the period restarts, unused allowance carries over. `downgrade`: at the period end. `lateral`: now. `start`: from free, now. `cancel`: to free, at the period end. `noop`: the plan stays as it is; with a `pending_change`, the confirm cancels it (nothing charged).
currentrequiredOrganizationPlanStop—
targetrequiredOrganizationPlanStop—
due_now_centsrequiredintegerCharged to the organization's card on confirm: the new monthly price on an upgrade or a start, else 0 (before any discount). An upgrade restarts the billing period, so usage beyond the old plan's allowance this period, if any, is billed on the same invoice and is not in this number.
carryover_centsrequiredintegerUnused allowance carried into the new period (an upgrade only).
effectiverequiredenumnow | period_end—
effective_atrequiredstringWhen the change takes effect (once confirmed, when it did or will). Null for a `noop`, except one on a plan already set to end, where it is when the plan ends.
expires_atrequiredstring—
created_atrequiredstring—
confirmed_atrequiredstring—
hosted_invoice_urlrequiredstringAfter a confirm from free (`start`): the organization's card was declined or asked for authentication. The plan starts when this invoice is paid; unpaid, it lapses after about 23 hours, nothing is charged and the workspace stays on Free. Null otherwise.
moves_to_organizationrequiredbooleanA free workspace that pays for itself, started on a paid plan billed to the organization: the confirm moves it onto the organization's billing first.
pending_changerequiredobjectA downgrade already scheduled for the end of the period when the quote was made: the plan and stop it moves to, and when. Null when none is scheduled. With one, a quote for the current plan and tier is a `noop` whose confirm cancels it, so the workspace keeps its plan; an upgrade or a lateral move replaces it, another downgrade replaces it, and a cancel to free ends the plan instead.
confirm_tokenstringOn create only: the single-use token the confirm takes (`pqct_…`). Stored hashed; never shown again.
201401403404409422429

Get a plan quote

GET/api/v1/organizations/{id}/workspaces/{workspace_id}/plan-quotes/{quote_id}

GET /organizations/{id}/workspaces/{workspace_id}/plan-quotes/{quote_id}
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123/plan-quotes/pq_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "plan_quote",
  "id": "id_123",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "status": "open",
  "kind": "upgrade",
  "current": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "target": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "due_now_cents": 0,
  "carryover_cents": 0,
  "effective": "now",
  "effective_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com",
  "moves_to_organization": false,
  "pending_change": {
    "plan": "string",
    "tier_index": 0,
    "effective_at": "2026-01-01T00:00:00.000Z"
  },
  "confirm_token": "string"
}

A plan quote as it was offered, with its status (open, confirmed, expired) and, once confirmed, confirmed_at and hosted_invoice_url. Never the confirm token. Takes an organization key (ok_live_…) with organizations:read.

Parameters3 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
quote_idrequiredstring · pathThe plan quote's id (`pq_…`).
Response · 200 fields19 fields
FieldTypeDescription
objectrequiredenumplan_quote—
idrequiredstring`pq_…`
workspace_idrequiredstring`ws_…`
external_idrequiredstringThe workspace's `external_id` when quoted.
statusrequiredenumopen | confirmed | expired`open` until confirmed or 10 minutes pass; `confirmed` once a confirm used it.
kindrequiredenumupgrade | downgrade | lateral | start | cancel | noop`upgrade`: now, charged in full, the period restarts, unused allowance carries over. `downgrade`: at the period end. `lateral`: now. `start`: from free, now. `cancel`: to free, at the period end. `noop`: the plan stays as it is; with a `pending_change`, the confirm cancels it (nothing charged).
currentrequiredOrganizationPlanStop—
targetrequiredOrganizationPlanStop—
due_now_centsrequiredintegerCharged to the organization's card on confirm: the new monthly price on an upgrade or a start, else 0 (before any discount). An upgrade restarts the billing period, so usage beyond the old plan's allowance this period, if any, is billed on the same invoice and is not in this number.
carryover_centsrequiredintegerUnused allowance carried into the new period (an upgrade only).
effectiverequiredenumnow | period_end—
effective_atrequiredstringWhen the change takes effect (once confirmed, when it did or will). Null for a `noop`, except one on a plan already set to end, where it is when the plan ends.
expires_atrequiredstring—
created_atrequiredstring—
confirmed_atrequiredstring—
hosted_invoice_urlrequiredstringAfter a confirm from free (`start`): the organization's card was declined or asked for authentication. The plan starts when this invoice is paid; unpaid, it lapses after about 23 hours, nothing is charged and the workspace stays on Free. Null otherwise.
moves_to_organizationrequiredbooleanA free workspace that pays for itself, started on a paid plan billed to the organization: the confirm moves it onto the organization's billing first.
pending_changerequiredobjectA downgrade already scheduled for the end of the period when the quote was made: the plan and stop it moves to, and when. Null when none is scheduled. With one, a quote for the current plan and tier is a `noop` whose confirm cancels it, so the workspace keeps its plan; an upgrade or a lateral move replaces it, another downgrade replaces it, and a cancel to free ends the plan instead.
confirm_tokenstringOn create only: the single-use token the confirm takes (`pqct_…`). Stored hashed; never shown again.
200401403404429

Confirm a plan quote

POST/api/v1/organizations/{id}/workspaces/{workspace_id}/plan-quotes/{quote_id}/confirm

POST /organizations/{id}/workspaces/{workspace_id}/plan-quotes/{quote_id}/confirm
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/workspaces/ws_123/plan-quotes/pq_123/confirm' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "plan_quote",
  "id": "id_123",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "status": "open",
  "kind": "upgrade",
  "current": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "target": {
    "plan": "string",
    "tier_index": 0,
    "price_monthly_cents": 0
  },
  "due_now_cents": 0,
  "carryover_cents": 0,
  "effective": "now",
  "effective_at": "2026-01-01T00:00:00.000Z",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "confirmed_at": "2026-01-01T00:00:00.000Z",
  "hosted_invoice_url": "https://example.com",
  "moves_to_organization": false,
  "pending_change": {
    "plan": "string",
    "tier_index": 0,
    "effective_at": "2026-01-01T00:00:00.000Z"
  },
  "confirm_token": "string"
}

Apply a plan quote, once: the body is its confirm_token, and Idempotency-Key is required (a retry with it answers what the first call did and never applies twice). The change takes effect as the quote said, the same as a plan change in the dashboard. Everything the quote assumed is checked again: today's API rules, who pays, and that the workspace's plan didn't change since (quote_stale). A card that refuses the charge is 402 payment_failed: nothing changed and the quote stays open until it expires. That is for an upgrade (a lateral move charges nothing now, only Stripe's proration on the next invoice): a start from free behaves as a paid create does, so a card that is declined or asks for authentication still answers 200 confirmed, with hosted_invoice_url; the plan starts when that invoice is paid, and unpaid it lapses after about 23 hours (nothing charged) and the workspace stays on Free. While a change is still being written back (or a first invoice waits), a new quote or confirm for the workspace is 409 conflict with details[0].code: "plan_change_in_progress". A quote with moves_to_organization first moves the free workspace onto the organization's billing (one of its card's workspace slots; at the limit it is 409 and nothing is charged) and, if it has no SMS purchases cap, gives it the Owner's default, as a paid create does. Every refusal frees the Idempotency-Key. The workspace's activity log names the organization key, and the organization's Owners and Billing members get an email about the change. The key's creator must still be an organization Owner. Takes an organization key (ok_live_…) with organizations:billing.

Parameters4 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
quote_idrequiredstring · pathThe plan quote's id (`pq_…`).
Idempotency-Keyrequiredstring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
confirm_tokenrequiredstringThe quote's `confirm_token` (`pqct_…`) from its create response. Single use.
Response · 200 fields19 fields
FieldTypeDescription
objectrequiredenumplan_quote—
idrequiredstring`pq_…`
workspace_idrequiredstring`ws_…`
external_idrequiredstringThe workspace's `external_id` when quoted.
statusrequiredenumopen | confirmed | expired`open` until confirmed or 10 minutes pass; `confirmed` once a confirm used it.
kindrequiredenumupgrade | downgrade | lateral | start | cancel | noop`upgrade`: now, charged in full, the period restarts, unused allowance carries over. `downgrade`: at the period end. `lateral`: now. `start`: from free, now. `cancel`: to free, at the period end. `noop`: the plan stays as it is; with a `pending_change`, the confirm cancels it (nothing charged).
currentrequiredOrganizationPlanStop—
targetrequiredOrganizationPlanStop—
due_now_centsrequiredintegerCharged to the organization's card on confirm: the new monthly price on an upgrade or a start, else 0 (before any discount). An upgrade restarts the billing period, so usage beyond the old plan's allowance this period, if any, is billed on the same invoice and is not in this number.
carryover_centsrequiredintegerUnused allowance carried into the new period (an upgrade only).
effectiverequiredenumnow | period_end—
effective_atrequiredstringWhen the change takes effect (once confirmed, when it did or will). Null for a `noop`, except one on a plan already set to end, where it is when the plan ends.
expires_atrequiredstring—
created_atrequiredstring—
confirmed_atrequiredstring—
hosted_invoice_urlrequiredstringAfter a confirm from free (`start`): the organization's card was declined or asked for authentication. The plan starts when this invoice is paid; unpaid, it lapses after about 23 hours, nothing is charged and the workspace stays on Free. Null otherwise.
moves_to_organizationrequiredbooleanA free workspace that pays for itself, started on a paid plan billed to the organization: the confirm moves it onto the organization's billing first.
pending_changerequiredobjectA downgrade already scheduled for the end of the period when the quote was made: the plan and stop it moves to, and when. Null when none is scheduled. With one, a quote for the current plan and tier is a `noop` whose confirm cancels it, so the workspace keeps its plan; an upgrade or a lateral move replaces it, another downgrade replaces it, and a cancel to free ends the plan instead.
confirm_tokenstringOn create only: the single-use token the confirm takes (`pqct_…`). Stored hashed; never shown again.
200400401402403404409422429500

Get the shared plan

GET/api/v1/organizations/{id}/shared-plan

GET /organizations/{id}/shared-plan
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/shared-plan' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "shared_plan",
  "approved": false,
  "requested_at": "2026-01-01T00:00:00.000Z",
  "status": "none",
  "plan": "string",
  "tier_index": 0,
  "price_monthly_cents": 0,
  "period_start": "2026-01-01T00:00:00.000Z",
  "period_end": "2026-01-01T00:00:00.000Z",
  "cancel_at": "2026-01-01T00:00:00.000Z",
  "allowance_cents": 0,
  "used_cents": 0,
  "overage_cents": 0,
  "overage_cap_cents": 0,
  "paused": false,
  "overage_frozen": false,
  "workspace_limit": 1,
  "workspaces": 0
}

The organization's shared plan: one plan whose allowance its workspaces share. approved says whether Unitpost's team turned it on for the organization (it is never on by default: an Owner or Billing member asks on Organization → Billing, requested_at). status is none until a plan is bought there, then the plan's status. With a plan: its plan, tier_index and list price_monthly_cents, the billing period, cancel_at (set to end at the period end), the shared allowance_cents, what its workspaces drew this period (used_cents, overage_cents beyond the allowance), the overage band's size (overage_cap_cents, null for no band), paused (the allowance and band are used up: every workspace on it stops sending until the period renews), overage_frozen (Unitpost paused overage: sending stops at the allowance) and how many workspaces it covers (workspace_limit) and has (workspaces). Buying, upgrading and ending the plan, and raising its workspace number, are done in the dashboard. Takes an organization key (ok_live_…) with organizations:read.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
Response · 200 fields18 fields
FieldTypeDescription
objectrequiredenumshared_plan—
approvedrequiredbooleanUnitpost's team turned the shared plan on for the organization; it is never on by default.
requested_atrequiredstringWhen an Owner or Billing member asked for it (Organization → Billing); null if nobody has.
statusrequiredenumnone | active | trialing | past_due | paused | canceled`none` until a plan is bought; then the plan's status. `past_due` keeps its workspaces but takes no new ones; `canceled` once it ended (its workspaces left it).
planrequiredstringThe plan's key (`pro` is Starter, `scale` is Growth); null with none.
tier_indexrequiredintegerThe stop on the plan's price ladder.
price_monthly_centsrequiredintegerThe stop's list price a month, before any discount or promotion code.
period_startrequiredstring—
period_endrequiredstring—
cancel_atrequiredstringSet to end then (the period end); null while it renews.
allowance_centsrequiredintegerThe allowance its workspaces share each period, in cents of sending (email, SMS, WhatsApp).
used_centsrequiredintegerWhat its workspaces drew this period, including workspaces that left during it. 0 with no plan.
overage_centsrequiredintegerThe part of `used_cents` beyond the allowance, billed at the plan's overage rate.
overage_cap_centsrequiredintegerThe overage band: how far past the allowance its workspaces may send in a period. Null: no band.
pausedrequiredbooleanThe allowance and the band are used up (only the allowance while `overage_frozen`): every workspace on the plan stops sending until the period renews or the plan is upgraded.
overage_frozenrequiredbooleanUnitpost's team paused overage on the plan (a disputed charge): sending stops at the allowance.
workspace_limitrequiredintegerHow many workspaces the plan covers (Starter 3, Growth 10, unless Unitpost's team set another number). Before a plan is bought, the number set for the organization, or null for the plan's own.
workspacesrequiredintegerHow many workspaces are on it now.
200401403404429

List the shared plan's workspaces

GET/api/v1/organizations/{id}/shared-plan/workspaces

GET /organizations/{id}/shared-plan/workspaces
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/shared-plan/workspaces' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "shared_plan_workspace",
      "workspace_id": "workspace_123",
      "external_id": "external_123",
      "name": "Example",
      "cap_cents": 0,
      "joined_at": "2026-01-01T00:00:00.000Z",
      "used_cents": 0
    }
  ]
}

Every workspace on the shared plan now, oldest first: its id, your external_id, name, its cap (cap_cents: what it may draw each period, allowance and overage together; null for none), joined_at, and what it drew this period (used_cents). One page: a shared plan covers a bounded number of workspaces, so has_more is always false. Takes an organization key (ok_live_…) with organizations:read.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredenumshared_plan_workspace—
workspace_idrequiredstring`ws_…`
external_idrequiredstringYour own id for it, if you gave one.
namerequiredstring—
cap_centsrequiredintegerWhat it may draw from the shared plan each period, allowance and overage together. Null: no cap.
joined_atrequiredstring—
used_centsrequiredintegerWhat it drew this period, counted against its cap.
200401403404429

Set a workspace's shared plan cap

PATCH/api/v1/organizations/{id}/shared-plan/workspaces/{workspace_id}

PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}
curl -X PATCH 'https://www.unitpost.com/api/v1/organizations/org_123/shared-plan/workspaces/ws_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "shared_plan_workspace",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "name": "Example",
  "cap_cents": 0,
  "joined_at": "2026-01-01T00:00:00.000Z",
  "used_cents": 0
}

Set what a workspace on the shared plan may draw from it each period, allowance and overage together, in cents (cap_cents; 0 stops it drawing at all, null removes the cap). At its cap only that workspace pauses (quota_exceeded); caps may add up to more than the plan. The workspace's activity log names the key. The key's creator must still be an organization Owner. Takes an organization key (ok_live_…) with organizations:billing.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Request body1 field
FieldTypeDescription
cap_centsrequiredintegerIts cap, in cents a period: 0 stops it drawing, null removes the cap.
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredenumshared_plan_workspace—
workspace_idrequiredstring`ws_…`
external_idrequiredstringYour own id for it, if you gave one.
namerequiredstring—
cap_centsrequiredintegerWhat it may draw from the shared plan each period, allowance and overage together. Null: no cap.
joined_atrequiredstring—
used_centsrequiredintegerWhat it drew this period, counted against its cap.
200400401403404422429

Add a workspace to the shared plan

PUT/api/v1/organizations/{id}/shared-plan/workspaces/{workspace_id}

PUT /organizations/{id}/shared-plan/workspaces/{workspace_id}
curl -X PUT 'https://www.unitpost.com/api/v1/organizations/org_123/shared-plan/workspaces/ws_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "shared_plan_workspace",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "name": "Example",
  "cap_cents": 0,
  "joined_at": "2026-01-01T00:00:00.000Z",
  "used_cents": 0
}

Put one of the organization's workspaces on the shared plan, with an optional cap_cents (left out: no cap). It moves onto the organization's card (one more workspace on its billing) and draws on the shared allowance from now; its own usage this period so far stays its own. Already on it: cap_cents, when sent, sets its cap, and nothing else changes. Refused with the reason in details[0].code: not_approved (403: the shared plan isn't turned on), no_plan or plan_inactive (none bought, not active, or set to end), own_plan (it pays for a plan of its own: set that to end first), grant (a plan Unitpost's team gave it), payer_change (a change of who pays is scheduled), suspended, closed, already_member (on another shared plan) or limit_reached (the plan covers no more workspaces, or the organization's card is at its workspace limit), all 409 but the first. Idempotency-Key is optional: a retry with it answers what the first call did. The workspace's activity log names the key. The key's creator must still be an organization Owner. Takes an organization key (ok_live_…) with organizations:billing.

Parameters3 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body1 field
FieldTypeDescription
cap_centsintegerIts cap, in cents a period (0 stops it drawing, null: none). Left out: none on a join, unchanged when it is already on the plan.
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredenumshared_plan_workspace—
workspace_idrequiredstring`ws_…`
external_idrequiredstringYour own id for it, if you gave one.
namerequiredstring—
cap_centsrequiredintegerWhat it may draw from the shared plan each period, allowance and overage together. Null: no cap.
joined_atrequiredstring—
used_centsrequiredintegerWhat it drew this period, counted against its cap.
200400401403404409422429

Remove a workspace from the shared plan

DELETE/api/v1/organizations/{id}/shared-plan/workspaces/{workspace_id}

DELETE /organizations/{id}/shared-plan/workspaces/{workspace_id}
curl -X DELETE 'https://www.unitpost.com/api/v1/organizations/org_123/shared-plan/workspaces/ws_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "shared_plan_removal",
  "workspace_id": "workspace_123",
  "external_id": "external_123",
  "left": false,
  "drops_to": "free"
}

Take a workspace off the shared plan. Its usage this period stays counted on the plan. It drops to Free if its Owner's one free workspace is unused, else it needs a plan before it sends again (drops_to: free or needs_plan); it stays on the organization's billing, so a plan bought for it is billed to the organization. A workspace not on the shared plan answers left: false and nothing changes. Idempotency-Key is optional: a retry with it answers what the first call did. The workspace's activity log names the key. The key's creator must still be an organization Owner. Takes an organization key (ok_live_…) with organizations:billing.

Parameters3 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
workspace_idrequiredstring · pathThe workspace's id (`ws_…`).
Idempotency-Keystring · headerAny unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredenumshared_plan_removal—
workspace_idrequiredstring`ws_…`
external_idrequiredstring—
leftrequiredbooleanFalse when it wasn't on the shared plan: nothing changed.
drops_torequiredenum | null`free`: it is on Free (its Owner's one free workspace). `needs_plan`: it sends again once a plan is bought for it. Null when `left` is false.
200400401403404409429

List the organization's webhook endpoints

GET/api/v1/organizations/{id}/webhooks

GET /organizations/{id}/webhooks
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook",
      "id": "id_123",
      "name": "Example",
      "url": "https://example.com",
      "events": [
        "email.sent"
      ],
      "status": "enabled",
      "include_text": false,
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "backlog": {
        "queued": 0,
        "failed": 0
      }
    }
  ]
}

The organization's webhook endpoints, newest first and cursor-paginated (limit, after, before). Signing secrets are never returned here. A workspace's own endpoints (/webhooks) are not listed. Takes an organization key (ok_live_…) with organizations:read.

Parameters4 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
200401403404422429

Create an organization webhook endpoint

POST/api/v1/organizations/{id}/webhooks

POST /organizations/{id}/webhooks
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhooks/unitpost",
    "events": [
      "email.delivered",
      "email.bounced"
    ]
  }'
Response · 201
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  },
  "signing_secret": "string"
}

Register an https URL that receives the events of every workspace in the organization, closed ones included while they exist, for the event types it subscribes to (as on POST /webhooks). Workspaces' own endpoints keep receiving theirs: an event goes to each matching endpoint of either kind. Each delivery's envelope names the workspace the event happened in (workspace_id) and that workspace's external_id as it is when the delivery is made (null when it has none); a workspace endpoint's envelope has no external_id. The response includes the signing_secret exactly once. Names and URLs are unique in the organization. At most 5 endpoints per organization: the next create is a 422 and creates nothing. One endpoint already receives every workspace's events, so add event types to an existing endpoint (update its events) instead of adding endpoints. Takes an organization key (ok_live_…) with organizations:write.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
Request body4 fields
FieldTypeDescription
urlrequiredstring—
eventsrequiredenum | string[]—
namestring—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
Response · 201 fields11 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
signing_secretrequiredstringThe HMAC signing secret. Shown exactly once — store it now; it can never be retrieved again. Use it to verify the signature on every delivery to this endpoint.
201401403404409422429

Get an organization webhook endpoint

GET/api/v1/organizations/{id}/webhooks/{webhook_id}

GET /organizations/{id}/webhooks/{webhook_id}
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  }
}

One organization webhook endpoint, without its secret. backlog counts the deliveries a flush would send: queued while the endpoint was paused, and failed. Takes an organization key (ok_live_…) with organizations:read.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
200401403404429503

Update an organization webhook endpoint

PATCH/api/v1/organizations/{id}/webhooks/{webhook_id}

PATCH /organizations/{id}/webhooks/{webhook_id}
curl -X PATCH 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      "email.delivered"
    ]
  }'
Response · 200
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  }
}

Change the endpoint's url, events, name, status or include_text, as PATCH /webhooks/{id} does. Re-enabling clears its failure streak; it never delivers the backlog on its own. The signing secret never changes here. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
Request body5 fields
FieldTypeDescription
urlstring—
eventsenum | string[]—
namestring—
statusenumenabled | disabled—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
200401403404409422429

Delete an organization webhook endpoint

DELETE/api/v1/organizations/{id}/webhooks/{webhook_id}

DELETE /organizations/{id}/webhooks/{webhook_id}
curl -X DELETE 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'

Delete the endpoint and its delivery log. Deliveries stop at once. Deleting one already gone still answers 204. To pause deliveries instead, set status to disabled. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
204401403404429

Rotate an organization webhook's signing secret

POST/api/v1/organizations/{id}/webhooks/{webhook_id}/rotate-secret

POST /organizations/{id}/webhooks/{webhook_id}/rotate-secret
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123/rotate-secret' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  },
  "signing_secret": "string",
  "previous_secret_expires_at": "2026-01-01T00:00:00.000Z"
}

A new signing secret, returned once. For 24 hours (until previous_secret_expires_at) every delivery is signed with the new and the old secret, so switch your receiver inside that window. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
Response · 200 fields1 field
FieldTypeDescription
previous_secret_expires_atrequiredstringUntil this time deliveries are signed with the new AND the old secret, so switch your receiver to the new one before then.
200401403404409429

Send a test event to an organization webhook

POST/api/v1/organizations/{id}/webhooks/{webhook_id}/test

POST /organizations/{id}/webhooks/{webhook_id}/test
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123/test' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "webhook_test",
  "delivered": false,
  "response_status": 0,
  "event_type": "string",
  "error": "string"
}

Send a sample event now, signed like a real delivery, and answer with your endpoint's response. It is not kept in the delivery log. A test happens in no workspace: its workspace_id and external_id are null. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredenumwebhook_test—
deliveredrequiredbooleanWhether the endpoint accepted the probe (2xx).
response_statusrequiredintegerThe HTTP status the endpoint returned, or null on a transport error.
event_typerequiredstringThe sample event type that was sent.
errorrequiredstringA transport/error message when delivery failed, else null.
200401403404429

List an organization webhook's deliveries

GET/api/v1/organizations/{id}/webhooks/{webhook_id}/deliveries

GET /organizations/{id}/webhooks/{webhook_id}/deliveries
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123/deliveries' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook_delivery",
      "id": "id_123",
      "svix_id": "svix_123",
      "webhook_id": "webhook_123",
      "event_id": "event_123",
      "event_type": "string",
      "status": "pending",
      "attempt": 0,
      "response_status": 0,
      "error": "string",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "next_attempt_at": "2026-01-01T00:00:00.000Z",
      "delivered_at": "2026-01-01T00:00:00.000Z",
      "event_created_at": "2026-01-01T00:00:00.000Z",
      "data": {},
      "workspace_id": "workspace_123",
      "external_id": "external_123"
    }
  ]
}

The endpoint's delivery log, newest first and cursor-paginated, as GET /webhooks/{id}/deliveries. Each row also names the event's workspace (workspace_id) and that workspace's external_id now. Narrow it with status, event_type, and one workspace by workspace_id or external_id. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. A workspace_id or external_id it can't read (malformed, too long, sent twice) is not ignored: the page is empty, named in Unitpost-Warning, never every workspace's deliveries. Each row carries its event's data (message content of every workspace), so this takes organizations:write; a key with only organizations:read gets 403 insufficient_scope. Takes an organization key (ok_live_…) with organizations:write.

Parameters9 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
statusstring · queryOne or more delivery statuses, comma-separated: `pending`, `queued`, `retrying`, `succeeded`, `failed`, `exhausted`.
event_typestring · queryOnly deliveries of this event type, e.g. `email.bounced`.
workspace_idstring · queryOnly events of this workspace (`ws_…`).
external_idstring · queryOnly events of the workspace with this `external_id`.
Response · 200 fields17 fields
FieldTypeDescription
objectrequiredenumwebhook_delivery—
idrequiredstringThe delivery id (`msg_…`).
svix_idrequiredstringThe `svix-id` header this delivery's requests carried; retries reuse it, so dedupe on it.
webhook_idrequiredstring—
event_idrequiredstringThe event (`evt_…`). The delivered payload's `event_id` is the same id without the `evt_` prefix.
event_typerequiredstring—
statusrequiredenumpending | queued | retrying | succeeded | failed | exhausted`queued`: held while the endpoint is disabled. `retrying`: an attempt failed and another is scheduled at `next_attempt_at`. `exhausted`: every retry failed.
attemptrequiredintegerAttempts made so far.
response_statusrequiredintegerYour endpoint's last HTTP status, or null before an attempt or on a network error.
errorrequiredstring—
scheduled_atrequiredstring—
next_attempt_atrequiredstring—
delivered_atrequiredstring—
event_created_atrequiredstring—
datarequiredobjectThe event's `data`, as delivered.
workspace_idrequiredstringThe workspace the event happened in (`ws_…`).
external_idrequiredstringThat workspace's `external_id` now (the delivered envelope carried the one at delivery time); null when it has none.
200401403404422429503

Replay an organization webhook delivery

POST/api/v1/organizations/{id}/webhooks/{webhook_id}/deliveries/{delivery}/replay

POST /organizations/{id}/webhooks/{webhook_id}/deliveries/{delivery}/replay
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123/deliveries/msg_123/replay' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "object": "webhook_delivery_replay",
  "webhook_id": "webhook_123",
  "delivery_id": "delivery_123",
  "replayed": true
}

Deliver one event to the endpoint again, with the same id, as POST /webhooks/{id}/deliveries/{delivery}/replay. The endpoint must be enabled. Takes no body. Takes an organization key (ok_live_…) with organizations:write.

Parameters3 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
deliveryrequiredstring · pathThe delivery's id (`msg_…`).
Response · 202 fields4 fields
FieldTypeDescription
objectrequiredenumwebhook_delivery_replay—
webhook_idrequiredstring—
delivery_idrequiredstring—
replayedrequiredenumtrue—
202400401403404409422429502

Deliver an organization webhook's backlog

POST/api/v1/organizations/{id}/webhooks/{webhook_id}/flush

POST /organizations/{id}/webhooks/{webhook_id}/flush
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks/wh_123/flush' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "include_failed": true
  }'
Response · 202
{
  "object": "webhook_flush",
  "webhook_id": "webhook_123",
  "flushed": 0
}

Deliver the deliveries held while the endpoint was suspended (queued); with include_failed also the ones that failed for good. The endpoint must be enabled: re-enabling never delivers the backlog on its own. Takes an organization key (ok_live_…) with organizations:write.

Parameters2 fields
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
webhook_idrequiredstring · pathThe organization webhook endpoint's id (`wh_…`).
Request body1 field
FieldTypeDescription
include_failedbooleanAlso deliver the `failed` and `exhausted` deliveries again. Default false: only the `queued` ones (held while the webhook was suspended).
Response · 202 fields3 fields
FieldTypeDescription
objectrequiredenumwebhook_flush—
webhook_idrequiredstring—
flushedrequiredintegerHow many deliveries were handed back for delivery (0 when the backlog was empty).
202400401403404409422429502

API keys

Create and revoke the API keys your integrations authenticate with. Each key has a scope: full, sending, read_only, or an explicit capabilities list (paid plans for read_only and custom lists); a request outside the key's capabilities returns 403 insufficient_scope. No key can manage keys, the team, the workspace or billing. Creating and revoking keys is session-gated (dashboard cookie + apikeys:manage) and NOT usable with a Bearer API key; listing keys and a key's usage take a key or app holding apikeys:read, which no preset includes.

List API keys

GET/api/v1/api-keys

GET /api-keys
curl -X GET 'https://www.unitpost.com/api/v1/api-keys' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "api_key",
      "id": "id_123",
      "name": "Example",
      "prefix": "string",
      "scope": "full",
      "capabilities": [
        "string"
      ],
      "last_used_at": "2026-01-01T00:00:00.000Z",
      "revoked_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your workspace's API keys — the key prefix, scope, capabilities and last use, never the secret. With an API key or an MCP sign-in it needs apikeys:read, which no key preset includes: tick it on the key that audits your keys. From a dashboard session it needs apikeys:manage. See how a key is used with Retrieve an API key's usage. Creating (Create an API key) and revoking (Revoke an API key) keys stay in a dashboard session. Requires the apikeys:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
prefixrequiredstring—
scoperequiredenumfull | sending | read_only—
capabilitiesrequiredstring[]—
last_used_atrequiredstring | null—
revoked_atrequiredstring | null—
created_atrequiredstring—
200401403422

Create an API key

POST/api/v1/api-keys

POST /api-keys
curl -X POST 'https://www.unitpost.com/api/v1/api-keys' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Production server",
    "capabilities": [
      "emails:send"
    ]
  }'
Response · 201
{
  "object": "api_key",
  "id": "id_123",
  "name": "Example",
  "prefix": "string",
  "scope": "full",
  "capabilities": [
    "string"
  ],
  "last_used_at": "2026-01-01T00:00:00.000Z",
  "revoked_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "key": "string"
}

Create an API key scoped to the capabilities you choose. The response includes the plaintext key exactly once — store it securely now, because it can never be retrieved again (only revoked). This endpoint is session-gated: it requires a dashboard session and cannot be called with a Bearer API key.

Request body3 fields
FieldTypeDescription
namerequiredstring—
scopeenumfull | sending | read_only—
capabilitiesenum[]—
Response · 201 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
prefixrequiredstring—
scoperequiredenumfull | sending | read_only—
capabilitiesrequiredstring[]—
last_used_atrequiredstring | null—
revoked_atrequiredstring | null—
created_atrequiredstring—
keyrequiredstringThe plaintext secret. Shown exactly once — store it now; it can never be retrieved again.
201401403422

List request logs

GET/api/v1/logs

GET /logs
curl -X GET 'https://www.unitpost.com/api/v1/logs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "request_log",
      "id": "id_123",
      "request_id": "request_123",
      "method": "string",
      "path": "string",
      "status": 0,
      "duration_ms": 0,
      "api_key_id": "api_key_123",
      "user_agent": "string",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Your workspace's API request log, newest first and cursor-paginated: each call's method, path, status, time taken, the API key that made it and its x-request-id (quote it to support). Never the caller's IP and never a body. Narrow with status (a code, or a class such as 4xx), api_key_id, method, path_prefix (e.g. /email), request_id and a created_after / created_before range. Rows are kept 30 days. Needs apikeys:read, which no key preset includes, and has its own per-workspace rate limit. Requires the apikeys:read capability.

Parameters10 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
statusstring · queryA status code (e.g. `429`) or a class: `2xx`, `3xx`, `4xx`, `5xx`.
api_key_idstring · queryOnly one API key's calls (`key_…`).
methodstring · queryOnly one HTTP method.
path_prefixstring · queryOnly paths under this one, as in this reference (e.g. `/email/campaigns`): whole path segments, matched literally (`/email` matches `/email` and `/email/campaigns`, not `/emails`). It can't name an email address or a phone number (paths show them as `{email}` / `{phone}`).
request_idstring · queryOne call, by the `x-request-id` its response carried. Searches the last 24 hours unless `created_after` is given.
created_afterstring · queryCalls at or after this time (ISO 8601 with a zone).
created_beforestring · queryCalls before this time (ISO 8601 with a zone).
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe log row (`rlog_…`); page with it as `after` / `before`.
request_idrequiredstring | nullThe `x-request-id` the response carried: quote it to support.
methodrequiredstring—
pathrequiredstringThe path called, without the host and `/api/v1` (e.g. `/email/email_…`); no query string. An email address or phone number in it reads `{email}` / `{phone}`.
statusrequiredintegerThe HTTP status answered.
duration_msrequiredinteger | nullHow long the request took to answer.
api_key_idrequiredstring | nullThe API key that called (`key_…`); null for an MCP or CLI sign-in, or a key since deleted.
user_agentrequiredstring | null—
created_atrequiredstring—
200401403422429503

Retrieve an API key's usage

GET/api/v1/api-keys/{id}/usage

GET /api-keys/{id}/usage
curl -X GET 'https://www.unitpost.com/api/v1/api-keys/key_123/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "api_key_usage",
  "id": "id_123",
  "last_used_at": "2026-01-01T00:00:00.000Z",
  "requests_24h": 0,
  "client_errors_24h": 0,
  "server_errors_24h": 0,
  "rate_limited_24h": 1
}

One key's last 24 hours: how many requests it made, how many were answered 4xx, 5xx or 429, and when it was last used. Check it before you revoke a key (is anything still calling with it?) or when an integration's calls fail. The dashboard's revoke dialog reads the same count. Needs apikeys:read, which no key preset includes. Requires the apikeys:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstringThe key (`key_…`).
last_used_atrequiredstring | null—
requests_24hrequiredintegerRequests the key made in the last 24 hours, counted up to 100,000: `100001` means more than 100,000.
client_errors_24hrequiredintegerOf those, answered 4xx (`rate_limited_24h` included). Past the cap, these three count the latest 100,001 requests.
server_errors_24hrequiredintegerOf those, answered 5xx.
rate_limited_24hrequiredintegerOf those, answered 429.
200401403404422503

Revoke an API key

DELETE/api/v1/api-keys/{id}

DELETE /api-keys/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/api-keys/key_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Permanently revoke an API key. Requests made with it start failing with 401 immediately, and revocation cannot be undone — create a replacement first with Create an API key if you're rotating. This endpoint is session-gated: it requires a dashboard session and cannot be called with a Bearer API key.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404

Suppressions

Address-level send blocks — the hard "never email this address" list. Combines engine-written bounce/complaint entries, your own additions, and read-only Unitpost-wide blocks.

List suppressed addresses

GET/api/v1/suppressions

GET /suppressions
curl -X GET 'https://www.unitpost.com/api/v1/suppressions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "suppression",
      "id": "id_123",
      "email": "customer@example.com",
      "scope": "workspace",
      "reason": "bounce",
      "detail": "string",
      "note": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of the email addresses your workspace has suppressed, newest-first and cursor-paginated. The list holds your workspace's own suppressions only. Unitpost-wide (platform) blocks are enforced at send time but never listed: they appear as email.suppressed on the send they stopped, and Retrieve a suppressed address with an email address still returns one, so you can see why that address is blocked. (Since 2026-10-13; before that the list also included platform rows.) Add an address with Suppress an address or lift a block with Un-suppress an address. Narrow the list with q, reason and a created_after / created_before range. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. Requires the suppressions:read capability.

Parameters8 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
qstring · queryPart of the email address (case-insensitive). At most 200 characters.
reasonstring · queryOnly suppressions with this reason.
created_afterstring · queryOnly suppressions created at or after this time. ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time).
created_beforestring · queryOnly suppressions created before this time. ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time).
scopestring · queryDeprecated and ignored (2026-10-13). The list always returns your workspace's own suppressions; platform rows are never listed. Still accepted so existing callers don't break.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring—
scoperequiredenumworkspace | platform—
reasonrequiredenumbounce | complaint | unsubscribe | manual | import | api—
detailrequiredstring | null—
noterequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403422

Suppress an address

POST/api/v1/suppressions

POST /suppressions
curl -X POST 'https://www.unitpost.com/api/v1/suppressions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "suppression",
  "id": "id_123",
  "email": "customer@example.com",
  "scope": "workspace",
  "reason": "bounce",
  "detail": "string",
  "note": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Block one address ({ email }) or up to 1,000 at once ({ emails: [...] }) from receiving any future sends from your workspace. The operation is idempotent — re-suppressing an existing address returns 200 rather than a conflict. The bulk form returns an { object: "list", added, skipped, total } summary. Suppression is the hard stop; to let recipients opt out of just one kind of email, use topics (see Create a topic). Undo with Un-suppress an address. Requires the suppressions:write capability.

Request body4 fields
FieldTypeDescription
emailstring—
emailsstring[]—
reasonenummanual | import | api—
notestring—
200201401403422

Retrieve a suppressed address

GET/api/v1/suppressions/{id}

GET /suppressions/{id}
curl -X GET 'https://www.unitpost.com/api/v1/suppressions/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "suppression",
  "id": "id_123",
  "email": "customer@example.com",
  "scope": "workspace",
  "reason": "bounce",
  "detail": "string",
  "note": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve one suppression by id (supp_…) or by the email address itself. Returns your own workspace row, or a read-only platform row when the address is blocked Unitpost-wide. Lift a workspace block with Un-suppress an address. Requires the suppressions:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathA suppression id (`supp_…`) or the email address.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
emailrequiredstring—
scoperequiredenumworkspace | platform—
reasonrequiredenumbounce | complaint | unsubscribe | manual | import | api—
detailrequiredstring | null—
noterequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404

Un-suppress an address

DELETE/api/v1/suppressions/{id}

DELETE /suppressions/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/suppressions/123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Remove a workspace suppression by id or email so the address can receive your mail again. The email form is idempotent — removing an address that isn't suppressed still returns 204. Unitpost-wide (platform) entries can't be removed here (403) — contact support. Check what's blocking an address first with Retrieve a suppressed address. Requires the suppressions:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · pathA suppression id (`supp_…`) or the email address.
204401403404

Usage

Your workspace's current billing-period usage: emails sent, and on paid plans the dollar sending wallet (monthly allowance, spend, purchased credit, overage) in integer USD cents. Spend caps: the monthly limits on what API keys and apps may spend, today the cap on SMS purchases (GET/PATCH /spend-caps).

Retrieve usage

GET/api/v1/usage

GET /usage
curl -X GET 'https://www.unitpost.com/api/v1/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "usage",
  "plan": "string",
  "period_start": "string",
  "period_end": "string",
  "emails": {
    "sent": 0,
    "included": 0,
    "daily_cap": 0,
    "sent_today": 0
  },
  "wallet": {
    "allowance_cents": 0,
    "used_cents": 0,
    "reserved_cents": 0,
    "fee_deficit_cents": 0,
    "fee_deficit_settled_cents": 0,
    "carryover_cents": 0,
    "purchased_credit_cents": 0,
    "overage_cents": 0,
    "overage_cap_cents": 0,
    "email_rate_per_1k_cents": 0,
    "shared_plan": {
      "allowance_cents": 0,
      "cap_cents": 0,
      "paused": false
    }
  },
  "spend": {
    "total_cents": 1,
    "email_cents": 0,
    "sms_cents": 0,
    "sms_carrier_fees_cents": 0,
    "other_cents": 0,
    "refunds_cents": 0,
    "included_cents": 0,
    "purchased_credit_cents": 0,
    "overage_cents": 0,
    "credits_added_cents": 0
  },
  "sms": {
    "messages": 0,
    "segments": 0,
    "send_cents": 0,
    "received": 0,
    "received_cents": 0,
    "monthly_fees_cents": 0,
    "one_time_fees_cents": 0,
    "refunds_cents": 0,
    "countries": [
      {
        "country": "string",
        "messages": 0,
        "segments": 0,
        "price_per_segment_cents": 0,
        "price_per_segment_cents_decimal": "string",
        "cost_cents": 0
      }
    ],
    "received_countries": [
      {
        "country": "string",
        "received": 0,
        "segments": 0,
        "cost_cents": 0
      }
    ]
  },
  "limits": {
    "log_retention_days": 0,
    "domains": 0,
    "team_members": 0,
    "api_keys": 0,
    "webhook_endpoints": 0,
    "image_storage_mb": 0,
    "contacts": 0,
    "advance_scheduling_days": 0,
    "automation_runs_included": 0,
    "ai_credits": 0,
    "sms_toll_free_numbers": 0,
    "sms_local_numbers_per_country": 1
  },
  "features": {
    "sms": false,
    "sms_carrier_resources": false,
    "inbound_email": false,
    "topics": false,
    "granular_permissions": false,
    "remove_branding": false
  }
}

Retrieve your workspace's current billing-period usage snapshot: the plan, the period window, and the email counter. On paid plans the response also carries the dollar sending wallet: the monthly allowance included with the plan, spend so far, any upgrade carryover, the non-expiring purchased-credit balance, and billable overage, all as integer USD cents. On the free plan wallet is null and the emails object carries the monthly quota and daily cap instead. spend itemizes the period from the wallet ledger (email, SMS, SMS carrier fees, refunds, and how it was paid), and sms breaks SMS down by destination country with segments, the price per segment, texts received by the receiving number's country, monthly number and campaign fees, one-time registration fees, and refunds. Amounts are read from the same ledger and meters that gate sending, so this matches the dashboard statement exactly. Requires the emails:read or sms:read capability.

Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
planrequiredstring—
period_startrequiredstring—
period_endrequiredstring—
emailsrequiredobject—
walletrequiredobject | null—
spendrequiredobject—
smsrequiredobject—
limitsobject—
featuresobject—
200401403

Retrieve spend caps

GET/api/v1/spend-caps

GET /spend-caps
curl -X GET 'https://www.unitpost.com/api/v1/spend-caps' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "spend_caps",
  "sms_purchases": {
    "cap_cents": 0,
    "max_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  },
  "shared_plan": {
    "cap_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  }
}

The workspace's monthly spend caps and what each has counted this period. sms_purchases caps the SMS carrier purchases API keys and apps confirm (POST /sms/quotes/{id}/confirm): the fee due now plus the first month of a monthly fee, per UTC calendar month; dashboard purchases never count. cap_cents is the cap as set (null: none, so every API purchase is refused with 403 api_spend_cap_not_set); the cap that applies is the lower of it and max_cents ($1,000 a month by default). A workspace that starts a paid plan on its own card starts with a $75 cap when it has none, unless a key or app of it already holds sms:purchase (a workspace its organization pays for follows the organization Owner's rules instead; a key still needs sms:purchase to buy). shared_plan is the workspace's cap on its organization's shared plan and what it drew from it this period (null when it isn't on one); its organization sets it. Requires the sms:read or sms:purchase or spend_caps:write capability.

Response · 200 fields3 fields
FieldTypeDescription
objectrequiredstring—
sms_purchasesrequiredobjectSMS purchases by API (`POST /sms/quotes/{id}/confirm`). Purchases made in the dashboard never count.
shared_planobject | nullThe workspace's cap on its organization's shared plan, read-only: its organization sets it (`PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Null when the workspace isn't on a shared plan.
200401403404422

Update spend caps

PATCH/api/v1/spend-caps

PATCH /spend-caps
curl -X PATCH 'https://www.unitpost.com/api/v1/spend-caps' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "spend_caps",
  "sms_purchases": {
    "cap_cents": 0,
    "max_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  },
  "shared_plan": {
    "cap_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  }
}

Set, raise, lower or clear a monthly spend cap; only the caps you send change. sms_purchases.cap_cents is whole cents from 0 (API purchases off) to the platform maximum ($1,000 a month by default), or null to clear it, after which every API purchase is refused (403 api_spend_cap_not_set) until a cap is set again. A purchase over the cap is refused with 403 api_spend_cap_exceeded and nothing is charged; the dashboard buys past it. The capability is in no key preset, and only the workspace owner holds it and can give it to a key or an app; no other capability changes a cap. A workspace its organization pays for refuses it (403 billed_by_organization): its organization sets that cap with sms_purchases_cap_cents on PATCH /organizations/{id}/workspaces/{workspace_id}. shared_plan is read-only: a body naming it is 403 billed_by_organization and changes nothing (the organization sets that cap with PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}). Requires the spend_caps:write capability.

Request body1 field
FieldTypeDescription
sms_purchasesobject—
Response · 200 fields3 fields
FieldTypeDescription
objectrequiredstring—
sms_purchasesrequiredobjectSMS purchases by API (`POST /sms/quotes/{id}/confirm`). Purchases made in the dashboard never count.
shared_planobject | nullThe workspace's cap on its organization's shared plan, read-only: its organization sets it (`PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Null when the workspace isn't on a shared plan.
200400401403404422

Search docs and guides

Search the docs and product guides.