Email

A domain, then the first send. Every call is on this page.

Start

Verify a domain, then send the first email.

Open this guide on its own page

Email starts with a domain you own. Add it under Domains, publish the DNS records, and wait until it verifies. Live sends use a from address on that domain.

A template is optional. You can send HTML or text in the request, or save the message on Templates and pass its id. The Quickstart is the full first-send walkthrough, including the API key.

  • Domains — DNS and verification.
  • Templates — reusable HTML and variables.
  • Emails API — send, retrieve, and list.
  • Rate limits — one message, a batch or a campaign: how to send to many people.

Quickstart

Create a key, verify a domain, and send your first email.

Open this guide on its own page

You can send your first email in minutes: create an API key, verify a domain, and make a POST request.

1. Create an API key

Go to API Keys. Choose a scope (Full access, Sending, or on paid plans Read only or your own capability list) and copy the key when shown. What each scope covers: API keys.

Scope keys tightly

A server that only sends mail should use a Sending key. Keys can never manage other keys, team, or billing.

2. Verify a sending domain

Add your domain under Domains and publish the generated DNS records. Verification runs automatically.

No domain yet?

While DNS propagates you can still send test emails to your own address from the dashboard onboarding flow — no verified domain required. Test sends confirm the pipeline works; live API sends need a verified domain.

3. Send

Send an email in one call — a from address on your verified domain, a recipient, a subject, and either inline HTML or a template ID. The from accepts a bare address or a display name ("Acme <you@yourdomain.com>").

cURL
curl https://www.unitpost.com/api/v1/email \
  -H "Authorization: Bearer $UNITPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{
    "from": "Acme <you@yourdomain.com>",
    "to": "customer@acme.com",
    "subject": "Welcome aboard",
    "html": "<p>Thanks for signing up!</p>"
  }'

The response includes the new email's id. Use GET /api/v1/email/{id} (or unitpost.email.get(id)) to read its current status and lifecycle events, or watch it live on the Emails page in the dashboard.

Templates & variables

Reference a saved template and pass per-recipient data.

Open this guide on its own page

Rather than inlining HTML on every send, save a template once and reference it by ID. Pass template.variables and any {{variable}} in the template is substituted at send time.

cURL
curl https://www.unitpost.com/api/v1/email \
  -H "Authorization: Bearer $UNITPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "customer@acme.com",
    "template": {
      "id": "tmpl_123",
       "variables": { "plan": "Pro" }
    }
  }'

When you send to a known contact, that contact's custom fields merge into the variables automatically — so a template can reference {{first_name}} without you re-sending it on every request. Variables also work in the subject and in the From name: "{{company_name}} Team <hi@yourdomain.com>". A variable with no value fails the send instead of going out as written.

A custom field can carry a default (set it under Contacts → Custom fields, or as default_value on the contact-fields API). A field's default is the value used for any contact that has none: when an email is sent, so {{plan}} renders it, and when segments are evaluated. It's never written onto contacts, so changing it takes effect everywhere at once.

Drafts can't be sent

A template must be published before the API will send it. Referencing a draft returns a 422 with code template_not_published. Publish it in the editor first.

Marketing templates go to a contact

A template in the marketing category sends to one recipient (no cc or bcc), because its unsubscribe link and List-Unsubscribe header belong to that person. If the address isn't a contact yet, the send adds it to Contacts first, so the recipient can opt out and you can find and segment them later. On the Free plan the new contact counts toward your contact limit; at the limit the send is refused with a limit error instead. An address that already unsubscribed or reported spam is added as unsubscribed, and the email is suppressed. Transactional templates never create contacts.

Author templates in the editor under Templates, or through the API in one of three editors. A Design template (the default for anything branded) is our components as TSX in tsx; wrap them in one <Email> element to set the page (backdrop, card, width, radius, border, fonts, colors, preview text) in the same call, and it stays editable in the Design tab. A Simple template is a plain, personal email in text. A Code template is your own HTML in html, kept as-is. Every read says which editor a template is in; PATCH with editor alone converts it. Every block and layout is documented at /components.

Sending domains

Add SPF, DKIM, and DMARC so mail sends from your domain.

Open this guide on its own page

To send from your own domain you publish a few DNS records so mailbox providers trust the mail is really from you. Add the domain under Domains and copy the generated records to your DNS provider.

  • DKIM — a TXT record that lets us cryptographically sign your mail.
  • MAIL FROM — a custom return-path subdomain for SPF alignment.
  • DMARC — a policy record that tells receivers what to do with unaligned mail.

Verification is continuous, not one-shot. A domain is Verified, Degraded, or Unverified, and we keep re-checking the records over time.

Degraded still sends

You can send from a Verified or Degraded domain. Degraded means some records drifted but mail still flows — fix the flagged records to return to Verified. You cannot send from an Unverified domain.

Opted-in mail only

Unitpost is for transactional mail and people who opted in. Cold outreach isn't allowed, B2B included. See the Acceptable Use Policy.

Open & click tracking

Control engagement tracking per send, template, or category.

Open this guide on its own page

With tracking on, we inject a 1×1 open pixel and rewrite links so opens and clicks land in the email's event timeline and feed the engagement rates on your dashboard.

How the default is resolved

Tracking is resolved per send in a clear order, most specific first:

  1. An explicit tracking flag on the request wins.
  2. Otherwise the referenced template's default applies.
  3. Otherwise the category default applies.

Sending a receipt or password reset?

Set tracking to false to deliver a clean, untracked transactional message. Many providers and recipients prefer no pixel on sensitive mail.

Bounces, complaints & suppression

How bad addresses are handled and where to review them.

Open this guide on its own page

When an address hard bounces or complains, we add it to your suppression list. It's enforced on every send (single, batch, and campaign), including CC and BCC recipients.

  • Hard bounce — the address is invalid or rejected permanently; it's suppressed (reason: bounced).
  • Complaint — the recipient marked the mail as spam; it's suppressed (reason: complained).
  • Soft bounce — a temporary failure (full mailbox, greylisting); delivery is retried and the address isn't suppressed. Three soft bounces in a row suppress it (reason: bounced), and so does one to a domain that doesn't exist or accepts no mail.

Suppressed recipients are excluded, not failed — surfaced as a "Recipients excluded" event on the timeline. Review the list on the Suppressions tab. You can remove an address there to make it mailable again — but re-sending to bad addresses hurts deliverability.

Suppression is separate from marketing unsubscribe

The suppression list is distinct from a contact's marketing preference. An address can be unsubscribed from marketing but mailable for transactional sends, or suppressed outright. Manage blocks on the Suppressions page; manage preferences on the contact.

Before a big send

Before a campaign goes out, the Send dialog (and warnings[] in the validate response of the campaigns API) may show a few warnings. They never block the send; they point at the habits that most often get mail throttled or filtered. A scheduled campaign also warns when your scheduled sends may outrun the credits left this period, since a campaign that runs short pauses until you top up. Before your first big send, read the deliverability guides.

New domains and sudden volume

Mailbox providers judge a sending domain by its history. A domain that verified recently, or has never sent, has none, and a large first send looks like a bulk or compromised sender. Start with your most engaged contacts, send a few hundred emails on day one, and grow the volume over about a week. The same goes for a send far larger than your usual days: split it into a few sends over several days. More in How to warm up a new sending domain.

DMARC

Gmail and Yahoo require a DMARC record for bulk senders. Without one, more of your mail lands in spam or is refused. Add the DMARC record shown on your domain page; a policy of p=none is enough to start. What Gmail, Yahoo and Microsoft require: bulk sender requirements.

Sending frequency

Mailing the same people several times in a few days drives unsubscribes and spam complaints, which hurt every later send. Space marketing campaigns out, and leave out recipients who just heard from you. More in How often to send marketing email.

The send time

A campaign's saved send time is armed when you press Send: until then the campaign stays a draft, and the campaign list and page show the time as saved, not scheduled. If that time has already passed, Send sends the campaign right away, and the Send dialog (and warnings[] in the validate response) says so first. To schedule it instead, set a new time (Edit, or scheduled_at on the API's Send). Times are stored and returned in UTC; the API takes ISO 8601 with Z or an offset such as -07:00.

Topics and unsubscribes

Without a subscription topic, anyone who unsubscribes from a campaign stops getting all of your marketing email. Scope recurring mail (a newsletter, product updates) to a topic so people can leave just that one and keep the rest, which keeps more of your list reachable.

Use your own unsubscribe on lifecycle email

Onboarding sequences, digests and alerts you render yourself and send as html/text are not marketing-category sends: we add no footer and no unsubscribe header to them. If you run your own unsubscribe page and list, put your headers on the send and Gmail shows its native Unsubscribe button (it is built from the List-Unsubscribe header, not from a link in the body — which is also what Google Postmaster Tools checks for one-click). It works on every plan, right away: no setting to turn on and nothing to request. The same headers work on a single send, each batch item, SMTP, and the MCP email.send tool.

  • List-Unsubscribe — one or more <…> entries separated by commas, each an https:// URL or a mailto: address. A mailto-only header is fine. Plain http://, other schemes and non-ASCII characters are refused with a 422: percent-encode non-ASCII characters in the URL and write an international domain in its punycode (xn--…) form. Keep the header to 870 characters or fewer.
  • List-Unsubscribe-Post — exactly List-Unsubscribe=One-Click, for one-click. It needs at least one https:// entry in List-Unsubscribe (the inbox POSTs to it); mailto alone can't take a one-click.
  • Set each header once. Header names are case-insensitive, so List-Unsubscribe and list-unsubscribe on the same send is refused.
  • Keep an unsubscribe link in the body too: inboxes that don't render the header still need one. Our content review reads the header the way it reads the body; it never holds or slows a send because of the header.
One-click (https + mailto)
curl https://www.unitpost.com/api/v1/email \
  -H "Authorization: Bearer $UNITPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{
    "from": "Jobs <jobs@mail.acme.com>",
    "to": "ada@example.com",
    "subject": "Your weekly digest",
    "html": "<p>New jobs for you. <a href=\"https://acme.com/u/abc\">Unsubscribe</a></p>",
    "headers": {
      "List-Unsubscribe": "<https://acme.com/u/abc>, <mailto:unsub@acme.com>",
      "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
    }
  }'
Over SMTP (Nodemailer)
await transporter.sendMail({
  from: "Jobs <jobs@mail.acme.com>",
  to: "ada@example.com",
  subject: "Your weekly digest",
  html: digestHtml,
  headers: {
    "List-Unsubscribe": "<https://acme.com/u/abc>, <mailto:unsub@acme.com>",
    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
  },
});

Over SMTP the two headers are read from the message itself. Mail libraries fold long header lines on their own; that's fine, we unfold them before checking.

Mailto only
curl https://www.unitpost.com/api/v1/email \
  -H "Authorization: Bearer $UNITPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{
    "from": "Jobs <jobs@mail.acme.com>",
    "to": "ada@example.com",
    "subject": "Your weekly digest",
    "text": "Jobs for you this week. Reply to this message to unsubscribe.",
    "headers": { "List-Unsubscribe": "<mailto:unsub@acme.com?subject=unsubscribe>" }
  }'

Marketing templates keep our unsubscribe

A send from a marketing-category template refuses these two headers (422): Unitpost adds its own per-recipient List-Unsubscribe and footer there, and records the opt-out on the contact. Your own headers are for mail whose unsubscribe you handle yourself — those opt-outs land on your endpoint and your list, not on the contact. Opt-outs recorded with us still don't block transactional sends.

When a campaign pauses itself

We watch every email campaign while it sends. If too many of its addresses don't exist, or too many recipients mark it as spam, we pause that campaign, not your account: your password resets, receipts and other campaigns keep sending. The campaign page shows what happened in plain numbers, and the campaign.paused webhook carries the same facts.

SignalJudged once there areWarning atPaused at
Addresses that don't exist (hard bounces), per message sent5 hard bounces—10%
Addresses that don't exist (hard bounces), per message sent10 hard bounces2%5%
Spam complaints, per message delivered3 complaints0.05%0.1%

Small numbers get a margin: we act only when we're 95% sure the real rate is at or above the line. So 3 bounces out of 10 sends doesn't pause yet, but 5 out of 20 does, and so do 98 out of 1,400. Temporary failures (a full mailbox, greylisting) never count. While the platform's overall bounce rate is high, the 5% line tightens to 3%. Our delivery reviewer, Unit, can also pause a campaign earlier when the pattern is clearly bad (for example, most of the first sends bouncing). It can only add caution; it never keeps a campaign sending past these lines. We may also tighten these lines for a while, for example during an incident; the campaign page and the webhook always show the line that applied.

  • The first time, you can resume it yourself: download or remove the affected addresses (they're already suppressed), confirm the list was opted in and cleaned, and resume. Only sends made after you resume count toward the lines, so old bounces won't pause it again.
  • A repeat needs a quick review by our team: this campaign was paused automatically before (at any time), or another of your campaigns was in the last 90 days. Resume answers 409 review_required and the page offers Request review. A third goes to an account review.
  • Cancel the rest stops the campaign for good; nothing more is sent.

In the API, a paused campaign carries pause_reason: a code (hard_bounce_rate, complaint_rate, quality_review, or a non-quality reason such as user, billing or failure_streak), the plain message, and for an automatic quality pause the metric, value, threshold, sample, window, decided_by and resume (self_serve, review_required or account_review).

When sending is paused for your workspace

Besides a single campaign, sending can pause for a whole stream of your workspace: marketing (campaigns) or transactional (everything you send through the API, SMTP or the dashboard one by one). The two are separate, so a pause of your campaigns never stops your password resets or receipts. A stream pauses when its recent mail drew too many spam complaints or bounces, or while our team reviews it.

While a stream is paused, a send to it is refused with sending_paused (403 for an email, 409 for a campaign send or resume), and campaigns already sending stop with that pause_reason. The error carries doc_url, a link to this section. Settings → Deliverability shows which stream is paused, why, and how to resume it.

  • The first marketing pause in 90 days you can resume yourself from Settings → Deliverability, after the steps it lists. For the first days after that, campaigns send up to a daily limit based on your own recent sending (the page shows the limit and when it ends); a campaign over the limit carries on the next day.
  • A pause for bounces (by default, when 10% or more of your latest 200 emails, and at least 10 of them, bounced because the address doesn't exist) stops only the stream those emails came from. We email the owner and admins. The first one in 90 days, on either stream, you can resume yourself once you've removed the addresses that bounced and any old, bought or scraped ones. Your dashboard, API keys, contacts and SMS keep working.
  • A repeat, any other transactional pause, or a pause under review goes to our team. We email the account owner with next steps.

Get these as webhooks

Every lifecycle event is available in-app today, and you can also have us POST them to your own endpoint in real time. See the Webhooks guide to register an endpoint and verify the signed payloads.

Emails

Send, schedule, retrieve, and cancel transactional email. Send one email or a batch of up to 100, track each message's delivery lifecycle, and pull aggregate deliverability stats for your workspace.

List sent emails

GET/api/v1/email

GET /email
curl -X GET 'https://www.unitpost.com/api/v1/email' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "email",
      "id": "id_123",
      "to": [
        "customer@example.com"
      ],
      "from": "you@yourdomain.com",
      "subject": "Welcome to Acme",
      "template_id": "template_123",
      "campaign_id": "campaign_123",
      "status": "scheduled",
      "last_event": "string",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "sent_at": "2026-01-01T00:00:00.000Z",
      "delivered_at": "2026-01-01T00:00:00.000Z",
      "opened_at": "2026-01-01T00:00:00.000Z",
      "clicked_at": "2026-01-01T00:00:00.000Z",
      "canceled_at": "2026-01-01T00:00:00.000Z",
      "last_error": "string",
      "created_at": "2026-01-01T00:00:00.000Z",
      "cc": [
        "string"
      ],
      "bcc": [
        "string"
      ],
      "reply_to": [
        "string"
      ],
      "tags": [
        {
          "name": "Example",
          "value": "string"
        }
      ]
    }
  ]
}

Retrieve a list of emails your workspace has sent or scheduled. Results are newest-first and cursor-paginated, and each row is a reference to a single email (status and lifecycle timestamps, not the rendered body). Narrow the list with the status, to, contact_id, campaign_id, batch_id, q, source, outcome and created_after/created_before filters. A q, source or outcome 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 an email's id with Retrieve an email to read its full record, or Cancel or reschedule an email to change a scheduled send. For aggregate deliverability numbers over a window, see Email deliverability stats. With campaign_id it is that campaign's report, so campaigns:read reads it too. Requires the emails:read capability.

