Send or schedule an email

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

Search docs and guides

Search the docs and product guides.