--- title: "Emails" description: "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." url: https://www.unitpost.com/docs/api/emails section: API reference updated: 2026-07-31 --- # Emails ## 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. Full schemas: [OpenAPI 3.1](https://www.unitpost.com/api/v1/openapi.json). HTML reference: https://www.unitpost.com/docs/api/emails. ## Operations ### `GET /api/v1/email` List sent emails 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`, `campaign_id`, `batch_id`, and `created_after`/`created_before` filters. Use an email's `id` with [Retrieve an email](#get-email-id) to read its full record, or [Cancel or reschedule an email](#patch-email-id) to change a scheduled send. For aggregate deliverability numbers over a window, see [Email deliverability stats](#get-email-stats). Requires the `emails:read` capability. ### `POST /api/v1/email` Send or schedule an email Send a single transactional email — now, or at a future time by passing `scheduled_at`. Provide the content inline as `html`/`text`, or reference a saved template with `template` (create one with [Create a template](#post-email-templates)). 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](#get-email-id), change a scheduled send with [Cancel or reschedule an email](#patch-email-id), or send many at once with [Send a batch of emails](#post-email-batch). Requires the `emails:send` capability. ### `POST /api/v1/email/batch` Send a batch of emails 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. 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](#get-email-batches-id) and stop the rest of it with [Cancel a batch](#post-email-batches-id-cancel). To send one email, use [Send or schedule an email](#post-email). Requires the `emails:send` capability. ### `GET /api/v1/email/batches/{id}` Retrieve a batch 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](#post-email-batch), or stop its remaining messages with [Cancel a batch](#post-email-batches-id-cancel). Requires the `emails:read` capability. ### `POST /api/v1/email/batches/{id}/cancel` Cancel a batch 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](#get-email-batches-id). Requires the `emails:send` capability. ### `GET /api/v1/email/{id}` Retrieve an email 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](#get-email). To change a scheduled or queued email, use [Cancel or reschedule an email](#patch-email-id). Requires the `emails:read` capability. ### `PATCH /api/v1/email/{id}` Cancel or reschedule an email 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](#get-email-id). Requires the `emails:send` capability. ### `GET /api/v1/email/stats` Email deliverability stats 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. Control the window with the `days` parameter (1–365, default 30). For the individual emails behind these numbers, see [List sent emails](#get-email). Requires the `emails:read` capability. ## Related - [Inbound emails](https://www.unitpost.com/docs/api/inbound-emails): Read email your receiving-enabled domains have received — list messages, retrieve full bodies, and download attachments via short-lived signed URLs. - [Contacts](https://www.unitpost.com/docs/api/contacts): Manage the people you email. Create and update contacts one at a time or import thousands in the background, with standard and custom field values that templates can reference as variables. - [Contact fields](https://www.unitpost.com/docs/api/contact-fields): Define the typed custom attributes (text, number, date, …) your contacts carry — usable in templates as per-recipient variables.