Parameters13 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 · queryFilter by send status.
tostring · queryOnly emails to this recipient address.
contact_idstring · queryOnly emails to this contact (`con_…`): sends linked to it or addressed to its current email address.
campaign_idstring · queryOnly emails produced by this campaign's fan-out.
batch_idstring · queryOnly emails sent as part of this batch.
created_afterstring · queryOnly emails created at/after this ISO 8601 time.
created_beforestring · queryOnly emails created at/before this ISO 8601 time.
qstring · querySearch: an exact recipient address, or part of the subject or the sender (case-insensitive), as the dashboard's Sent table searches. At most 200 characters.
sourcestring · queryHow the email was sent: `api`, `smtp`, `test` (a test send), `batch`, `campaign`, or `reply` (from the inbox).
outcomestring · queryWhat happened, as a campaign's Emails tab filters: `delivered`, `opened`, `clicked`, `unsubscribed` (engagement overlaps delivery), `bounced`, `complained`, `failed` (failed, suppressed or canceled), `pending`. With `campaign_id`: who opened or clicked a campaign.
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring[]—
fromrequiredstring—
subjectrequiredstring—
template_idrequiredstring | null—
campaign_idrequiredstring | null—
statusrequiredenumscheduled | queued | sent | delivered | bounced | complained | canceled | failed—
last_eventrequiredstring—
scheduled_atrequiredstring | null—
sent_atrequiredstring | null—
delivered_atrequiredstring | null—
opened_atrequiredstring | null—
clicked_atrequiredstring | null—
canceled_atrequiredstring | null—
last_errorrequiredstring | null—
created_atrequiredstring—
ccstring[]Cc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
bccstring[]Bcc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
reply_tostring[]Reply-To addresses, as sent. Empty when none. Only on `GET /email/{id}`.
tagsobject[]The send's tags. Empty when none. Only on `GET /email/{id}`.
200401403422503

Send or schedule an email

POST/api/v1/email

POST /email
curl -X POST 'https://www.unitpost.com/api/v1/email' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "you@yourdomain.com",
    "to": "customer@example.com",
    "subject": "Welcome to Acme",
    "html": "<h1>Hello</h1>"
  }'
Response · 200
{
  "id": "id_123",
  "status": "queued",
  "scheduled_at": "2026-01-01T00:00:00.000Z"
}

Send a single transactional email — now, or at a future time by passing scheduled_at (ISO 8601 with Z or an offset, normalized to UTC; up to 90 days ahead, fewer on some plans). A scheduled_at in the past or under 30 seconds ahead sends immediately: check that the response status is scheduled. Provide the content inline as html/text, or reference a saved template with template (create one with Create a template). Pass an Idempotency-Key header to make retries safe: the same key replays the original result instead of sending twice. The response returns the new email's id — read its delivery status back with Retrieve an email, change a scheduled send with Cancel or reschedule an email, or send many at once with Send a batch of emails. Each call is one request against your workspace's rate limit (10 requests a second by default): a 429 sent nothing, so send that request again after Retry-After. A request body may be up to 30 MB. A larger one that declares its length is answered 413 before it is read; one sent without a length (chunked) is cut off at the limit with no answer. Either way nothing in it was sent or stored. A batch carries up to 100 emails as one request, and the same content to a list is a campaign (Create a campaign), which Unitpost paces for you. A template in the marketing category sends to one recipient (no cc/bcc) and adds them to your contacts if they aren't one yet, because the unsubscribe link belongs to a contact: the new contact counts toward a Free plan's contact limit (at the limit the send is refused) and fires contact.created with source: "send". A to/cc/bcc address on a domain reserved for examples (example.com, example.net, example.org) can't receive mail: it is left out, the others get the email, and Unitpost-Warning names it. Requires the emails:send 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 body16 fields
FieldTypeDescription
fromrequiredstringSender address on one of your verified domains. Accepts a bare address ("hi@acme.com") or a display name ("Acme <hi@acme.com>") — the name is what inbox clients show next to the message.
torequiredstring | string[]—
subjectstring—
ccstring | string[]—
bccstring | string[]—
reply_tostring | string[]—
in_reply_tostringId of a received email (`inb_…`) this send replies to: Unitpost sets In-Reply-To / References and prefixes `Re:`. Not a Message-ID — a raw header goes in `headers`.
headersobjectCustom headers (your own `X-*` and threading headers). Envelope (`From`/`To`/`Cc`/`Bcc`/`Reply-To`/`Subject`/`Date`/`Message-ID`) and signing/transport headers are managed for you and rejected with 422. On a non-marketing send you may set your own `List-Unsubscribe` (one or more `<…>` entries, each `https://` or `mailto:`) and `List-Unsubscribe-Post` (exactly `List-Unsubscribe=One-Click`, which needs at least one `https://` entry). A marketing-template send refuses both: Unitpost adds its own per recipient.
tagsobject[]—
templateobjectPublished template plus variable values. Mutually exclusive with `html` and `text`.
htmlstringHTML MIME body. It is sanitized for email safety and may be supplied with `text` to create a multipart alternative. This field does not parse Markdown.
textstringPlain-text MIME body. Newline characters are preserved; Markdown and rich-text styling are not interpreted. It may be supplied with `html` as the fallback alternative. When `html` is sent without `text`, a plain-text alternative is derived from the visible HTML content; an explicit `text` value is always sent unchanged.
attachmentsobject[]—
open_trackingboolean—
click_trackingboolean—
scheduled_atstringFuture send time: ISO 8601 with `Z` or a `±hh:mm` offset, normalized to UTC (reads return UTC). Up to 90 days ahead, fewer on some plans. A time in the past or under 30 seconds ahead sends immediately, so check the response `status`.
Response · 200 fields3 fields
FieldTypeDescription
idrequiredstring—
statusrequiredenumqueued | scheduled—
scheduled_atrequiredstring—
200400401403404409413422429503

Send a batch of emails

POST/api/v1/email/batch

POST /email/batch
curl -X POST 'https://www.unitpost.com/api/v1/email/batch' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": [
      {
        "from": "you@yourdomain.com",
        "to": "a@example.com",
        "subject": "Hi A",
        "html": "<p>Hi A</p>"
      },
      {
        "from": "you@yourdomain.com",
        "to": "b@example.com",
        "subject": "Hi B",
        "html": "<p>Hi B</p>"
      }
    ]
  }'
Response · 200
{
  "object": "list",
  "batch_id": "batch_123",
  "status": "queued",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "data": [
    {
      "id": "id_123"
    }
  ],
  "failed": [
    {
      "index": 0,
      "error": "string"
    }
  ]
}

Send up to 100 transactional emails in a single request. Validation is all-or-nothing: if any item is invalid the whole batch is rejected and nothing is queued, so you never end up with a partial send. Addresses on a reserved domain (example.com, example.net, example.org) can't receive mail: an item's are left out and the rest of it is sent (named in Unitpost-Warning), and an item with no to left is refused on its own and returned in failed with its index while the rest of the batch is sent. With Unitpost-Strict: true an item with any reserved recipient is refused the same way, on its own and in failed: strict mode doesn't refuse the whole batch for it. To schedule, use the object form { emails, scheduled_at } for the whole batch: an item that carries its own send time (scheduled_at, send_at, …) is rejected (422) and nothing is sent. An item with attachments is rejected (422). Pass an Idempotency-Key header to make retries safe — the same key replays the original result instead of re-sending. The response returns a batch_id; track the batch's per-status rollup with Retrieve a batch and stop the rest of it with Cancel a batch. The whole batch counts as one request against your workspace's rate limit (10 requests a second by default), so a list you keep in your own system goes out as one request per 100 recipients: give each batch its own Idempotency-Key and read failed[] in each answer. A batch sent with an Idempotency-Key stops starting messages 5 minutes after its request began and lists the ones it did not reach in failed: those were not sent. The same key replays that answer, so they are sent only by a new request with a new key. A batch is one request, so its messages together fit in 30 MB: a larger one is a 413 that sent nothing, to be sent as several batches. To send one email, use Send or schedule an email; to send the same content to a list, use Create a campaign, which takes up to 5,000 addresses inline. Requires the emails:send 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`.
Response · 200 fields1 field
FieldTypeDescription
idrequiredstring—
200400401403409413422429503

List batches

GET/api/v1/email/batches

GET /email/batches
curl -X GET 'https://www.unitpost.com/api/v1/email/batches' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "batch",
      "id": "id_123",
      "count": 1,
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "status_counts": {},
      "cancelable": 0
    }
  ]
}

Your batch sends, newest first and cursor-paginated, as the dashboard's Batches tab lists them. Each is the same live rollup Retrieve a batch returns: how many emails it holds, when it's scheduled, a count per delivery status and how many are still cancelable. Requires the emails: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 fields7 fields
FieldTypeDescription
objectrequiredenumbatch—
idrequiredstring—
countrequiredinteger—
scheduled_atrequiredstring—
created_atrequiredstring—
status_countsrequiredobjectLive child counts keyed by status (e.g. { delivered: 98, failed: 2 }).
cancelablerequiredinteger—
200401403422

Retrieve a batch

GET/api/v1/email/batches/{id}

GET /email/batches/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/batches/batch_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "batch",
  "id": "id_123",
  "count": 1,
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "status_counts": {},
  "cancelable": 0
}

Retrieve a batch and its live, per-status rollup (how many of its messages are queued, sent, delivered, bounced, and so on). The counts update as the batch progresses. Create a batch with Send a batch of emails, or stop its remaining messages with Cancel a batch. Requires the emails:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredenumbatch—
idrequiredstring—
countrequiredinteger—
scheduled_atrequiredstring—
created_atrequiredstring—
status_countsrequiredobjectLive child counts keyed by status (e.g. { delivered: 98, failed: 2 }).
cancelablerequiredinteger—
200401403404

Cancel a batch

POST/api/v1/email/batches/{id}/cancel

POST /email/batches/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/email/batches/batch_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "batch",
  "id": "id_123",
  "count": 1,
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "status_counts": {},
  "cancelable": 0
}

Cancel every still-cancelable message in a batch in one call. Messages that have already been sent are left untouched — only queued or scheduled ones are stopped. Check what remains cancelable first with Retrieve a batch. Requires the emails:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredenumbatch—
idrequiredstring—
countrequiredinteger—
scheduled_atrequiredstring—
created_atrequiredstring—
status_countsrequiredobjectLive child counts keyed by status (e.g. { delivered: 98, failed: 2 }).
cancelablerequiredinteger—
200401403404409

List an email's events

GET/api/v1/email/{id}/events

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

One sent email's delivery events, oldest first: sent, delivered, delayed, bounced, complained, opened, clicked, failed, suppressed, unsubscribed. Each carries its detail under the webhook's names (a bounce's diagnostic_code, a click's link), with the provider's wording redacted as in webhooks. Opens and clicks are recorded once per email per day (clicks once per link per day). Cursor-paginated with emev_ ids. Requires the emails: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 fields5 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
typerequiredstringThe event, as webhooks name it (`email.delivered`, `email.bounced`, ...).
created_atrequiredstringWhen it happened.
datarequiredobjectThe event's own detail, under the webhook's field names: `bounce` { type, sub_type, category, diagnostic_code[] } (`category`: hard_bounce, soft_bounce, provider_policy_reject or already_suppressed; only hard_bounce means the address can't receive mail), `complaint` { feedback_type }, `open` { user_agent }, `click` { link, user_agent }, `failed` { reason }, `suppressed` { recipients[], reasons[] { email, reason }, full }, `unsubscribe` { scope, source }. Empty for the rest.
200401403404422

Retrieve an email

GET/api/v1/email/{id}

GET /email/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/email_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "email",
  "id": "id_123",
  "to": [
    "customer@example.com"
  ],
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "template_id": "template_123",
  "campaign_id": "campaign_123",
  "status": "scheduled",
  "last_event": "string",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "delivered_at": "2026-01-01T00:00:00.000Z",
  "opened_at": "2026-01-01T00:00:00.000Z",
  "clicked_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "cc": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "reply_to": [
    "string"
  ],
  "tags": [
    {
      "name": "Example",
      "value": "string"
    }
  ]
}

Retrieve a single email by id, including its current send status and lifecycle timestamps (created, scheduled, sent, delivered, and so on). Find an id by browsing List sent emails. Messages submitted over **SMTP** can also be retrieved by the RFC 5322 Message-ID your mail library stamped on them (URL-encode it, e.g. /email/%3Cabc%40example.com%3E; angle brackets optional) — the id in the SMTP 250 Queued as … reply works too. It also carries the cc, bcc, reply_to and tags the email was sent with (never its body); its delivery events are List an email's events. To change a scheduled or queued email, use Cancel or reschedule an email. Requires the emails:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring[]—
fromrequiredstring—
subjectrequiredstring—
template_idrequiredstring | null—
campaign_idrequiredstring | null—
statusrequiredenumscheduled | queued | sent | delivered | bounced | complained | canceled | failed—
last_eventrequiredstring—
scheduled_atrequiredstring | null—
sent_atrequiredstring | null—
delivered_atrequiredstring | null—
opened_atrequiredstring | null—
clicked_atrequiredstring | null—
canceled_atrequiredstring | null—
last_errorrequiredstring | null—
created_atrequiredstring—
ccstring[]Cc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
bccstring[]Bcc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
reply_tostring[]Reply-To addresses, as sent. Empty when none. Only on `GET /email/{id}`.
tagsobject[]The send's tags. Empty when none. Only on `GET /email/{id}`.
200401403404

Cancel or reschedule an email

PATCH/api/v1/email/{id}

PATCH /email/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/email_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "scheduled_at": null
  }'
Response · 200
{
  "object": "email",
  "id": "id_123",
  "to": [
    "customer@example.com"
  ],
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "template_id": "template_123",
  "campaign_id": "campaign_123",
  "status": "scheduled",
  "last_event": "string",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "delivered_at": "2026-01-01T00:00:00.000Z",
  "opened_at": "2026-01-01T00:00:00.000Z",
  "clicked_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "cc": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "reply_to": [
    "string"
  ],
  "tags": [
    {
      "name": "Example",
      "value": "string"
    }
  ]
}

Cancel a scheduled or queued email, or move it to a new send time. Only emails that haven't been handed off for delivery yet can be changed — once an email is sent this returns 409. Look up the email's current state first with Retrieve an email. Requires the emails:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body2 fields
FieldTypeDescription
cancelboolean—
scheduled_atstring—
Response · 200 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring[]—
fromrequiredstring—
subjectrequiredstring—
template_idrequiredstring | null—
campaign_idrequiredstring | null—
statusrequiredenumscheduled | queued | sent | delivered | bounced | complained | canceled | failed—
last_eventrequiredstring—
scheduled_atrequiredstring | null—
sent_atrequiredstring | null—
delivered_atrequiredstring | null—
opened_atrequiredstring | null—
clicked_atrequiredstring | null—
canceled_atrequiredstring | null—
last_errorrequiredstring | null—
created_atrequiredstring—
ccstring[]Cc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
bccstring[]Bcc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
reply_tostring[]Reply-To addresses, as sent. Empty when none. Only on `GET /email/{id}`.
tagsobject[]The send's tags. Empty when none. Only on `GET /email/{id}`.
200401403404409422

Retry a failed email

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

POST /email/{id}/retry
curl -X POST 'https://www.unitpost.com/api/v1/email/email_123/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "email",
  "id": "id_123",
  "to": [
    "customer@example.com"
  ],
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "template_id": "template_123",
  "campaign_id": "campaign_123",
  "status": "scheduled",
  "last_event": "string",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "sent_at": "2026-01-01T00:00:00.000Z",
  "delivered_at": "2026-01-01T00:00:00.000Z",
  "opened_at": "2026-01-01T00:00:00.000Z",
  "clicked_at": "2026-01-01T00:00:00.000Z",
  "canceled_at": "2026-01-01T00:00:00.000Z",
  "last_error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "cc": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "reply_to": [
    "string"
  ],
  "tags": [
    {
      "name": "Example",
      "value": "string"
    }
  ]
}

Send a failed email again on the same id, as the dashboard's Retry does. Only a one-off send whose failure was temporary is retried: a campaign recipient, a template test, a suppressed or rejected send, a content error, or a send whose stored content is gone is a 409 saying why (send a new email instead). The HTML and text you sent are kept for up to 365 days; a template send re-renders, so it keeps no copy and can still be retried. It passes the same checks as a new send: the sending domain, your plan and quota. Pass an Idempotency-Key so a retried call can't send it twice. Takes no body; follow the email with Retrieve an email. Requires the emails:send capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
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 fields21 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
torequiredstring[]—
fromrequiredstring—
subjectrequiredstring—
template_idrequiredstring | null—
campaign_idrequiredstring | null—
statusrequiredenumscheduled | queued | sent | delivered | bounced | complained | canceled | failed—
last_eventrequiredstring—
scheduled_atrequiredstring | null—
sent_atrequiredstring | null—
delivered_atrequiredstring | null—
opened_atrequiredstring | null—
clicked_atrequiredstring | null—
canceled_atrequiredstring | null—
last_errorrequiredstring | null—
created_atrequiredstring—
ccstring[]Cc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
bccstring[]Bcc recipients, as sent. Empty when none. Only on `GET /email/{id}`.
reply_tostring[]Reply-To addresses, as sent. Empty when none. Only on `GET /email/{id}`.
tagsobject[]The send's tags. Empty when none. Only on `GET /email/{id}`.
200400401403404409422429

Email deliverability stats

GET/api/v1/email/stats

GET /email/stats
curl -X GET 'https://www.unitpost.com/api/v1/email/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "windowDays": 0,
  "clampedToRetentionDays": 0,
  "totals": {
    "sent": 0,
    "delivered": 0,
    "opened": 0,
    "clicked": 0,
    "bounced": 0,
    "complained": 0,
    "failed": 0,
    "bounced_permanent": 0,
    "bounced_transient": 0,
    "suppressed": 0,
    "unsubscribed": 0
  },
  "rates": {
    "delivery": 0,
    "open": 0,
    "click": 0,
    "bounce": 0,
    "complaint": 0,
    "unsubscribe": 0
  },
  "domain_id": "domain_123",
  "from": "you@yourdomain.com",
  "to": "customer@example.com",
  "series": {
    "grain": "5m",
    "time_zone": "string",
    "buckets": [
      {
        "bucket": "string",
        "sends": 0
      }
    ]
  }
}

