Emails

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

Search docs and guides

Search the docs and product guides.