Retrieve aggregate deliverability and engagement metrics for your workspace over a rolling window. You get totals (sent, delivered, opened, clicked, bounced, complained, failed) alongside the rates that matter — delivery, open, click, bounce, and complaint. Open and click rates count only emails where that tracking was enabled, so turning tracking off for transactional mail won't skew them. Bounces are split into permanent and transient, with the sends that skipped a suppressed recipient and the unsubscribes your emails led to. Control the window with days (1–365, default 30), or count a period with from and to; add grain (and tz) for the send volume per bucket, as the dashboard home charts it. domain_id counts one sending domain. 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. For the individual emails behind these numbers, see List sent emails. Requires the emails:read capability.

Parameters6 fields
FieldTypeDescription
daysinteger · queryWindow size in days (1–365). Defaults to 30; values above 365 are rejected.
fromstring · queryStart of a period, with `to` (instead of `days`). ISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). Not in the future.
tostring · queryEnd of the period, exclusive. At most 366 days after `from`; with `grain`, at most 6 hours (`5m`), 3 days (`1h`) or 93 days (`1d`) (a longer period keeps its totals, without `series`). With `days`, `from` and `to` are ignored.
grainstring · queryWith `from` and `to`: return `series`, the send volume per bucket of five minutes, an hour or a day.
tzstring · queryWith `grain`: the IANA time zone the buckets are keyed in (default `UTC`).
domain_idstring · queryCount only emails sent from this domain (`dom_…`).
Response · 200 fields8 fields
FieldTypeDescription
windowDaysrequiredintegerThe window, in days (a period's length, rounded up).
clampedToRetentionDaysintegerNon-null when the window reached past the plan's log retention: counting starts this many days back (data past the retention horizon is purged).
totalsrequiredobject—
ratesrequiredobjectPercentages (one decimal). delivery/bounce/complaint are vs sent; open/click are vs delivered with that tracking on; unsubscribe vs delivered.
domain_idstring | nullThe sending domain counted (`domain_id`), or null for every domain.
fromstringStart of the window counted (UTC).
tostringEnd of the window counted, exclusive (UTC).
seriesobject | nullThe send volume per `grain` bucket over `from`–`to`, as the dashboard home charts it; null without `grain`.
200401403404422

Inbound emails

Read email your receiving-enabled domains have received — list messages, retrieve full bodies, and download attachments via short-lived signed URLs.

List received emails

GET/api/v1/email/received

GET /email/received
curl -X GET 'https://www.unitpost.com/api/v1/email/received' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "received_email",
      "id": "id_123",
      "from": "you@yourdomain.com",
      "from_name": "string",
      "to": [
        "customer@example.com"
      ],
      "cc": [
        "string"
      ],
      "bcc": [
        "string"
      ],
      "message_id": "message_123",
      "subject": "Welcome to Acme",
      "spam_verdict": "string",
      "virus_verdict": "string",
      "spf_verdict": "string",
      "dkim_verdict": "string",
      "dmarc_verdict": "string",
      "size": 1,
      "received_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "thread_id": "thread_123",
      "reply_to": [
        "string"
      ],
      "attachment_count": 1
    }
  ]
}

Retrieve a list of inbound emails received on your receiving-enabled domains, newest-first and cursor-paginated. Rows are summaries (sender, subject, timestamps) without bodies — use a message's id with Retrieve a received email to read the full content and attachment metadata. Narrow the list with to (one address in the To or Cc header), thread_id (one conversation) and a created_after / created_before range. Requires the emails:read capability.

Parameters7 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).
tostring · queryOnly mail with this address in its To or Cc header, in any case. Envelope recipients aren't stored, so a Bcc copy or a forward to one of your addresses is matched by its headers only.
thread_idstring · queryOnly the messages of this conversation (`thr_…`), as `thread_id` on a received email and on the `email.received` webhook.
created_afterstring · queryOnly mail whose `created_at` is at/after this ISO 8601 time (with `Z` or an offset).
created_beforestring · queryOnly mail whose `created_at` is at/before this ISO 8601 time (with `Z` or an offset).
Response · 200 fields20 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
fromrequiredstring—
from_namerequiredstring | null—
torequiredstring[]—
ccrequiredstring[]—
bccrequiredstring[]—
message_idrequiredstring | null—
subjectrequiredstring | null—
spam_verdictrequiredstring | null—
virus_verdictrequiredstring | null—
spf_verdictrequiredstring | null—
dkim_verdictrequiredstring | null—
dmarc_verdictrequiredstring | null—
sizerequirednumber—
received_atrequiredstring—
created_atrequiredstring—
thread_idstring | nullThe conversation (`thr_…`); null until the message is threaded.
reply_tostring[]Reply-To addresses: answer these before `from` when present.
attachment_countrequirednumber—
200401403422

Retrieve a received email

GET/api/v1/email/received/{id}

GET /email/received/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/received/email_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "received_email",
  "id": "id_123",
  "from": "you@yourdomain.com",
  "from_name": "string",
  "to": [
    "customer@example.com"
  ],
  "cc": [
    "string"
  ],
  "bcc": [
    "string"
  ],
  "message_id": "message_123",
  "subject": "Welcome to Acme",
  "text": "string",
  "html": "string",
  "spam_verdict": "string",
  "virus_verdict": "string",
  "spf_verdict": "string",
  "dkim_verdict": "string",
  "dmarc_verdict": "string",
  "size": 1,
  "attachments": [
    {
      "object": "received_attachment",
      "id": "id_123",
      "filename": "string",
      "content_type": "string",
      "content_disposition": "string",
      "content_id": "content_123",
      "size": 1
    }
  ],
  "received_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "thread_id": "thread_123",
  "reply_to": [
    "string"
  ],
  "headers": {},
  "sent_by_us": false
}

Retrieve a full inbound message by id, including its HTML and text bodies plus metadata for every attachment. Attachment bytes aren't inlined — download each one via Get an attachment download URL. Browse your inbound mail with List received emails. Requires the emails:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields24 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
fromrequiredstring—
from_namerequiredstring | null—
torequiredstring[]—
ccrequiredstring[]—
bccrequiredstring[]—
message_idrequiredstring | null—
subjectrequiredstring | null—
textrequiredstring | null—
htmlrequiredstring | null—
spam_verdictrequiredstring | null—
virus_verdictrequiredstring | null—
spf_verdictrequiredstring | null—
dkim_verdictrequiredstring | null—
dmarc_verdictrequiredstring | null—
sizerequirednumber—
attachmentsrequiredobject[]—
received_atrequiredstring—
created_atrequiredstring—
thread_idstring | nullThe conversation (`thr_…`); null until the message is threaded.
reply_tostring[]Reply-To addresses: answer these before `from` when present.
headersobjectThe headers we keep, by lower-case name: `date`, `in-reply-to`, `references`, `reply-to`, `return-path`, `list-unsubscribe` (when present).
sent_by_usbooleanA copy of one of your own sends that came back to your receiving domain. Its `text` and `html` are null: sent bodies aren't on the API (they can carry a sign-in or reset link).
200401403404

Get an attachment download URL

GET/api/v1/email/received/{id}/attachments/{attachmentId}

GET /email/received/{id}/attachments/{attachmentId}
curl -X GET 'https://www.unitpost.com/api/v1/email/received/email_123/attachments/att_789' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "received_attachment_url",
  "url": "https://example.com",
  "expires_at": "2026-01-01T00:00:00.000Z"
}

Get a short-lived, signed URL for downloading one inbound attachment's bytes. Fetch the URL and download promptly — it expires quickly (the expiry is included in the response). Find attachment ids on the message via Retrieve a received email. A copy of an email you sent (sent_by_us) is a 403, like its body: what you send isn't readable through the API. Requires the emails:read capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
attachmentIdrequiredstring · path—
Response · 200 fields3 fields
FieldTypeDescription
objectrequiredenumreceived_attachment_url—
urlrequiredstringA signed, expiring URL to download the attachment bytes.
expires_atrequiredstringISO 8601 expiry of the signed URL (~5 minutes out).
200401403404503

Get a received email's original message

GET/api/v1/email/received/{id}/raw

GET /email/received/{id}/raw
curl -X GET 'https://www.unitpost.com/api/v1/email/received/email_123/raw' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "received_email_raw",
  "url": "https://example.com",
  "expires_at": "2026-01-01T00:00:00.000Z",
  "size_bytes": 1
}

Get a short-lived, signed URL for the received message's full original MIME (.eml), headers, every part and attachment included. A body over 256 KB isn't inlined on Retrieve a received email, so this is how to read it. Download promptly: the URL expires in about 5 minutes. Stored messages are kept 30 days. A copy of an email you sent (sent_by_us) is a 403. Requires the emails:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredenumreceived_email_raw—
urlrequiredstringA signed, expiring URL to download the original message (.eml, RFC 5322).
expires_atrequiredstringISO 8601 expiry of the signed URL (~5 minutes out).
size_bytesrequiredintegerThe message's size in bytes.
200401403404422503

Email threads

Work your inbox as conversations: list and read them, mark them read, report spam, block a sender, reply or forward, and delete a conversation, as Emails → Received does in the dashboard.

List conversations

GET/api/v1/email/threads

GET /email/threads
curl -X GET 'https://www.unitpost.com/api/v1/email/threads' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "email_thread",
      "id": "id_123",
      "subject": "Welcome to Acme",
      "last_message_at": "2026-01-01T00:00:00.000Z",
      "last_direction": "inbound",
      "snippet": "string",
      "from": "you@yourdomain.com",
      "from_name": "string",
      "inbox_address": "string",
      "message_count": 1,
      "has_attachments": false,
      "flagged": false,
      "replied": false
    }
  ],
  "next_cursor": "string"
}

Your inbox's conversations, newest activity first, as Emails → Received shows them: each received message and the replies and forwards sent from it are one conversation. Every conversation is listed: read state and Spam are the dashboard's. q searches the subject, the sender and the opening words. Page with next_cursor as after. snippet is null when the newest message is one you sent (or a copy of your own send): sent bodies aren't on the API, and q never matches a withheld snippet, so a page can be shorter than limit while has_more is true. q shares the search rate policy. Any other query key is a 422. Requires the emails:read capability.

Parameters3 fields
FieldTypeDescription
qstring · querySearch the subject, sender and opening words.
limitinteger · query1–100 (default 50).
afterstring · queryThe previous page's `next_cursor`.
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
subjectrequiredstring | null—
last_message_atrequiredstring—
last_directionrequiredenuminbound | outbound—
snippetrequiredstring | nullThe newest received message's opening words; null when the newest message is one you sent.
fromrequiredstring | nullThe other party: the newest received message's sender.
from_namerequiredstring | null—
inbox_addressrequiredstring | nullYour address it came in on (the newest received message's To).
message_countrequiredinteger—
has_attachmentsrequiredboolean—
flaggedrequiredbooleanA received message was flagged spam or virus, or failed SPF, DKIM or DMARC.
repliedrequiredbooleanA reply or forward was sent from this conversation.
200401403422

Retrieve a conversation

GET/api/v1/email/threads/{id}

GET /email/threads/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/threads/thr_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "email_thread",
  "id": "id_123",
  "subject": "Welcome to Acme",
  "last_message_at": "2026-01-01T00:00:00.000Z",
  "sender": {
    "address": "string"
  },
  "older_hidden": false,
  "older_cursor": "string",
  "sent_with_unitpost": false,
  "messages": [
    {
      "object": "received_email",
      "direction": "inbound",
      "id": "id_123",
      "received_at": "2026-01-01T00:00:00.000Z",
      "from": "you@yourdomain.com",
      "from_name": "string",
      "to": [
        "customer@example.com"
      ],
      "cc": [
        "string"
      ],
      "reply_to": [
        "string"
      ],
      "subject": "Welcome to Acme",
      "message_id": "message_123",
      "text": "string",
      "html": "string",
      "verdicts": {
        "spam": "string",
        "virus": "string",
        "spf": "string",
        "dkim": "string",
        "dmarc": "string"
      },
      "size": 1,
      "attachments": [
        {
          "object": "received_attachment",
          "id": "id_123",
          "filename": "string",
          "content_type": "string",
          "content_disposition": "string",
          "content_id": "content_123",
          "size": 1
        }
      ],
      "sent_by_us": false,
      "duplicate": false
    }
  ]
}

One conversation, oldest message first: what you received (bodies, reply_to, verdicts, attachments) and what you sent from it (status and recipients, no body). A long conversation comes in pages, newest first: this read holds its newest limit messages (fewer when their bodies are large), and older_cursor passed as before reads the messages before them, as the inbox's "Show earlier messages" does. Answer a message with Reply to a conversation. Requires the emails:read capability.

Parameters3 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryMessages per read, 1–100 (default 50). A read stays under a size budget, so big messages can make it shorter.
beforestring · queryThe previous read's `older_cursor`: read the messages before those.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
subjectrequiredstring | null—
last_message_atrequiredstring—
senderrequiredobject | nullThe other party; null when the conversation has no received mail.
older_hiddenrequiredbooleanOlder messages exist than the ones in `messages`; read them with `before` = `older_cursor`.
older_cursorrequiredstring | nullPass as `before` to read the messages before these (the next page back). Null when nothing older remains.
sent_with_unitpostrequiredbooleanA reply from here carries the "Sent with Unitpost" line (your plan decides).
messagesrequiredobject[]Oldest first. What you sent is metadata only: no body.
200401403404422

Delete a conversation

DELETE/api/v1/email/threads/{id}

DELETE /email/threads/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/email/threads/thr_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "email_thread",
  "id": "id_123",
  "deleted": true,
  "deleted_messages": 0
}

Delete a conversation for good, as the inbox's Delete does. Its received messages are erased (they still count toward usage, and never come back); replies and forwards sent from it stay on your sent emails. It can't be undone. Also requires emails:read. Requires the emails:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredenumemail_thread—
idrequiredstring—
deletedrequiredenumtrue—
deleted_messagesrequiredintegerReceived messages erased.
200401403404

Reply to a conversation

POST/api/v1/email/threads/{id}/reply

POST /email/threads/{id}/reply
curl -X POST 'https://www.unitpost.com/api/v1/email/threads/thr_123/reply' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "email",
  "id": "id_123",
  "status": "queued",
  "thread_id": "thread_123"
}

Reply, reply all or forward one received message of the conversation (received_email_id), as the inbox does: your text and/or html go on top and the original is quoted under them; a reply carries In-Reply-To and References; a forward carries the attachments you list in forward_attachment_ids. The message joins the conversation and the conversation is marked read. For a reply, send to the message's reply_to addresses, else its from. It goes out now (no scheduled_at) through the same checks as any send. Pass an Idempotency-Key: a retry with it never sends twice. A copy of one of your own sends (sent_by_us) is never forwarded or quoted, since what you send isn't readable through the API: a reply to it goes without the quote, and a forward of it is a 403. Also requires emails:read (a reply quotes mail). Requires the emails:send capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
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 body13 fields
FieldTypeDescription
received_email_idrequiredstringThe received message (`inb_…`) in this conversation to answer or forward.
moderequiredenumreply | reply_all | forward`reply` (the sender), `reply_all` (everyone on it), or `forward` (to someone new, with the original's attachments you pick).
fromrequiredstringOne of your sending addresses, e.g. the address the message came in on.
torequiredstring | string[]For a reply: the message's `reply_to`, else its `from`. Up to 50.
ccstring | string[]Copy recipients, up to 50.
bccstring | string[]Blind-copy recipients, up to 50.
subjectrequiredstringUsually `Re: <their subject>` (or `Fwd:`).
textstringYour words, plain text. The original is quoted under them.
htmlstringYour words, HTML. The original is quoted under them.
include_quotebooleanQuote the original under a reply (default true; a forward always carries it). A copy of one of your own sends (`sent_by_us`) is never quoted: left out, it defaults to false there, and `true` is a `403`.
forward_attachment_idsstring[]Forward only: the original's attachments to carry over (their `id`s).
attachmentsobject[]Files to attach: `content` (base64) or `path` (an https URL), up to 20 with the carried-over ones.
trackingbooleanOpen and click tracking for this message; omitted = the sending domain's default.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredenumemail—
idrequiredstringThe sent email (`email_…`); read it with `GET /email/{id}`.
statusrequiredenumqueued | scheduled—
thread_idrequiredstring—
200400401403404409422429

Topics

Subscription categories (e.g. Promotions) recipients can opt out of without leaving your list, independent of segment membership. Scope a campaign to a topic and opted-out contacts are skipped automatically.

List topics

GET/api/v1/email/topics

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

Retrieve a list of your subscription topics, cursor-paginated. A topic is a category of email (e.g. Product updates, Promotions) that recipients can opt out of without leaving your list entirely. Pass ?archived=true to list archived topics instead. Create one with Create a topic, or check a contact's preferences with List a contact's topic subscriptions. Requires the topics: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 topics instead of active ones.
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401422503

Create a topic

POST/api/v1/email/topics

POST /email/topics
curl -X POST 'https://www.unitpost.com/api/v1/email/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product updates",
    "default_opt_in": true
  }'
Response · 201
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a subscription topic — a category recipients can opt out of on their own (e.g. Promotions) while staying on your list. default_opt_in decides whether contacts with no explicit preference are treated as subscribed. Scope a campaign to a topic so opted-out contacts are skipped automatically via Create a campaign, and set an individual contact's preference with Set a contact's topic preference. Topics differ from segments: a segment decides who a campaign targets, a topic lets recipients opt out. Requires the topics:write capability.

Request body3 fields
FieldTypeDescription
namerequiredstring—
descriptionstring—
default_opt_inboolean—
Response · 201 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
201401409422

Retrieve a topic

GET/api/v1/email/topics/{id}

GET /email/topics/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single topic by id, including its name and default_opt_in setting. Change it with Update a topic, or list every topic with List topics. Requires the topics:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401404503

Update a topic

PATCH/api/v1/email/topics/{id}

PATCH /email/topics/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/topics/top_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "topic",
  "id": "id_123",
  "name": "Example",
  "description": "string",
  "channel": "email",
  "default_opt_in": false,
  "subscriber_count": 1,
  "unsubscribed_count": 1,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a topic's name or default_opt_in behavior, or pass { "archived": true | false } to archive or restore it. Only explicit choices are stored, so changing default_opt_in subscribes (true) or unsubscribes (false) every contact with no explicit choice on the topic at once; Unitpost-Warning names how many. Archiving a topic hides it and stops it from being targeted, but is blocked with 409 while an active campaign still targets it. To manage a single contact's preference, use Set a contact's topic preference. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
namestring—
descriptionstring | null—
default_opt_inboolean—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
descriptionrequiredstring | null—
channelrequiredenumemail | smsWhich channel the topic belongs to. Email topics are managed under `/email/topics`, SMS topics under `/sms/topics`.
default_opt_inrequiredboolean—
subscriber_countintegerContacts subscribed to this topic, among those the channel can reach (an email address, or an SMS number): for an opt-out topic everyone but those who opted out of it, for an opt-in topic those who opted in. A send also skips contacts unsubscribed from everything and suppressed addresses. The dashboard's count.
unsubscribed_countintegerReachable contacts who opted out of this topic.
created_atrequiredstring—
updated_atrequiredstring—
200401404409422

Delete a topic

DELETE/api/v1/email/topics/{id}

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

Archive a topic (a soft delete — existing subscription records are preserved so you can restore it later). It's blocked with 409 while an active campaign still targets it. Restore an archived topic by sending { "archived": false } to Update a topic. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404409

Opt contacts out of a topic

POST/api/v1/email/topics/{id}/opt-out

POST /email/topics/{id}/opt-out
curl -X POST 'https://www.unitpost.com/api/v1/email/topics/top_123/opt-out' \
  -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"
}

Opt many contacts out of this topic in one call, as a background job: 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. Each contact is opted out as Set a contact's topic preference would: one that was subscribed gets a topic.unsubscribed webhook and an activity row naming your key; one already opted out is left as it is, with no webhook. Suppressions and other topics are untouched, and there is no bulk opt-in. Listed contacts are checked first: the first that isn't one of yours is a 404 naming it (details), and nothing starts. The answer is the job (202, Location); follow it with Retrieve a job. Pass an Idempotency-Key so a retry answers the same job instead of starting another. Requires the topics:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
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 body3 fields
FieldTypeDescription
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

List a contact's topic subscriptions

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

GET /contacts/{id}/topics
curl -X GET 'https://www.unitpost.com/api/v1/contacts/con_123/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_topic",
      "topic_id": "topic_123",
      "channel": "email",
      "subscribed": false,
      "status": "subscribed",
      "source": "user"
    }
  ]
}

Retrieve a contact's effective subscription state for every active topic, cursor-paginated. Each row resolves the contact's explicit preference against the topic's default_opt_in, so subscribed is always the answer to "would this contact receive a campaign scoped to this topic?". Change a preference with Set a contact's topic preference. Requires the topics: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 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
200401404422

Set a contact's topic preference

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

POST /contacts/{id}/topics
curl -X POST 'https://www.unitpost.com/api/v1/contacts/con_123/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "topic_id": "top_123",
    "subscribed": false
  }'
Response · 201
{
  "object": "contact_topic",
  "topic_id": "topic_123",
  "channel": "email",
  "subscribed": false,
  "status": "subscribed",
  "source": "user"
}

Subscribe or unsubscribe a contact for one topic. This records an explicit preference that overrides the topic's default_opt_in, and it's idempotent — setting the same preference twice succeeds. PUT behaves identically. Read the contact's current state with List a contact's topic subscriptions; change several at once with Update a contact's topic preferences. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
topic_idstring—
topicstring—
subscribedrequiredboolean—
Response · 201 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
201401404422

Update a contact's topic preferences

PATCH/api/v1/contacts/{id}/topics

PATCH /contacts/{id}/topics
curl -X PATCH 'https://www.unitpost.com/api/v1/contacts/con_123/topics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "topics": [
      {
        "topic_id": "top_123",
        "subscribed": false
      },
      {
        "topic_id": "top_456",
        "subscribed": true
      }
    ]
  }'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_topic",
      "topic_id": "topic_123",
      "channel": "email",
      "subscribed": false,
      "status": "subscribed",
      "source": "user"
    }
  ]
}

Subscribe or unsubscribe a contact for several topics in one call: topics lists up to 50 preferences, each topic once. Topics you leave out keep their current preference. The contact and every topic are checked before any preference is set, so an unknown topic is a 404 naming it and nothing changes. Each preference is then recorded as Set a contact's topic preference records one (topic.subscribed / topic.unsubscribed only when it actually changes), and it's idempotent. The answer lists the resolved subscriptions in the order sent. Any key other than topics, in the body or in an item, is a 422. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
topicsrequiredobject[]The preferences to change, up to 50, each topic once. Topics left out keep theirs.
Response · 200 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
200400401403404422

Set a contact's topic preference (alias of POST)

PUT/api/v1/contacts/{id}/topics

PUT /contacts/{id}/topics
# API: no generated example for PUT https://www.unitpost.com/api/v1/contacts/:id/topics
Response · 201
{
  "object": "contact_topic",
  "topic_id": "topic_123",
  "channel": "email",
  "subscribed": false,
  "status": "subscribed",
  "source": "user"
}

Identical to Set a contact's topic preference — provided so clients that prefer PUT semantics for an upsert can use it interchangeably. Requires the topics:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
topic_idstring—
topicstring—
subscribedrequiredboolean—
Response · 201 fields6 fields
FieldTypeDescription
objectrequiredstring—
topic_idrequiredstring—
channelrequiredenumemail | smsThe topic's channel: manage it under `/email/topics` or `/sms/topics`.
subscribedrequiredboolean—
statusrequiredenumsubscribed | unsubscribed—
sourcerequiredenumuser | manual | import | api—
201401404422

Campaigns

One-to-many sends to a segment or an inline recipient list. Draft, validate, schedule, send, pause, resume, and cancel — with a pre-send report that catches problems before anything goes out.

List campaigns

GET/api/v1/email/campaigns

GET /email/campaigns
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign",
      "id": "id_123",
      "name": "Example",
      "template_id": "template_123",
      "segment_id": "segment_123",
      "topic_id": "topic_123",
      "from": "you@yourdomain.com",
      "subject": "Welcome to Acme",
      "preview_text": "string",
      "open_tracking": false,
      "click_tracking": false,
      "status": "draft",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "variable_fallbacks": {},
      "excluded_contact_ids": [
        "string"
      ],
      "total_recipients": 1,
      "projected_recipients": {
        "total": 1,
        "reachable": 0,
        "skipped": 0
      },
      "sent_count": 1,
      "failed_count": 1,
      "pause_reason": {
        "code": "user",
        "message": "string",
        "metric": "hard_bounce_rate",
        "value": 0,
        "threshold": 0,
        "sample": {
          "events": 0,
          "of": 0
        },
        "window": {
          "since": "string"
        },
        "decided_by": "floor",
        "resume": "self_serve",
        "paused_at": "2026-01-01T00:00:00.000Z"
      },
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your campaigns, cursor-paginated. Each row is a reference to one campaign and its current status (draft, scheduled, sending, sent, …). Use a campaign's id with Retrieve a campaign for the full record, or with List sent emails (?campaign_id=) to see the individual emails it produced. Deleted (archived) campaigns are hidden; pass ?archived=true to list only archived ones, which can be restored for 30 days. Requires the campaigns:read capability.

Parameters6 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 campaigns instead of active ones.
topic_idstring · queryOnly campaigns scoped to this topic. An id from another workspace or channel matches nothing.
segment_idstring · queryOnly campaigns aimed at this segment (`seg_…`).
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401422

Create a campaign

POST/api/v1/email/campaigns

POST /email/campaigns
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "June newsletter",
    "subject": "What's new",
    "from": "you@yourdomain.com",
    "template_id": "tmpl_123",
    "segment_id": "seg_123"
  }'
Response · 201
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a campaign in draft. Target either a saved segment (segment_id, see Create a segment) or an inline recipients list of up to 5,000 addresses (a list you keep in your own system needs no import: the addresses become contacts, so an unsubscribe is remembered), and optionally scope it to a subscription topic (topic_id) so contacts who opted out of that topic are skipped automatically. Content comes from a published template_id (campaigns have no inline html/text). Set scheduled_at (ISO 8601 with Z or an offset such as 2026-10-27T08:00:00-07:00; stored and returned in UTC; inside your plan's scheduling window, at most 90 days) to save a send time. Without one, or once it has passed, the campaign goes out the moment you send it (validate warns SCHEDULE_PASSED). Nothing is sent yet — edit the draft with Update a campaign, check it with Validate a campaign, then launch it with Send a campaign. Requires the campaigns:write capability.

Request body13 fields
FieldTypeDescription
namerequiredstring—
template_idrequiredstring—
segment_idstring—
recipientsstring[]—
topic_idstring—
fromrequiredstring—
subjectstring—
preview_textstring—
scheduled_atstringISO 8601 with `Z` or a `±hh:mm` offset; normalized to UTC (reads return the UTC time). A time without a timezone, a bare date, or natural language is a `422`.
open_trackingboolean | null—
click_trackingboolean | null—
variable_fallbacksobject—
excluded_contact_idsstring[]—
Response · 201 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
201401403404409422

Retrieve a campaign

GET/api/v1/email/campaigns/{id}

GET /email/campaigns/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single campaign by id, including its status, targeting, content references, and schedule. To see the individual emails a sent campaign produced, filter List sent emails by campaign_id; for a pre-send readiness report, use Validate a campaign. Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a campaign

PATCH/api/v1/email/campaigns/{id}

PATCH /email/campaigns/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Edit a campaign while it's still in draft (edits after that return 409; unschedule a scheduled one first with Unschedule a campaign). Change its name, subject, from, preview_text, template_id or segment_id (a template or segment gets create's checks: this workspace's, published, not archived). A value equal to the draft's is no edit, so you can send back what you read. Beyond content and targeting, you can: send archived to archive/restore it; set variable_fallbacks (fill-only per-variable defaults) and/or excluded_contact_ids to resolve a send blocked by missing variables — the API equivalent of the dashboard's pre-send fix; set topic_id to scope it to a subscription topic (or null to clear); set open_tracking/click_tracking (tri-state; null inherits the template/domain default); and set or clear (null) the saved scheduled_at (a misnamed time key is a 422). Other keys are ignored. See what's blocking a send with Validate a campaign. Requires the campaigns:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body13 fields
FieldTypeDescription
archivedboolean—
namestring—
template_idstring—
segment_idstring—
fromstring—
subjectstring | null—
preview_textstring | null—
topic_idstring | null—
open_trackingboolean | null—
click_trackingboolean | null—
variable_fallbacksobject—
excluded_contact_idsstring[]—
scheduled_atstring | null—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422

Delete a campaign

DELETE/api/v1/email/campaigns/{id}

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

Archive a campaign that's in draft or a terminal state (sent, canceled, failed): it leaves the list and is permanently deleted after 30 days. Restore it before then with PATCH { "archived": false }. A campaign that's mid-flight can't be archived — stop it first with Cancel a campaign. Requires the campaigns:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404409

Send a campaign

POST/api/v1/email/campaigns/{id}/send

POST /email/campaigns/{id}/send
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Validate a draft campaign and then send it now or schedule it. scheduled_at in the body schedules it for that time (ISO 8601 with Z or an offset; in the future, inside your plan's scheduling window); null sends it now; omit it to use the draft's saved scheduled_at while that is still in the future — **otherwise the campaign is sent immediately** (except right after a dashboard Unschedule, which cleared its time: then it answers 409 with details[].code send_time_required and sends nothing, so name the time or pass null). The response's scheduled_at is the resolved time in UTC (null when it is sending now). A misnamed time field (scheduledAt, send_at, deliver_at, …) is a 422 naming scheduled_at, and a body that isn't JSON (a form-encoded one included) is a 400; nothing is sent in either case. Other fields are ignored and a JSON null body means no options. If anything blocks the send (unverified domain, missing template variables, empty audience, …) you get a 409 with each blocking reason itemized in error.details[] (code is the reason, as in the validate report's blockers[].code). To see the full pre-send report without attempting a send, use Validate a campaign; fix variable issues via Update a campaign. A launched campaign can be paused or canceled, and a scheduled one rescheduled. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
scheduled_atstring | null—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200400401402403404409422429502503

Cancel a campaign

POST/api/v1/email/campaigns/{id}/cancel

POST /email/campaigns/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Cancel a draft, scheduled, or sending campaign. Cancelation is terminal — the campaign can't be restarted afterwards. Messages already sent to recipients are not recalled. If you only want to stop temporarily, use Pause a campaign instead. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409

Pause a campaign

POST/api/v1/email/campaigns/{id}/pause

POST /email/campaigns/{id}/pause
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/pause' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Pause a scheduled or sending campaign. A paused send stops cleanly between recipients — already-sent messages are untouched, and no partial email is ever produced. Continue where it left off with Resume a campaign, or stop it for good with Cancel a campaign. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409

Unschedule a campaign

POST/api/v1/email/campaigns/{id}/unschedule

POST /email/campaigns/{id}/unschedule
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/unschedule' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Move a scheduled campaign (or one paused before it started sending) back to draft, same id, so you can edit it. Content, audience and overrides are kept; the saved send time is cleared, so the next Send a campaign needs an explicit scheduled_at (409 send_time_required without one). A campaign that started sending can't be unscheduled: cancel it and duplicate it (the copy goes to the whole segment again, including people the first run reached, unless you set excluded_contact_ids). No body; any key is a 422. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409422

Results for several campaigns

GET/api/v1/email/campaigns/stats

GET /email/campaigns/stats
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign_stats",
      "campaign_id": "campaign_123",
      "recipients": 0,
      "failed_recipients": 0,
      "suppressed": 0,
      "counts": {
        "sent": 0,
        "delivered": 0,
        "opened": 0,
        "clicked": 0,
        "unsubscribed": 0,
        "bounced": 0,
        "complained": 0,
        "failed": 0
      },
      "rates": {
        "delivery": 0,
        "open": 0,
        "click": 0,
        "unsubscribe": 0,
        "bounce": 0,
        "complaint": 0
      },
      "tracking": {
        "open": false,
        "click": false
      },
      "source": "live",
      "snapshotted_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

The same numbers as Campaign results for up to 100 campaigns in one read: ids, comma-separated. An id that isn't one of this workspace's email campaigns is left out of data, never an error. Pass ids once; a repeated or any other query key is a 422. Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idsrequiredstring · queryComma-separated campaign ids (1–100).
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
campaign_idrequiredstring—
recipientsrequiredintegerContacts the campaign was sent to (suppressed addresses never became recipients).
failed_recipientsrequiredintegerRecipients that didn't receive it, including ones that failed before a message existed.
suppressedrequiredinteger | nullContacts left out at send because their address is suppressed; null for campaigns sent before this was counted.
countsrequiredobject—
ratesrequiredobjectPercentages with one decimal (12.3 = 12.3%). null when there is nothing to measure yet, or when that tracking was off.
trackingrequiredobject—
sourcerequiredenumlive | snapshot | combinedLive rows, the counts frozen when old messages were cleaned up, or both.
snapshotted_atrequiredstring | null—
200401403422503

Campaign results

GET/api/v1/email/campaigns/{id}/stats

GET /email/campaigns/{id}/stats
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/stats' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_stats",
  "campaign_id": "campaign_123",
  "recipients": 0,
  "failed_recipients": 0,
  "suppressed": 0,
  "counts": {
    "sent": 0,
    "delivered": 0,
    "opened": 0,
    "clicked": 0,
    "unsubscribed": 0,
    "bounced": 0,
    "complained": 0,
    "failed": 0
  },
  "rates": {
    "delivery": 0,
    "open": 0,
    "click": 0,
    "unsubscribe": 0,
    "bounce": 0,
    "complaint": 0
  },
  "tracking": {
    "open": false,
    "click": false
  },
  "source": "live",
  "snapshotted_at": "2026-01-01T00:00:00.000Z"
}

A campaign's results: delivered, unique opens and clicks, unsubscribes, bounces, complaints and their rates, recipients, and who didn't receive it. Open and click rates are null when that tracking was off; every rate is null until something was sent. Old messages are cleaned up after your plan's retention window; their counts are kept (source). Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
campaign_idrequiredstring—
recipientsrequiredintegerContacts the campaign was sent to (suppressed addresses never became recipients).
failed_recipientsrequiredintegerRecipients that didn't receive it, including ones that failed before a message existed.
suppressedrequiredinteger | nullContacts left out at send because their address is suppressed; null for campaigns sent before this was counted.
countsrequiredobject—
ratesrequiredobjectPercentages with one decimal (12.3 = 12.3%). null when there is nothing to measure yet, or when that tracking was off.
trackingrequiredobject—
sourcerequiredenumlive | snapshot | combinedLive rows, the counts frozen when old messages were cleaned up, or both.
snapshotted_atrequiredstring | null—
200401403404422503

List who a campaign would reach

GET/api/v1/email/campaigns/{id}/recipients

GET /email/campaigns/{id}/recipients
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/recipients' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign_recipient",
      "contact_id": "contact_123",
      "email": "customer@example.com",
      "name": "Example",
      "status": "sendable",
      "reason": "string",
      "reason_code": "unsubscribed"
    }
  ],
  "next_cursor": "string"
}

Who the campaign would reach if sent now, one row per segment member, by the send's own rule: sendable, missing_data (a required variable has no value), suppressed or excluded, with the reason. The numbers of Validate a campaign, member by member. Rows run in contact-id order: pass next_cursor as after for the next page. A page can hold fewer rows than limit while has_more is true (a rare status in a big segment is walked in bounded steps). Rows name contacts, so this also requires contacts:read. Requires the campaigns:read capability.

Parameters4 fields
FieldTypeDescription
idrequiredstring · path—
statusstring · queryOnly members with this outcome (default `all`).
limitinteger · queryRows per page (1–100, default 50).
afterstring · queryThe previous page's `next_cursor`.
Response · 200 fields7 fields
FieldTypeDescription
objectrequiredstring—
contact_idrequiredstring—
emailrequiredstring | null—
namerequiredstring | null—
statusrequiredenumsendable | missing_data | suppressed | excludedWhat a send now would do for this member, by the send's own rule.
reasonrequiredstring | nullWhy, in plain words; null when sendable.
reason_coderequiredenum | null—
200401403404409422503

List addresses a quality pause flagged

GET/api/v1/email/campaigns/{id}/quality/affected

GET /email/campaigns/{id}/quality/affected
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/quality/affected' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "campaign_affected_recipient",
      "email": "customer@example.com",
      "contact_id": "contact_123",
      "reason": "hard_bounce"
    }
  ]
}

After an automatic quality pause: the recipients whose message hard-bounced (hard_bounce) or drew a spam complaint (complaint). They're already suppressed; this is for cleaning the source list. By address, limit per page (default and most 10,000); when has_more, pass the last row's email as after for the rest. Take them out of the campaign's segment with Remove flagged addresses. Requires the campaigns:read capability.

Parameters3 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryAddresses per page, 1–10,000 (default 10,000).
afterstring · queryThe last row's `email` from the previous page.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
emailrequiredstring—
contact_idrequiredstring | null—
reasonrequiredenumhard_bounce | complaintThe address doesn't exist (`hard_bounce`), or the person marked it as spam.
200401403404422503

Remove flagged addresses from the audience

POST/api/v1/email/campaigns/{id}/quality/remove-affected

POST /email/campaigns/{id}/quality/remove-affected
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/quality/remove-affected' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_quality_removal",
  "removed": 0
}

While a campaign is paused for its delivery quality: take every hard-bounced and complained contact out of its static segment. It edits a reusable segment for good. Each removal records its activity and fires segment.left (the first at once, the rest within a few minutes); a repeat removes nothing. A campaign that isn't paused for quality, or a filter (dynamic) segment, is a 409 (a filter's matches can't be removed one by one, and they're suppressed anyway). It doesn't resume the campaign. No body. Requires the segments:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields2 fields
FieldTypeDescription
objectrequiredenumcampaign_quality_removal—
removedrequiredinteger—
200400401403404409422503

Request a review for a paused campaign

POST/api/v1/email/campaigns/{id}/quality/request-review

POST /email/campaigns/{id}/quality/request-review
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/quality/request-review' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_review_request",
  "requested": false,
  "already_requested": false
}

When a campaign the delivery-quality check paused again needs our team's review before it can resume (Resume a campaign answers 409 review_required): ask for that review. Our team is notified once a day per campaign; a repeat answers already_requested: true and notifies no one. A campaign that isn't waiting for a review is a 409, and so is one paused while our team reviews the whole account (resume: account_review). No body. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields3 fields
FieldTypeDescription
objectrequiredenumcampaign_review_request—
requestedrequiredboolean—
already_requestedrequiredboolean—
200400401403404409422

Duplicate a campaign

POST/api/v1/email/campaigns/{id}/duplicate

POST /email/campaigns/{id}/duplicate
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/duplicate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Copy a campaign into a new draft. Only configuration is copied (name, template, segment, sender, subject, preview text, topic, tracking overrides, fallbacks, exclusions), never the send time or status, and every create check runs again (template published, segment not archived, domain, limits). Optional name for the copy; any other key is a 422. Pass an Idempotency-Key so a retry returns the same copy instead of making another. Requires the campaigns:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
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
namestringName of the copy. Defaults to the source's name with " (copy)".
Response · 201 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

Resume a campaign

POST/api/v1/email/campaigns/{id}/resume

POST /email/campaigns/{id}/resume
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/resume' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Resume a paused campaign. Sending continues with the recipients that hadn't been reached yet — only them: contacts who joined the segment after the campaign started are not added, and anyone already delivered to is skipped, so nobody receives the campaign twice. After an automatic quality pause (pause_reason.code hard_bounce_rate, complaint_rate or quality_review) the quality check measures only sends made after the resume. A campaign whose scheduled_at is still in the future waits for it; otherwise it sends immediately. Resume runs the same checks as Send a campaign and answers with the same errors; the campaign stays paused when one fails. Pause a send with Pause a campaign. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401402403404409429

Reschedule a campaign

POST/api/v1/email/campaigns/{id}/reschedule

POST /email/campaigns/{id}/reschedule
curl -X POST 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/reschedule' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "scheduled_at": "2026-07-01T15:00:00Z"
  }'
Response · 200
{
  "object": "campaign",
  "id": "id_123",
  "name": "Example",
  "template_id": "template_123",
  "segment_id": "segment_123",
  "topic_id": "topic_123",
  "from": "you@yourdomain.com",
  "subject": "Welcome to Acme",
  "preview_text": "string",
  "open_tracking": false,
  "click_tracking": false,
  "status": "draft",
  "scheduled_at": "2026-01-01T00:00:00.000Z",
  "variable_fallbacks": {},
  "excluded_contact_ids": [
    "string"
  ],
  "total_recipients": 1,
  "projected_recipients": {
    "total": 1,
    "reachable": 0,
    "skipped": 0
  },
  "sent_count": 1,
  "failed_count": 1,
  "pause_reason": {
    "code": "user",
    "message": "string",
    "metric": "hard_bounce_rate",
    "value": 0,
    "threshold": 0,
    "sample": {
      "events": 0,
      "of": 0
    },
    "window": {
      "since": "string"
    },
    "decided_by": "floor",
    "resume": "self_serve",
    "paused_at": "2026-01-01T00:00:00.000Z"
  },
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Move a scheduled campaign to a new send time: scheduled_at in ISO 8601 with Z or an offset, in the future and inside your plan's scheduling window; the response returns it in UTC (a time without a timezone is still read as UTC, deprecated). A draft is scheduled with Send a campaign instead. Only campaigns that haven't started sending can be rescheduled — once a send is in flight, pause or cancel it instead. Requires the campaigns:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
scheduled_atrequiredstringISO 8601 with `Z` or a `±hh:mm` offset; returned in UTC. A time without a timezone is read as UTC (deprecated: include the zone).
Response · 200 fields22 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
template_idrequiredstring—
segment_idrequiredstring—
topic_idrequiredstring | null—
fromrequiredstring—
subjectrequiredstring | null—
preview_textrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
statusrequiredenumdraft | scheduled | sending | paused | sent | canceled | failed—
scheduled_atrequiredstring | null—
variable_fallbacksrequiredobject—
excluded_contact_idsrequiredstring[]—
total_recipientsrequirednumberRecipients the engine admitted when the campaign started sending. 0 while it is `draft` or `scheduled`: read `projected_recipients`, or `sendable` from validate.
projected_recipientsobject | nullThe audience counted when the campaign was sent or scheduled: `total` segment members, `reachable` who will get it, `skipped` (unsubscribed, suppressed, excluded). Null for a draft that was never sent: read validate. Read-only.
sent_countrequirednumber—
failed_countrequirednumber—
pause_reasonrequiredobject | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404409422502

Validate a campaign

GET/api/v1/email/campaigns/{id}/validate

GET /email/campaigns/{id}/validate
curl -X GET 'https://www.unitpost.com/api/v1/email/campaigns/cmp_123/validate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "campaign_validation",
  "total_members": 1,
  "sendable": 0,
  "suppressed": 0,
  "excluded": 0,
  "missing_data": [
    {
      "contact_id": "contact_123",
      "email": "customer@example.com",
      "missing": [
        "string"
      ]
    }
  ],
  "unresolved_variables": [
    "string"
  ],
  "variable_coverage": [
    {
      "name": "Example",
      "missing_count": 1,
      "eligible": 0,
      "missing_for_all": false,
      "has_default": false
    }
  ],
  "blockers": [
    {
      "code": "string",
      "message": "string"
    }
  ],
  "can_send": false,
  "warnings": [
    {
      "code": "QUOTA_OVERSUBSCRIBED",
      "severity": "info",
      "title": "string",
      "message": "string",
      "guide_url": "https://example.com",
      "fix_url": "https://example.com"
    }
  ]
}

Run a non-mutating pre-send check and get the full readiness report: how many contacts will receive the campaign (sendable), how many are suppressed or excluded, which contacts are missing template variables, variable_coverage[] per variable (missing_for_all: a variable_fallbacks default is required to send; otherwise a default is optional and only fills the blanks), blockers, warnings, and a final can_send verdict. Nothing is sent or changed. Show the user sendable, the blockers and the warnings before sending. Fix reported variable gaps with Update a campaign (variable_fallbacks / excluded_contact_ids), then launch with Send a campaign. Requires the campaigns:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields11 fields
FieldTypeDescription
objectrequiredenumcampaign_validation—
total_membersrequiredinteger—
sendablerequiredinteger—
suppressedrequiredinteger—
excludedrequiredinteger—
missing_datarequiredobject[]—
unresolved_variablesrequiredstring[]—
variable_coverageobject[]Per template variable that some recipients lack, missing-for-all first. `missing_for_all`: no recipient has it, so a `variable_fallbacks` default is REQUIRED to send. Otherwise a default is optional and only fills the `missing_count` blanks (it never replaces a recipient's own value); or exclude those contacts. `has_default`: the campaign already sets one.
blockersobject[]What refuses Send right now (draft template, archived segment, unverified domain, …). The same codes as a blocked send's `error.details[].code`.
can_sendrequiredboolean—
warningsrequiredobject[]Deliverability warnings: advice that never blocks `can_send` (credits that may run short, a saved send time that has passed so Send sends now, no subscription topic; and, once switched on, a young sending domain, a send far above your usual volume, no DMARC, recipients mailed in the last few days). Most severe first, at most three. Show them to whoever is about to send.
200202401404

Templates

Reusable email HTML with per-recipient {{variables}} filled at send time. The dashboard visual editor is a separate surface and still uses the structured document internally.

List templates

GET/api/v1/email/templates

GET /email/templates
curl -X GET 'https://www.unitpost.com/api/v1/email/templates' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "template",
      "id": "id_123",
      "name": "Example",
      "subject": "Welcome to Acme",
      "status": "draft",
      "editor": "simple",
      "kind": "simple",
      "preview_text": "string",
      "category": "transactional",
      "html": "string",
      "tsx": "string",
      "text": "string",
      "warnings": [
        "string"
      ],
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your email templates, cursor-paginated. Each row says which editor it's authored in (design, simple or code). List rows omit html and tsx to keep responses small — fetch a single template with Retrieve a template to get it. Reference a template's id when sending with Send or schedule an email or when creating a campaign. 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 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
subjectrequiredstring | null—
statusrequiredenumdraft | published—
editorenumsimple | design | codeWhich editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body.
kindrequiredenumsimple | designedThe coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`.
preview_textstringInbox preview text: the snippet most inboxes show after the subject. Empty when unset.
categoryenumtransactional | marketing`marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update.
htmlstring | null—
tsxstring | nullA `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows.
textstring | nullA `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows.
warningsstring[]Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user.
created_atrequiredstring—
updated_atrequiredstring—
200401422

Create a template

POST/api/v1/email/templates

POST /email/templates
curl -X POST 'https://www.unitpost.com/api/v1/email/templates' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Welcome",
    "subject": "Welcome!",
    "html": "<h1>Hi Mike</h1>"
  }'
Response · 201
{
  "object": "template",
  "id": "id_123",
  "name": "Example",
  "subject": "Welcome to Acme",
  "status": "draft",
  "editor": "simple",
  "kind": "simple",
  "preview_text": "string",
  "category": "transactional",
  "html": "string",
  "tsx": "string",
  "text": "string",
  "warnings": [
    "string"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create a reusable email template from ONE body field, which picks its editor in the dashboard. tsx (the default for anything branded) makes a **Design** template from @unitpost/email components; wrap them in one <Email …> element, or pass theme, to set the page style, so one call makes the finished, branded template. text makes a **Simple** email: a plain, personal note typed like Gmail. html makes a **Code** template: your raw HTML, kept as-is. {{variables}} fill per-recipient at send time. Anything that changed that you didn't write comes back in warnings. Once created, send with it via Send or schedule an email, and iterate with Update a template. Requires the templates:write capability.

Request body8 fields
FieldTypeDescription
namerequiredstring—
subjectstring—
tsxstringA Design email body (editor `design`) — the DEFAULT for anything branded: newsletters, announcements, promos, welcome and product emails, receipts. @unitpost/email component TSX: <Section>, <Row>/<Column>, <Heading>, <Text>, <Button href>, <Image src alt>, <List>, <Divider>, <Spacer>, <Link>, <Code> (props and ready-made layout bands: the `design_library` MCP tool or unitpost.com/components). Wrap the blocks in ONE <Email …> element to set the page in the same call: background-color, body-color, content-width, body-padding, body-radius, body-border-width/-style/-color, font-family, text-color, link-color, preview-text, category. <Section> holds leaf blocks and nested <Section>s (never a <Row>); <Row> holds only <Column>s. Inline <strong>/<em>/<a href> inside <Text>, and <br /> for a line break (a new line in the markup is only a space); no Markdown; no <html>/<body>. Images: hosted https URLs or `/img/{id}` library images only. Don't write the unsubscribe / postal-address footer — marketing templates get it at send. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`.
htmlstringA Code email body (editor `code`): raw HTML kept as-is in one HTML block — the Design editor can show it but not edit it piece by piece. Use it only when the user asks for HTML or brings their own; for a branded email send `tsx` instead. Write simple, email-safe HTML: tables for layout, inline styles, hosted https images. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`.
textstringA Simple email body (editor `simple`) — only when the user wants a plain, personal note that reads like it was typed in Gmail. Plain text exactly as you'd type it into Gmail: lines, a blank line between paragraphs (the only spacing), '- ' or '1. ' list items, inline <b>, <i>, <u>, <s>, <a href="…">, <br>, and <span style="color:#hex; background-color:#hex; font-size:13px|18px|24px; font-family:Georgia"> for colour, highlight, size and font; <div style="text-align:center">…</div> around one line to centre it; <img src="/img/{id}" alt="…" width="400"> alone on a line for an image; {{variables}}. Not supported (removed): headings, layout/sections/buttons, block HTML tags (p, div, table, ul), other CSS, and Markdown (stays literal). Sent as a bare mail-client fragment with no layout; marketing templates get a one-line unsubscribe footer at send time. Max 20,000 characters. Pass exactly one of `tsx`, `html` or `text`.
themeobjectPage-level look of a Design template (`tsx`) — the same settings as the `<Email>` element's attributes. Keys you leave out keep the template's current value (a new template starts from the Unitpost brand theme). Not accepted with `html` (style the HTML itself) or `text` (Simple emails use the reader's own style).
preview_textstringInbox preview text: the snippet shown after the subject. A short line that complements the subject. Wins over a `preview-text` on <Email>.
categoryenumtransactional | marketing—
Response · 201 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
subjectrequiredstring | null—
statusrequiredenumdraft | published—
editorenumsimple | design | codeWhich editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body.
kindrequiredenumsimple | designedThe coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`.
preview_textstringInbox preview text: the snippet most inboxes show after the subject. Empty when unset.
categoryenumtransactional | marketing`marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update.
htmlstring | null—
tsxstring | nullA `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows.
textstring | nullA `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows.
warningsstring[]Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user.
created_atrequiredstring—
updated_atrequiredstring—
201401422

Retrieve a template

GET/api/v1/email/templates/{id}

GET /email/templates/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/templates/tmpl_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "template",
  "id": "id_123",
  "name": "Example",
  "subject": "Welcome to Acme",
  "status": "draft",
  "editor": "simple",
  "kind": "simple",
  "preview_text": "string",
  "category": "transactional",
  "html": "string",
  "tsx": "string",
  "text": "string",
  "warnings": [
    "string"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single template by id, including the rendered html, for a Design template its tsx with the <Email> theme element, and for a Simple one its text (List templates omits both). Use this to read the body in its own editor, then save changes with Update a template. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
subjectrequiredstring | null—
statusrequiredenumdraft | published—
editorenumsimple | design | codeWhich editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body.
kindrequiredenumsimple | designedThe coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`.
preview_textstringInbox preview text: the snippet most inboxes show after the subject. Empty when unset.
categoryenumtransactional | marketing`marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update.
htmlstring | null—
tsxstring | nullA `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows.
textstring | nullA `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows.
warningsstring[]Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user.
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a template

PATCH/api/v1/email/templates/{id}

PATCH /email/templates/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/templates/tmpl_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "Welcome aboard!"
  }'
Response · 200
{
  "object": "template",
  "id": "id_123",
  "name": "Example",
  "subject": "Welcome to Acme",
  "status": "draft",
  "editor": "simple",
  "kind": "simple",
  "preview_text": "string",
  "category": "transactional",
  "html": "string",
  "tsx": "string",
  "text": "string",
  "warnings": [
    "string"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a template's metadata and/or body. Changes take effect for future sends only — emails already sent or queued keep the body they were rendered with. Send the body in the template's own editor (tsx for design, text for simple, html for code); another body field switches the editor. editor alone converts the current body (lossy steps are listed in warnings), and theme alone restyles a Design template, and category switches it between marketing and transactional on any editor. A change to its body, subject or category, or an unpublish, is refused with 409 while a live campaign renders it (see Get a template's usage). Read the current body first with Retrieve a template. Requires the templates:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body10 fields
FieldTypeDescription
namestring—
subjectstring | null—
statusenumdraft | published—
tsxstringA Design email body (editor `design`) — the DEFAULT for anything branded: newsletters, announcements, promos, welcome and product emails, receipts. @unitpost/email component TSX: <Section>, <Row>/<Column>, <Heading>, <Text>, <Button href>, <Image src alt>, <List>, <Divider>, <Spacer>, <Link>, <Code> (props and ready-made layout bands: the `design_library` MCP tool or unitpost.com/components). Wrap the blocks in ONE <Email …> element to set the page in the same call: background-color, body-color, content-width, body-padding, body-radius, body-border-width/-style/-color, font-family, text-color, link-color, preview-text, category. <Section> holds leaf blocks and nested <Section>s (never a <Row>); <Row> holds only <Column>s. Inline <strong>/<em>/<a href> inside <Text>, and <br /> for a line break (a new line in the markup is only a space); no Markdown; no <html>/<body>. Images: hosted https URLs or `/img/{id}` library images only. Don't write the unsubscribe / postal-address footer — marketing templates get it at send. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`.
htmlstringA Code email body (editor `code`): raw HTML kept as-is in one HTML block — the Design editor can show it but not edit it piece by piece. Use it only when the user asks for HTML or brings their own; for a branded email send `tsx` instead. Write simple, email-safe HTML: tables for layout, inline styles, hosted https images. `{{variables}}` fill at send. Pass exactly one of `tsx`, `html` or `text`.
textstringA Simple email body (editor `simple`) — only when the user wants a plain, personal note that reads like it was typed in Gmail. Plain text exactly as you'd type it into Gmail: lines, a blank line between paragraphs (the only spacing), '- ' or '1. ' list items, inline <b>, <i>, <u>, <s>, <a href="…">, <br>, and <span style="color:#hex; background-color:#hex; font-size:13px|18px|24px; font-family:Georgia"> for colour, highlight, size and font; <div style="text-align:center">…</div> around one line to centre it; <img src="/img/{id}" alt="…" width="400"> alone on a line for an image; {{variables}}. Not supported (removed): headings, layout/sections/buttons, block HTML tags (p, div, table, ul), other CSS, and Markdown (stays literal). Sent as a bare mail-client fragment with no layout; marketing templates get a one-line unsubscribe footer at send time. Max 20,000 characters. Pass exactly one of `tsx`, `html` or `text`.
themeobjectPage-level look of a Design template (`tsx`) — the same settings as the `<Email>` element's attributes. Keys you leave out keep the template's current value (a new template starts from the Unitpost brand theme). Not accepted with `html` (style the HTML itself) or `text` (Simple emails use the reader's own style).
preview_textstringInbox preview text: the snippet shown after the subject. A short line that complements the subject. Wins over a `preview-text` on <Email>.
categoryenumtransactional | marketing`marketing` or `transactional`, on any editor. A campaign sends only a `marketing` template; a change is a content edit, so it is refused while a live campaign uses the template. With `tsx` it wins over `<Email category>`.
editorenumsimple | design | codeConvert the template to this editor. Alone (no body field) it converts the CURRENT body: simple → design keeps every line; design → code renders it to HTML (looks the same, no longer editable block by block); code → design rebuilds components where the HTML maps and keeps the rest as HTML; design or code → simple flattens to plain lines. What a conversion changes comes back in `warnings`. With a body field it must name that field's editor (`tsx` = design, `html` = code, `text` = simple). Only when the user asked to switch.
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
subjectrequiredstring | null—
statusrequiredenumdraft | published—
editorenumsimple | design | codeWhich editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body.
kindrequiredenumsimple | designedThe coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`.
preview_textstringInbox preview text: the snippet most inboxes show after the subject. Empty when unset.
categoryenumtransactional | marketing`marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update.
htmlstring | null—
tsxstring | nullA `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows.
textstring | nullA `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows.
warningsstring[]Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user.
created_atrequiredstring—
updated_atrequiredstring—
200401404409422

Delete a template

DELETE/api/v1/email/templates/{id}

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

Permanently delete a template. Emails already sent with it are unaffected, but future sends that reference its id will fail — update any code or campaigns that still point at it first (see List campaigns or Get a template's usage). A template a campaign or live automation still uses, or with queued sends, is a 409. Requires the templates:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404409

Render a template

POST/api/v1/email/templates/{id}/render

POST /email/templates/{id}/render
curl -X POST 'https://www.unitpost.com/api/v1/email/templates/tmpl_123/render' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "template_render",
  "subject": "Welcome to Acme",
  "html": "string",
  "text": "string",
  "missing_variables": [
    "string"
  ]
}

The subject, HTML and text a send of this template would carry, with your footer and branding, without sending or storing anything. Pass variables as a send's template.variables, and contact_id to fill contact fields from that contact. missing_variables lists the variables left without a value: they render as a literal {{token}} here, and a real send refuses them. {{unsubscribe_url}} renders a preview link. A POST only because it takes a body; any other key is a 422. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
variablesobjectValues for the template's {{variables}}, as a send's `template.variables`. One with no value stays a literal {{token}} and is listed in `missing_variables`.
subjectstringRender this subject instead of the template's.
contact_idstringFill contact fields ({{first_name}}, custom fields) from this contact (`con_…`), as a send to them would.
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredstring—
subjectrequiredstring—
htmlrequiredstringThe HTML a send would carry, footer and branding included. `{{unsubscribe_url}}` is a preview link.
textrequiredstring—
missing_variablesrequiredstring[]Variables with no value: they render as a literal {{token}}, and a real send would refuse them.
200400401403404422429

Send a test of a template

POST/api/v1/email/templates/{id}/test-send

POST /email/templates/{id}/test-send
curl -X POST 'https://www.unitpost.com/api/v1/email/templates/tmpl_123/test-send' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "template_test_send",
  "email_id": "email_123",
  "status": "queued",
  "dispatched": false,
  "unresolved_variables": [
    "string"
  ]
}

Render the template with sample variables and send ONE test email to to, exactly as a recipient would get it (footer included). With a verified sending domain it comes from test@<your domain> and may go to anyone; with none it comes from Unitpost's shared test address and only to your workspace's members (403 forbidden otherwise). unresolved_variables lists the ones with no sample value. Rate limited per workspace. Requires the emails:send capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
torequiredstring—
subjectstring—
variablesobject—
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredenumtemplate_test_send—
email_idrequiredstringThe test email (`email_…`); retrieve it like any email.
statusrequiredstringThe test email's status, usually `queued`.
dispatchedrequiredbooleanFalse when this environment records sends without delivering them.
unresolved_variablesrequiredstring[]Variables with no sample value, sent as a literal `{{name}}`.
200401403404422429502

Duplicate a template

POST/api/v1/email/templates/{id}/duplicate

POST /email/templates/{id}/duplicate
curl -X POST 'https://www.unitpost.com/api/v1/email/templates/tmpl_123/duplicate' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "template",
  "id": "id_123",
  "name": "Example",
  "subject": "Welcome to Acme",
  "status": "draft",
  "editor": "simple",
  "kind": "simple",
  "preview_text": "string",
  "category": "transactional",
  "html": "string",
  "tsx": "string",
  "text": "string",
  "warnings": [
    "string"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Copy a template into a new draft, as the dashboard's Duplicate does: its name (with " (copy)", or your name), subject, editor and body carry over; its status, versions and usage don't. Pass an Idempotency-Key so a retry returns the same copy instead of making a second one. Requires the templates:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
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
namestringThe copy's name. Default: the original's with " (copy)".
Response · 201 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
subjectrequiredstring | null—
statusrequiredenumdraft | published—
editorenumsimple | design | codeWhich editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body.
kindrequiredenumsimple | designedThe coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`.
preview_textstringInbox preview text: the snippet most inboxes show after the subject. Empty when unset.
categoryenumtransactional | marketing`marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update.
htmlstring | null—
tsxstring | nullA `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows.
textstring | nullA `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows.
warningsstring[]Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user.
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

Add a template from the gallery

POST/api/v1/email/templates/from-library

POST /email/templates/from-library
curl -X POST 'https://www.unitpost.com/api/v1/email/templates/from-library' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "welcome"
  }'
Response · 201
{
  "object": "template",
  "id": "id_123",
  "name": "Example",
  "subject": "Welcome to Acme",
  "status": "draft",
  "editor": "simple",
  "kind": "simple",
  "preview_text": "string",
  "category": "transactional",
  "html": "string",
  "tsx": "string",
  "text": "string",
  "warnings": [
    "string"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Add one of the gallery's ready-made emails (unitpost.com/templates) to your workspace as a draft Design template, as the gallery's "Use this template" does. slug names it; the ones marked for paid plans answer 403 limit_reached on the free plan. Edit it with Update a template. Pass an Idempotency-Key so a retry returns the same template. 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 body2 fields
FieldTypeDescription
slugrequiredstringThe gallery email to add (unitpost.com/templates): `welcome`, `email-verification`, `one-time-code`, `magic-link`, `password-reset`, `password-changed`, `security-alert`, `team-invite`, `receipt`, `invoice`, `payment-failed`, `subscription-renewal`, `trial-ending`, `usage-alert`, `subscription-cancelled`, `order-confirmation`, `shipping-confirmation`, `delivery-update`, `booking-confirmation`, `appointment-reminder`, `review-request`, `comment-mention`, `support-reply`, `weekly-report`, `document-to-sign`, `export-ready`, `newsletter`, `daily-brief`, `link-roundup`, `content-digest`, `essay-letter`, `founder-letter`, `community-update`, `monthly-product-update`, `july-newsletter`, `product-announcement`, `product-launch-dark`, `app-release`, `pricing-update`, `waitlist-invite`, `flash-sale`, `discount-offer`, `new-collection`, `back-in-stock`, `abandoned-cart`, `birthday-reward`, `holiday-greeting`, `new-listings`, `seasonal-menu`, `rewards-poster`, `travel-guide`, `event-invite`, `conference-invite`, `webinar-recap`, `webinar-invite`, `onboarding-tips`, `re-engagement`, `feedback-survey`, `referral`, `case-study`, `nonprofit-impact`.
namestringThe template's name. Default: the gallery email's.
Response · 201 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
subjectrequiredstring | null—
statusrequiredenumdraft | published—
editorenumsimple | design | codeWhich editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body.
kindrequiredenumsimple | designedThe coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`.
preview_textstringInbox preview text: the snippet most inboxes show after the subject. Empty when unset.
categoryenumtransactional | marketing`marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update.
htmlstring | null—
tsxstring | nullA `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows.
textstring | nullA `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows.
warningsstring[]Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user.
created_atrequiredstring—
updated_atrequiredstring—
201400401403409422

Get a template's usage

GET/api/v1/email/templates/{id}/usage

GET /email/templates/{id}/usage
curl -X GET 'https://www.unitpost.com/api/v1/email/templates/tmpl_123/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "template_usage",
  "template_id": "template_123",
  "campaigns": [
    {
      "id": "id_123",
      "name": "Example",
      "status": "draft",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "campaign_count": 1,
  "sent_count": 1,
  "live_campaigns": [
    {
      "id": "id_123",
      "name": "Example",
      "status": "draft"
    }
  ],
  "live_automations": [
    {
      "id": "id_123",
      "name": "Example",
      "status": "active"
    }
  ],
  "pending_sends": 0,
  "system_locked": false,
  "can_edit_content": false,
  "content_blocked_reason": "string",
  "can_unpublish": false,
  "unpublish_blocked_reason": "string"
}

What uses a template, and whether a change would be accepted now: the campaigns that reference it, its live campaigns and automations, queued sends, and can_edit_content / can_unpublish with the reason when not. Read it before an edit or delete: a content edit is refused while a live campaign renders the template, and a delete while any campaign uses it. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields13 fields
FieldTypeDescription
objectrequiredstring—
template_idrequiredstring—
campaignsrequiredobject[]The campaigns that use it, any status, newest first: the newest 25 (`campaign_count` says how many in all).
campaign_countrequiredintegerHow many campaigns use it in all.
sent_countrequiredintegerEmails sent from it, all time.
live_campaignsrequiredobject[]Scheduled, sending or paused campaigns: they render its current content when they send, so its content is locked.
live_automationsrequiredobject[]Active or paused automations whose published version sends it: it can't be unpublished or deleted.
pending_sendsrequiredintegerQueued or scheduled single sends that render it when they go out.
system_lockedrequiredbooleanA template behind Unitpost's own emails: read-only.
can_edit_contentrequiredbooleanWhether an update to its body, subject or category would be accepted now.
content_blocked_reasonrequiredstring | null—
can_unpublishrequiredbooleanWhether `status: "draft"` would be accepted now.
unpublish_blocked_reasonrequiredstring | null—
200401403404422

List a template's versions

GET/api/v1/email/templates/{id}/versions

GET /email/templates/{id}/versions
curl -X GET 'https://www.unitpost.com/api/v1/email/templates/tmpl_123/versions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "template_version",
      "version": 0,
      "subject": "Welcome to Acme",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

A template's history, newest first: a version is added on every publish and on every content save while it's published. Put one back with Restore a template version. Page with the last row's version as after. Requires the templates:read capability.

Parameters3 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · query1–100 (default 20).
afterinteger · queryThe last `version` of the previous page.
Response · 200 fields4 fields
FieldTypeDescription
objectrequiredstring—
versionrequiredinteger1 is the first publish; every publish, and every content save while published, adds one.
subjectrequiredstring | null—
created_atrequiredstring—
200401403404422

Restore a template version

POST/api/v1/email/templates/{id}/versions/{version}/restore

POST /email/templates/{id}/versions/{version}/restore
curl -X POST 'https://www.unitpost.com/api/v1/email/templates/tmpl_123/versions/3/restore' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "template",
  "id": "id_123",
  "name": "Example",
  "subject": "Welcome to Acme",
  "status": "draft",
  "editor": "simple",
  "kind": "simple",
  "preview_text": "string",
  "category": "transactional",
  "html": "string",
  "tsx": "string",
  "text": "string",
  "warnings": [
    "string"
  ],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Put a version's subject and body back, as the dashboard's version restore does. It is an update, so the update rules apply: a system template, or one a live campaign renders, is a 409 naming why (Get a template's usage says so up front). On a published template the restore adds a new version; history is never rewritten. Takes no body. Requires the templates:write capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
versionrequiredinteger · pathA `version` from the template's history.
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
subjectrequiredstring | null—
statusrequiredenumdraft | published—
editorenumsimple | design | codeWhich editor this template is authored in — and so which body field updates it. `design`: built from @unitpost/email components (the dashboard's Design tab) — update with `tsx`. `simple`: a plain, personal Gmail-style email (the Simple tab) — update with `text`. `code`: raw HTML (the Code tab) — update with `html`. Keep the editor unless the user asked to switch; to switch, send the other body field or `editor` alone to convert the current body.
kindrequiredenumsimple | designedThe coarse kind: `simple` (editor `simple`) or `designed` (editor `design` or `code`). Prefer `editor`.
preview_textstringInbox preview text: the snippet most inboxes show after the subject. Empty when unset.
categoryenumtransactional | marketing`marketing` (a campaign can send it; it gets the unsubscribe footer at send) or `transactional` (receipts, sign-in codes, notifications: no footer, and campaigns refuse it). Change it with `category` on an update.
htmlstring | null—
tsxstring | nullA `design` template's body as @unitpost/email component TSX, wrapped in the `<Email …>` element that carries its theme, preview text and category — edit it and send it back as `tsx`. Null for `simple` and `code` templates. Present on single reads; omitted from list rows.
textstring | nullA `simple` template's body in the Simple `text` format: edit it and send it back as `text`. Null for `design` and `code` templates, and for a Simple email the format can't carry whole (an indented line): change that one in the dashboard, or send a whole new `text`. Present on single reads; omitted from list rows.
warningsstring[]Create or update only: what changed that you didn't write, in plain words — markup the Simple format removed from `text`, `<Email>` attributes or theme values that were ignored, what an `editor` conversion flattened or couldn't keep, a `tsx` write that switched the template's editor. Absent when nothing did. Tell the user.
created_atrequiredstring—
updated_atrequiredstring—
200400401403404409422

Brand kits

Brand Kit profiles (voice, labeled colors, pinned library graphics, core pages) for on-brand template authoring, as Settings → Brand has them. Reading takes templates:read; every write (create, edit, reset, delete, set the default, pin a graphic, import from a website) takes branding:write.

List brand kits

GET/api/v1/brand-kits

GET /brand-kits
curl -X GET 'https://www.unitpost.com/api/v1/brand-kits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "data": [
    {
      "object": "brand_kit",
      "id": "id_123",
      "name": "Example",
      "is_default": false,
      "website_url": "https://example.com",
      "description": "string",
      "tone": "NEUTRAL",
      "voice_notes": "string",
      "industry": "string",
      "core_pages": [
        {
          "url": "https://example.com",
          "title": "string"
        }
      ],
      "extracted": {
        "colors": [
          {
            "hex": "string",
            "label": "string"
          }
        ],
        "logo_urls": [
          "string"
        ],
        "background_urls": [
          "string"
        ],
        "fonts": [
          "string"
        ]
      },
      "graphics": [
        {
          "library_image_id": "library_image_123",
          "image_id": "image_123",
          "path": "string",
          "role": "logo",
          "label": "string"
        }
      ],
      "source": "string",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "default_id": "default_123"
}

Retrieve every Brand Kit profile in the workspace (up to five named profiles). Each profile holds tone, about, voice notes, labeled colors, pinned logo/background library images, and core pages — the primary brand context for on-brand template authoring. Pass ?name= to filter to one profile by display name (case-insensitive). The response includes default_id for the Default profile. Fetch one by id with Retrieve a brand kit. Create, edit and import profiles with branding:write. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
namestring · queryFilter to a single profile by display name (case-insensitive).
Response · 200 fields14 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
is_defaultrequiredboolean—
website_urlrequiredstring | null—
descriptionrequiredstring | null—
tonerequiredenum | null—
voice_notesrequiredstring | null—
industryrequiredstring | null—
core_pagesrequiredobject[]—
extractedrequiredobject—
graphicsrequiredobject[]—
sourcerequiredstring | null—
updated_atrequiredstring | null—
200401403

Create a brand kit

POST/api/v1/brand-kits

POST /brand-kits
curl -X POST 'https://www.unitpost.com/api/v1/brand-kits' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "brand_kit",
  "id": "id_123",
  "name": "Example",
  "is_default": false,
  "website_url": "https://example.com",
  "description": "string",
  "tone": "NEUTRAL",
  "voice_notes": "string",
  "industry": "string",
  "core_pages": [
    {
      "url": "https://example.com",
      "title": "string"
    }
  ],
  "extracted": {
    "colors": [
      {
        "hex": "string",
        "label": "string"
      }
    ],
    "logo_urls": [
      "string"
    ],
    "background_urls": [
      "string"
    ],
    "fonts": [
      "string"
    ]
  },
  "graphics": [
    {
      "library_image_id": "library_image_123",
      "image_id": "image_123",
      "path": "string",
      "role": "logo",
      "label": "string"
    }
  ],
  "source": "string",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Create an empty profile (name, unique in the workspace). The first profile, or one with make_default, becomes the default. At most five profiles (403 limit_reached). Fill it with Update a brand kit or an import. Requires the branding:write capability.

Request body2 fields
FieldTypeDescription
namerequiredstringUnique in the workspace.
make_defaultbooleanMake it the default profile (the first profile always is).
Response · 201 fields14 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
is_defaultrequiredboolean—
website_urlrequiredstring | null—
descriptionrequiredstring | null—
tonerequiredenum | null—
voice_notesrequiredstring | null—
industryrequiredstring | null—
core_pagesrequiredobject[]—
extractedrequiredobject—
graphicsrequiredobject[]—
sourcerequiredstring | null—
updated_atrequiredstring | null—
201400401403409422429

Retrieve a brand kit

GET/api/v1/brand-kits/{id}

GET /brand-kits/{id}
curl -X GET 'https://www.unitpost.com/api/v1/brand-kits/bk_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "brand_kit",
  "id": "id_123",
  "name": "Example",
  "is_default": false,
  "website_url": "https://example.com",
  "description": "string",
  "tone": "NEUTRAL",
  "voice_notes": "string",
  "industry": "string",
  "core_pages": [
    {
      "url": "https://example.com",
      "title": "string"
    }
  ],
  "extracted": {
    "colors": [
      {
        "hex": "string",
        "label": "string"
      }
    ],
    "logo_urls": [
      "string"
    ],
    "background_urls": [
      "string"
    ],
    "fonts": [
      "string"
    ]
  },
  "graphics": [
    {
      "library_image_id": "library_image_123",
      "image_id": "image_123",
      "path": "string",
      "role": "logo",
      "label": "string"
    }
  ],
  "source": "string",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve one Brand Kit profile by id (bk_…), including voice, labeled colors, pinned graphics (library_image_id for /img/{id} in design TSX), and core pages. List every profile with List brand kits. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields14 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
is_defaultrequiredboolean—
website_urlrequiredstring | null—
descriptionrequiredstring | null—
tonerequiredenum | null—
voice_notesrequiredstring | null—
industryrequiredstring | null—
core_pagesrequiredobject[]—
extractedrequiredobject—
graphicsrequiredobject[]—
sourcerequiredstring | null—
updated_atrequiredstring | null—
200401403404

Update a brand kit

PATCH/api/v1/brand-kits/{id}

PATCH /brand-kits/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/brand-kits/bk_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "brand_kit",
  "id": "id_123",
  "name": "Example",
  "is_default": false,
  "website_url": "https://example.com",
  "description": "string",
  "tone": "NEUTRAL",
  "voice_notes": "string",
  "industry": "string",
  "core_pages": [
    {
      "url": "https://example.com",
      "title": "string"
    }
  ],
  "extracted": {
    "colors": [
      {
        "hex": "string",
        "label": "string"
      }
    ],
    "logo_urls": [
      "string"
    ],
    "background_urls": [
      "string"
    ],
    "fonts": [
      "string"
    ]
  },
  "graphics": [
    {
      "library_image_id": "library_image_123",
      "image_id": "image_123",
      "path": "string",
      "role": "logo",
      "label": "string"
    }
  ],
  "source": "string",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Edit a profile: voice, tone, description, industry, website, core pages, the palette and logo candidates (extracted), and the pinned graphics (library images, img_…). Only the fields sent change; a list replaces the list; null or "" clears a text field. sync_visual on the default profile also sets the email branding's accent from these colors. Requires the branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body10 fields
FieldTypeDescription
namestring—
website_urlstring | nullAn https URL; `null` or `""` clears it.
descriptionstring | nullWhat the brand does.
toneenum | null—
voice_notesstring | nullDos and don'ts for writing in this voice.
industrystring | nullThe brand's industry.
core_pagesobject[]Replaces the list.
extractedobjectThe palette, logo and background candidates, fonts. Replaces the set.
graphicsobject[]The pinned library images (`img_…`). Replaces the list.
sync_visualbooleanOn the default profile, also set the email branding's accent from these colors (no change on another profile, or without a usable accent).
Response · 200 fields14 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
is_defaultrequiredboolean—
website_urlrequiredstring | null—
descriptionrequiredstring | null—
tonerequiredenum | null—
voice_notesrequiredstring | null—
industryrequiredstring | null—
core_pagesrequiredobject[]—
extractedrequiredobject—
graphicsrequiredobject[]—
sourcerequiredstring | null—
updated_atrequiredstring | null—
200400401403404409422429

Delete a brand kit

DELETE/api/v1/brand-kits/{id}

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

Delete a profile. When it was the default, the oldest remaining profile becomes the default. The last profile can't be deleted (409): reset it instead. Its pinned images stay in the library. Requires the branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404409422429

Reset a brand kit

POST/api/v1/brand-kits/{id}/reset

POST /brand-kits/{id}/reset
curl -X POST 'https://www.unitpost.com/api/v1/brand-kits/bk_123/reset' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "brand_kit",
  "id": "id_123",
  "name": "Example",
  "is_default": false,
  "website_url": "https://example.com",
  "description": "string",
  "tone": "NEUTRAL",
  "voice_notes": "string",
  "industry": "string",
  "core_pages": [
    {
      "url": "https://example.com",
      "title": "string"
    }
  ],
  "extracted": {
    "colors": [
      {
        "hex": "string",
        "label": "string"
      }
    ],
    "logo_urls": [
      "string"
    ],
    "background_urls": [
      "string"
    ],
    "fonts": [
      "string"
    ]
  },
  "graphics": [
    {
      "library_image_id": "library_image_123",
      "image_id": "image_123",
      "path": "string",
      "role": "logo",
      "label": "string"
    }
  ],
  "source": "string",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Clear a profile's content (voice, colors, graphics, pages) and keep its name and whether it's the default. Takes no body. Requires the branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields14 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
is_defaultrequiredboolean—
website_urlrequiredstring | null—
descriptionrequiredstring | null—
tonerequiredenum | null—
voice_notesrequiredstring | null—
industryrequiredstring | null—
core_pagesrequiredobject[]—
extractedrequiredobject—
graphicsrequiredobject[]—
sourcerequiredstring | null—
updated_atrequiredstring | null—
200400401403404422429

Make a brand kit the default

POST/api/v1/brand-kits/{id}/set-default

POST /brand-kits/{id}/set-default
curl -X POST 'https://www.unitpost.com/api/v1/brand-kits/bk_123/set-default' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "brand_kit",
  "id": "id_123",
  "name": "Example",
  "is_default": false,
  "website_url": "https://example.com",
  "description": "string",
  "tone": "NEUTRAL",
  "voice_notes": "string",
  "industry": "string",
  "core_pages": [
    {
      "url": "https://example.com",
      "title": "string"
    }
  ],
  "extracted": {
    "colors": [
      {
        "hex": "string",
        "label": "string"
      }
    ],
    "logo_urls": [
      "string"
    ],
    "background_urls": [
      "string"
    ],
    "fonts": [
      "string"
    ]
  },
  "graphics": [
    {
      "library_image_id": "library_image_123",
      "image_id": "image_123",
      "path": "string",
      "role": "logo",
      "label": "string"
    }
  ],
  "source": "string",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Make a profile the default: the one agents write with unless told otherwise. Takes no body. Requires the branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields14 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
is_defaultrequiredboolean—
website_urlrequiredstring | null—
descriptionrequiredstring | null—
tonerequiredenum | null—
voice_notesrequiredstring | null—
industryrequiredstring | null—
core_pagesrequiredobject[]—
extractedrequiredobject—
graphicsrequiredobject[]—
sourcerequiredstring | null—
updated_atrequiredstring | null—
200400401403404409422429

Add a graphic to a brand kit

POST/api/v1/brand-kits/{id}/graphics

POST /brand-kits/{id}/graphics
curl -X POST 'https://www.unitpost.com/api/v1/brand-kits/bk_123/graphics' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 201
{
  "object": "brand_kit_graphic",
  "brand_kit": {
    "object": "brand_kit",
    "id": "id_123",
    "name": "Example",
    "is_default": false,
    "website_url": "https://example.com",
    "description": "string",
    "tone": "NEUTRAL",
    "voice_notes": "string",
    "industry": "string",
    "core_pages": [
      {
        "url": "https://example.com",
        "title": "string"
      }
    ],
    "extracted": {
      "colors": [
        {
          "hex": "string",
          "label": "string"
        }
      ],
      "logo_urls": [
        "string"
      ],
      "background_urls": [
        "string"
      ],
      "fonts": [
        "string"
      ]
    },
    "graphics": [
      {
        "library_image_id": "library_image_123",
        "image_id": "image_123",
        "path": "string",
        "role": "logo",
        "label": "string"
      }
    ],
    "source": "string",
    "updated_at": "2026-01-01T00:00:00.000Z"
  },
  "image": {
    "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 a graphic from a public https image url (fetched once, no redirects): it goes into the image library, counted against its storage, and is pinned with its role (default logo). To pin an image already in the library, Update a brand kit with graphics. Requires the branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
urlrequiredstringA public https PNG, JPEG, GIF or WebP (fetched once, no redirects; up to 5 MB).
roleenumlogo | logo_light | logo_dark | mark | background | otherDefault `logo`.
labelstring—
Response · 201 fields3 fields
FieldTypeDescription
objectrequiredstring—
brand_kitrequiredobject—
imagerequiredobject—
201400401403404422429503

Import a brand kit

POST/api/v1/brand-kits/imports

POST /brand-kits/imports
curl -X POST 'https://www.unitpost.com/api/v1/brand-kits/imports' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 202
{
  "object": "brand_import",
  "id": "id_123",
  "status": "pending",
  "review": false,
  "source": {
    "kind": "url",
    "url": "https://example.com"
  },
  "brand_kit_id": "brand_kit_123",
  "proposal": {
    "name": "Example",
    "website_url": "https://example.com",
    "description": "string",
    "tone": "NEUTRAL",
    "voice_notes": "string",
    "industry": "string",
    "core_pages": [
      {
        "url": "https://example.com",
        "title": "string"
      }
    ],
    "extracted": {
      "colors": [
        {
          "hex": "string",
          "label": "string"
        }
      ],
      "logo_urls": [
        "string"
      ],
      "background_urls": [
        "string"
      ],
      "fonts": [
        "string"
      ]
    },
    "memory_facts": [
      {
        "key": "string",
        "content": "string"
      }
    ]
  },
  "warnings": [
    "string"
  ],
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Build a profile from a website (url, or a bare domain) or the brand's own words (text). It runs in the background, usually under a minute (202; follow it with Retrieve a brand kit import). By default the result is applied when it lands: to brand_kit_id, else the default profile, or a new one when the default already has content. With review: true it stops at a proposal (preview_ready) for Accept a brand kit import; one review import is open at a time, and a new one replaces it. Applying an import started here never adds a sending domain (add one with Add a domain). Requires the branding:write capability.

Request body6 fields
FieldTypeDescription
urlstringThe site to read: an https URL or a bare domain (`acme.com`).
textstringOr paste the brand's own words (an about page, a style guide).
website_urlstring | nullWith `text`: the brand's site, for the profile.
brand_kit_idstringThe profile to fill (`bk_…`). Default: the default profile, or a new one when it already has content.
reviewboolean`true` stops at the proposal for you to accept (POST …/accept); default `false` applies it when ready.
sync_visualbooleanAlso set the email branding's accent from the imported colors (the default profile only).
Response · 202 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | running | preview_ready | completed | failed | cancelled`preview_ready`: the proposal waits for an accept (review imports) or is being applied (one-shot); with an `error` on a one-shot import, applying it failed: accept or cancel it.
reviewrequiredbooleanWhether it waits for an accept (false: applied when the crawl lands).
sourcerequiredobject—
brand_kit_idrequiredstring | nullThe profile it fills.
proposalrequiredobject | nullWhat the import found, once ready.
warningsrequiredstring[]—
errorrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
completed_atrequiredstring | null—
202400401403404422429

Retrieve a brand kit import

GET/api/v1/brand-kits/imports/{id}

GET /brand-kits/imports/{id}
curl -X GET 'https://www.unitpost.com/api/v1/brand-kits/imports/bki_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "brand_import",
  "id": "id_123",
  "status": "pending",
  "review": false,
  "source": {
    "kind": "url",
    "url": "https://example.com"
  },
  "brand_kit_id": "brand_kit_123",
  "proposal": {
    "name": "Example",
    "website_url": "https://example.com",
    "description": "string",
    "tone": "NEUTRAL",
    "voice_notes": "string",
    "industry": "string",
    "core_pages": [
      {
        "url": "https://example.com",
        "title": "string"
      }
    ],
    "extracted": {
      "colors": [
        {
          "hex": "string",
          "label": "string"
        }
      ],
      "logo_urls": [
        "string"
      ],
      "background_urls": [
        "string"
      ],
      "fonts": [
        "string"
      ]
    },
    "memory_facts": [
      {
        "key": "string",
        "content": "string"
      }
    ]
  },
  "warnings": [
    "string"
  ],
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

One import: its status, the proposal once it's ready, warnings and any error. Requires the templates:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | running | preview_ready | completed | failed | cancelled`preview_ready`: the proposal waits for an accept (review imports) or is being applied (one-shot); with an `error` on a one-shot import, applying it failed: accept or cancel it.
reviewrequiredbooleanWhether it waits for an accept (false: applied when the crawl lands).
sourcerequiredobject—
brand_kit_idrequiredstring | nullThe profile it fills.
proposalrequiredobject | nullWhat the import found, once ready.
warningsrequiredstring[]—
errorrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
completed_atrequiredstring | null—
200401403404422

Accept a brand kit import

POST/api/v1/brand-kits/imports/{id}/accept

POST /brand-kits/imports/{id}/accept
curl -X POST 'https://www.unitpost.com/api/v1/brand-kits/imports/bki_123/accept' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "brand_import",
  "id": "id_123",
  "status": "pending",
  "review": false,
  "source": {
    "kind": "url",
    "url": "https://example.com"
  },
  "brand_kit_id": "brand_kit_123",
  "proposal": {
    "name": "Example",
    "website_url": "https://example.com",
    "description": "string",
    "tone": "NEUTRAL",
    "voice_notes": "string",
    "industry": "string",
    "core_pages": [
      {
        "url": "https://example.com",
        "title": "string"
      }
    ],
    "extracted": {
      "colors": [
        {
          "hex": "string",
          "label": "string"
        }
      ],
      "logo_urls": [
        "string"
      ],
      "background_urls": [
        "string"
      ],
      "fonts": [
        "string"
      ]
    },
    "memory_facts": [
      {
        "key": "string",
        "content": "string"
      }
    ]
  },
  "warnings": [
    "string"
  ],
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "brand_kit": {
    "object": "brand_kit",
    "id": "id_123",
    "name": "Example",
    "is_default": false,
    "website_url": "https://example.com",
    "description": "string",
    "tone": "NEUTRAL",
    "voice_notes": "string",
    "industry": "string",
    "core_pages": [
      {
        "url": "https://example.com",
        "title": "string"
      }
    ],
    "extracted": {
      "colors": [
        {
          "hex": "string",
          "label": "string"
        }
      ],
      "logo_urls": [
        "string"
      ],
      "background_urls": [
        "string"
      ],
      "fonts": [
        "string"
      ]
    },
    "graphics": [
      {
        "library_image_id": "library_image_123",
        "image_id": "image_123",
        "path": "string",
        "role": "logo",
        "label": "string"
      }
    ],
    "source": "string",
    "updated_at": "2026-01-01T00:00:00.000Z"
  },
  "apply_warnings": [
    "string"
  ]
}

Apply a review import's proposal (preview_ready) to a profile: voice, colors and pages, and its logos and backgrounds brought into the image library and pinned. Without brand_kit_id it fills the profile the import named, else the default, or a new profile when the default has content; the profile takes the name the import found unless you send name. A one-shot import whose automatic apply failed (preview_ready with an error) can be accepted too. The site becomes a sending domain only when the key holds domains:write. To change fields, accept and then Update a brand kit. The body is optional. Requires the branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body3 fields
FieldTypeDescription
brand_kit_idstringApply to this profile instead of the one the import named.
namestringThe profile's name (default: the one the import found).
sync_visualbooleanAlso set the email branding's accent from the imported colors (the default profile only).
Response · 200 fields14 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | running | preview_ready | completed | failed | cancelled`preview_ready`: the proposal waits for an accept (review imports) or is being applied (one-shot); with an `error` on a one-shot import, applying it failed: accept or cancel it.
reviewrequiredbooleanWhether it waits for an accept (false: applied when the crawl lands).
sourcerequiredobject—
brand_kit_idrequiredstring | nullThe profile it fills.
proposalrequiredobject | nullWhat the import found, once ready.
warningsrequiredstring[]—
errorrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
completed_atrequiredstring | null—
brand_kitrequiredobjectThe profile as the accept left it.
apply_warningsrequiredstring[]What the accept couldn't bring in (a logo that wouldn't fetch, the graphics cap, a renamed profile).
200400401403404409422429

Cancel a brand kit import

POST/api/v1/brand-kits/imports/{id}/cancel

POST /brand-kits/imports/{id}/cancel
curl -X POST 'https://www.unitpost.com/api/v1/brand-kits/imports/bki_123/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "brand_import",
  "id": "id_123",
  "status": "pending",
  "review": false,
  "source": {
    "kind": "url",
    "url": "https://example.com"
  },
  "brand_kit_id": "brand_kit_123",
  "proposal": {
    "name": "Example",
    "website_url": "https://example.com",
    "description": "string",
    "tone": "NEUTRAL",
    "voice_notes": "string",
    "industry": "string",
    "core_pages": [
      {
        "url": "https://example.com",
        "title": "string"
      }
    ],
    "extracted": {
      "colors": [
        {
          "hex": "string",
          "label": "string"
        }
      ],
      "logo_urls": [
        "string"
      ],
      "background_urls": [
        "string"
      ],
      "fonts": [
        "string"
      ]
    },
    "memory_facts": [
      {
        "key": "string",
        "content": "string"
      }
    ]
  },
  "warnings": [
    "string"
  ],
  "error": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z"
}

Discard a review import's proposal or stop its crawl, or discard a one-shot import whose automatic apply failed. Takes no body. Requires the branding:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
statusrequiredenumpending | running | preview_ready | completed | failed | cancelled`preview_ready`: the proposal waits for an accept (review imports) or is being applied (one-shot); with an `error` on a one-shot import, applying it failed: accept or cancel it.
reviewrequiredbooleanWhether it waits for an accept (false: applied when the crawl lands).
sourcerequiredobject—
brand_kit_idrequiredstring | nullThe profile it fills.
proposalrequiredobject | nullWhat the import found, once ready.
warningsrequiredstring[]—
errorrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
completed_atrequiredstring | null—
200400401403404409422

Domains

The domains you send from. Add a domain, publish its DNS records, verify it, and manage its tracking and TLS defaults — sending is blocked until the domain verifies.

List domains

GET/api/v1/email/domains

GET /email/domains
curl -X GET 'https://www.unitpost.com/api/v1/email/domains' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "domain",
      "id": "id_123",
      "name": "Example",
      "status": "pending",
      "records": [
        {
          "type": "string",
          "name": "Example",
          "value": "string",
          "priority": 0
        }
      ],
      "dkim_selector": "string",
      "open_tracking": false,
      "click_tracking": false,
      "tls": "opportunistic",
      "tracking_subdomain": "string",
      "tracking_verified_at": "2026-01-01T00:00:00.000Z",
      "capabilities": {
        "sending": "enabled",
        "receiving": "enabled"
      },
      "receiving": {
        "status": "disabled",
        "record": {
          "type": "string",
          "name": "Example",
          "value": "string",
          "priority": 0
        },
        "checks": {
          "mx_found": false,
          "mx_lowest_priority": false,
          "other_mx_found": false
        },
        "checked_at": "2026-01-01T00:00:00.000Z"
      },
      "verified_at": "2026-01-01T00:00:00.000Z",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a list of your sending domains, cursor-paginated, with each domain's verification status. Add a new one with Add a domain, or fetch a single domain (including its DNS records) with Retrieve a domain. Requires the domains: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 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401422

Add a domain

POST/api/v1/email/domains

POST /email/domains
curl -X POST 'https://www.unitpost.com/api/v1/email/domains' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "yourdomain.com"
  }'
Response · 201
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Add a domain you'll send email from. The response includes the DNS records (SPF, DKIM, and so on) to publish with your DNS provider. Once they're published, trigger a check with Verify a domain — sending from the domain is blocked until it verifies. Requires the domains:write capability.

Request body1 field
FieldTypeDescription
namerequiredstring—
Response · 201 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
201401409422

Retrieve a domain

GET/api/v1/email/domains/{id}

GET /email/domains/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/domains/dom_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Retrieve a single sending domain by id, including its current verification status and the DNS records you need to publish. Re-run the DNS check with Verify a domain, or change its tracking/TLS settings with Update a domain. Requires the domains:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401404

Update a domain

PATCH/api/v1/email/domains/{id}

PATCH /email/domains/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/domains/dom_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "click_tracking": true,
    "open_tracking": true
  }'
Response · 200
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Update a domain's sending options: open/click tracking defaults, TLS enforcement, and the tracking subdomain. These act as the domain-level defaults that individual emails and campaigns can override (see Update a campaign). A tracking_subdomain can be set at any time, so you can publish its CNAME along with the domain's other records. It is only checked once the domain is verified, and tracked links switch to it once its CNAME is published and it answers over HTTPS; until then they use the default tracking host. After a change, links keep using the previous subdomain until the new one answers over HTTPS (keep the previous CNAME in place). Changing it is limited to a few times an hour per domain, and to a few new subdomains a day per workspace. **Receiving.** capabilities.receiving: "enabled" receives mail sent to any address at the domain: each message is stored and fires the email.received webhook. The domain must be verified (or degraded), else 409 and nothing in the request is applied. Then publish receiving.record (an MX record at the domain's own name) and call Verify a domain: receiving.status turns verified once the record wins and mail is accepted. An MX record takes ALL mail for the name, so if receiving.checks.other_mx_found is true the name already gets mail elsewhere: receive on a subdomain instead (add it as its own domain). "disabled" stops receiving and is always allowed. Turning it on is limited to a few times an hour per domain; sending "enabled" again while it's on doesn't count. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body5 fields
FieldTypeDescription
open_trackingboolean | null—
click_trackingboolean | null—
tlsenumopportunistic | enforced—
tracking_subdomainstring | null—
capabilitiesobjectTurn receiving on or off: `{ "receiving": "enabled" }` or `{ "receiving": "disabled" }`.
Response · 200 fields16 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
200401403404409422429

Delete a domain

DELETE/api/v1/email/domains/{id}

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

Remove a sending domain from your workspace. Sends that reference an address on this domain will be rejected afterwards, so update your from addresses first. Re-add it any time with Add a domain (you'll need to verify it again). Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401404

List sender addresses

GET/api/v1/email/senders

GET /email/senders
curl -X GET 'https://www.unitpost.com/api/v1/email/senders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "sender",
      "id": "id_123",
      "domain_id": "domain_123",
      "address": "string",
      "display_name": "string",
      "from": "you@yourdomain.com",
      "source": "manual",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Your saved From addresses, as the domain page lists them and the dashboard's From pickers offer them: each a mailbox on one of your domains, with its display name and from, the value to send with. Filter with domain_id. A sender can send once its domain can (see Retrieve a domain). Requires the domains: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).
domain_idstring · queryOnly the senders on this domain.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
200401403422

Add a sender address

POST/api/v1/email/senders

POST /email/senders
curl -X POST 'https://www.unitpost.com/api/v1/email/senders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "address": "hello@yourdomain.com",
    "display_name": "Acme"
  }'
Response · 201
{
  "object": "sender",
  "id": "id_123",
  "domain_id": "domain_123",
  "address": "string",
  "display_name": "string",
  "from": "you@yourdomain.com",
  "source": "manual",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Save a From address on one of your domains, as the domain page's "Add address" does. The domain may still be verifying. A mailbox already saved on that domain is a 409, so a retry never saves it twice. Requires the domains:write capability.

Request body2 fields
FieldTypeDescription
addressrequiredstringThe mailbox to save, on one of your domains (e.g. `hello@mail.acme.com`). Its domain may still be verifying.
display_namestring | nullShown as the sender's name (`Acme Support <hello@…>`).
Response · 201 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
201400401403404409422

Retrieve a sender address

GET/api/v1/email/senders/{id}

GET /email/senders/{id}
curl -X GET 'https://www.unitpost.com/api/v1/email/senders/sndr_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "sender",
  "id": "id_123",
  "domain_id": "domain_123",
  "address": "string",
  "display_name": "string",
  "from": "you@yourdomain.com",
  "source": "manual",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

One saved From address. Requires the domains:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
200401403404422

Update a sender address

PATCH/api/v1/email/senders/{id}

PATCH /email/senders/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/email/senders/sndr_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "display_name": "Acme Support"
  }'
Response · 200
{
  "object": "sender",
  "id": "id_123",
  "domain_id": "domain_123",
  "address": "string",
  "display_name": "string",
  "from": "you@yourdomain.com",
  "source": "manual",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Change a sender's display name, the only field that changes: a different mailbox is a new sender. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
display_namerequiredstring | nullThe new display name; `null` or `""` clears it.
Response · 200 fields9 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
domain_idrequiredstring—
addressrequiredstring`local_part@domain`.
display_namerequiredstring | null—
fromrequiredstringThe From value to send with: `Display Name <address>`, or the address alone.
sourcerequiredenummanual | api`manual` (saved by someone) or `api` (seen on a send through the API).
created_atrequiredstring—
updated_atrequiredstring—
200400401403404422

Delete a sender address

DELETE/api/v1/email/senders/{id}

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

Remove a saved From address from the pickers. Templates and campaigns that send from it keep their From. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403404

Diagnose a domain's DNS

GET/api/v1/email/domains/{id}/diagnose

GET /email/domains/{id}/diagnose
curl -X GET 'https://www.unitpost.com/api/v1/email/domains/dom_123/diagnose' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "domain_diagnosis",
  "domain_id": "domain_123",
  "domain": "string",
  "status": "queued",
  "checked_at": "2026-01-01T00:00:00.000Z",
  "last_checked_at": "2026-01-01T00:00:00.000Z",
  "would_verify": false,
  "zone": "string",
  "nameservers": [
    {
      "host": "string",
      "ips": [
        "string"
      ]
    }
  ],
  "provider": {
    "configured": false,
    "identity_exists": false,
    "dkim_status": "string",
    "mail_from_status": "string",
    "error": "string"
  },
  "records": [
    {}
  ],
  "findings": [
    {
      "code": "string",
      "severity": "blocking",
      "title": "string",
      "detail": "string",
      "fix": "string"
    }
  ]
}

Explain why a domain is not verified, or what could break it. Every authoritative nameserver is asked about every expected record, the email provider's view of the identity is read, and findings list what is wrong, most serious first, each with the concrete fix. Read-only: it never changes the domain; Verify a domain does. Shares verify's per-workspace DNS rate limit. Requires the domains:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields12 fields
FieldTypeDescription
objectrequiredenumdomain_diagnosis—
domain_idrequiredstring—
domainrequiredstring—
statusrequiredstringThe domain's stored status, next to the live diagnosis.
checked_atrequiredstring—
last_checked_atstringThe last verify check, which this call does not change.
would_verifyrequiredbooleanWhether a verify run now would mark the domain verified.
zonestringThe zone whose nameservers were asked; null when none was found.
nameserversobject[]—
providerobjectThe email provider's view of the sending identity.
recordsrequiredobject[]Every expected record, with each nameserver's answer and a `verdict` (`ok`, `partial`, `wrong`, `missing`, `unknown`).
findingsrequiredobject[]What is wrong, most serious first, each with the concrete `fix`.
200401403404429502

Verify a domain

POST/api/v1/email/domains/{id}/verify

POST /email/domains/{id}/verify
curl -X POST 'https://www.unitpost.com/api/v1/email/domains/dom_123/verify' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "domain",
  "id": "id_123",
  "name": "Example",
  "status": "pending",
  "records": [
    {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    }
  ],
  "dkim_selector": "string",
  "open_tracking": false,
  "click_tracking": false,
  "tls": "opportunistic",
  "tracking_subdomain": "string",
  "tracking_verified_at": "2026-01-01T00:00:00.000Z",
  "capabilities": {
    "sending": "enabled",
    "receiving": "enabled"
  },
  "receiving": {
    "status": "disabled",
    "record": {
      "type": "string",
      "name": "Example",
      "value": "string",
      "priority": 0
    },
    "checks": {
      "mx_found": false,
      "mx_lowest_priority": false,
      "other_mx_found": false
    },
    "checked_at": "2026-01-01T00:00:00.000Z"
  },
  "verified_at": "2026-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "checks": [
    "string"
  ]
}

Run an on-demand DNS check and advance the domain's verification status. The response includes per-record checks so you can see exactly which DNS records are still missing or wrong. checks.mx and checks.spf are true once the record is correct on your nameservers; checks.dkim also needs the email provider to confirm the key. The domain is verified when all three are true. Get the records to publish from Retrieve a domain. Verification also re-runs periodically in the background. If another workspace also added this domain, yours verifies only once the domain's sending identity is yours: your DKIM record is live and theirs is gone on two checks at least 10 minutes apart, or their domain is deleted. While they have it verified, this returns 409 once all your records are live, and nothing is written. With receiving on (capabilities.receiving), it also checks the receiving MX record and reports it in receiving. Requires the domains:write capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields17 fields
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
statusrequiredenumpending | verifying | verified | degraded | failed—
recordsrequiredobject[] | null—
dkim_selectorrequiredstring | null—
open_trackingrequiredboolean | null—
click_trackingrequiredboolean | null—
tlsrequiredenumopportunistic | enforced—
tracking_subdomainrequiredstring | null—
tracking_verified_atrequiredstring | nullWhen tracked links and open pixels started using the custom tracking host (`tracking_subdomain`). Non-null only while sends actually use it: the domain is verified (or degraded) and the host's last check proved it answers over HTTPS. Otherwise null, and links use the default tracking host. A host that stops answering, or a domain that's no longer verified, goes back to null.
capabilitiesrequiredobject—
receivingrequiredobjectReceiving setup: the MX record to publish and the last check of it.
verified_atrequiredstring | null—
created_atrequiredstring—
updated_atrequiredstring—
checksobject[]—
200401404409502

Search docs and guides

Search the docs and product guides.