Mail API reference

Mail API · Templates

post/v1/workspaces/{workspace_id}/templates/{name}/sendAuth

Send a template-rendered message. Pass an `Idempotency-Key` header (1..256 chars, [A-Za-z0-9._:-]) to make retries safe — replays return the original response with `Idempotent-Replay: true` for 24h. Same key + different request body returns 409 IDEMPOTENCY_KEY_REUSE.

Path parameters

workspace_id*string · uuid

Id of the workspace.

name*string

Name of the template.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window.

Request body

data*object

Data to render into the template. Keys are your variable names and are kept exactly as sent.

Example: {"name":"Alice","order_id":"ord_123"}

fromstring

Sender. Either a bare address (`hello@acme.com`) or a display name plus the address in angle brackets (`Acme <hello@acme.com>`; quote a name that contains a comma: `"Acme, Inc." <hello@acme.com>`). The display name is at most 200 characters. The address's domain must itself be an active (verified) sending domain of the workspace; a verified subdomain does not cover its parent (with only `mail.acme.com` verified, `hello@acme.com` is refused with 422 `from_domain_not_verified`). Optional: omit it to send from the workspace default sender (`GET /v1/workspaces/{id}/sending-defaults`); with no default set the send is refused with 422 `no_default_sender`.

Example: "Acme <hello@acme.com>"

to*object

Recipient: one address, or an array of up to 50 (tasks/mail-api/002). Each recipient gets its own copy (its own suppression check, message row and delivery status) showing the full `To` list. One address is the historical shape and behaves exactly as before.

Example: "user@example.com"

ccobject

Cc recipients: one address or an array. Shown in the `Cc` header to every recipient.

Example: ["finance@example.com"]

bccobject

Bcc recipients: one address or an array. Each gets the message; no header names them.

Example: ["audit@example.com"]

reply_toobject

Reply-To address(es): one address or an array. This is the only way to set `Reply-To`.

Example: "support@acme.com"

headersobject

Custom headers, as a map of header name to value, kept exactly as sent. Allowed: `X-*` (except `X-SES-*`), `List-Unsubscribe`, `List-Unsubscribe-Post`, `List-Id`, `In-Reply-To` and `References`; at most 50, values up to 998 characters with no line breaks. Any other header (`From`, `To`, `Cc`, `Bcc`, `Subject`, `Date`, `Message-ID`, `DKIM-Signature`, `Return-Path`, `Reply-To`, …) is a 400 `MAIL_HEADER_NOT_ALLOWED`: use the matching field (`reply_to` for `Reply-To`).

Example: {"x-entity-ref-id":"order-1234"}

tagsarray

Up to 10 `{ name, value }` labels, stored on every message of the send. Filter sends by them with `GET /emails?tag[name]=value`.

Example: [{"name":"category","value":"confirm_email"}]

subjectstring

Subject override (optional; uses template subject otherwise)

topic_idstring · uuid

Send as mail on this topic (tasks/mail-api/016). The recipient must be a contact subscribed to the topic: one who opted in, or, for a topic whose `default_subscription` is `opt_in`, one with a recorded consent who has not opted out. Anyone else is refused with 422 `RECIPIENT_SUPPRESSED` and `details.reason` `unsubscribe` (opted out of the topic or unsubscribed from everything) or `no_consent` (never opted in, or not a contact), and an `email.suppressed` event. A topic send carries a one-click unsubscribe link (`{{{unsubscribe_url}}}` in the template) and the `List-Unsubscribe` + `List-Unsubscribe-Post` headers, and goes out on the separate marketing stream. A `topic_id` that is not a topic of this workspace is a 422 `TOPIC_NOT_FOUND`.

Example: "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c"

attachmentsarray

Files to attach, and inline images (`content_id`). Up to 20 files and 10 MB in total after decoding (400 `MAIL_ATTACHMENT_TOO_LARGE`). Stored for the message log's 30 days and downloadable from `GET /emails/{id}/attachments/{position}`. We do not scan for viruses: executable files are refused by name, declared type and content (400 `MAIL_ATTACHMENT_TYPE_BLOCKED`), and archives are passed through unopened. Not accepted by the batch routes (400 `MAIL_ATTACHMENTS_NOT_IN_BATCH`). Every `content_id` must be referenced as `cid:<id>` in the rendered html.

trackingobject

Open and click tracking for this email, overriding the From domain's `open_tracking` / `click_tracking` field by field. Off by default. Opens add a 1x1 image; clicks send each http(s) link in the html through `track.productcraft.co`, which redirects to the original URL and fires `email.clicked`. The unsubscribe link, `mailto:`/`tel:` links and any `<a data-pc-track="false">` are left alone; the plain-text part is never rewritten. Apple Mail Privacy Protection and link scanners inflate the numbers: events carry `proxy` and `bot`.

scheduled_atstring

Send later instead of now: ISO 8601 with an offset (`2026-11-18T09:00:00+01:00`), or `in 10 minutes`, `in 2 hours`, `in 1 day`, `tomorrow at 9am` (UTC). Between 1 minute and 7 days ahead (400 `MAIL_SCHEDULE_OUT_OF_RANGE`; anything else 400 `MAIL_SCHEDULE_UNPARSEABLE`). The send is checked now (content, From domain, attachments) and recorded `scheduled` with an `email.scheduled` event; it is rendered, checked against the suppression list and counted against the send limits when it goes out (a send over the limits waits a minute and tries again). Cancel with `POST /emails/{id}/cancel`, move with `PATCH /emails/{id}`.

Example: "in 2 hours"

Response · 202 Send accepted; queued for delivery.

id*string · uuid

Id of the stored message (`outbound_message.id`). Pass it to `GET /messages/{id}` and match it against `data.email_id` on webhook events. Null only if the message log write failed; the send itself was still queued.

Example: "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05"

accepted*boolean

Always true on a 202.

Example: true

from*string

The From field as sent, display name included.

Example: "Acme <hello@acme.com>"

to*object

The `to` field as sent: one address, or the array.

Example: "user@example.com"

subject*string

The rendered subject line.

email_id*string · uuid

The email this send created (`GET /emails/{id}`): one email, one message per recipient. Equals `id` for a send whose first message was recorded.

Example: "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05"

scheduled_atstring · date-time

Only for a send with `scheduled_at` (tasks/mail-api/004): when it goes out.

Example: "2026-11-18T09:00:00.000Z"

Example

Request

POST https://api.mail.productcraft.co/v1/workspaces/{workspace_id}/templates/{name}/send
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "data": {
    "name": "Alice",
    "order_id": "ord_123"
  },
  "from": "Acme <hello@acme.com>",
  "to": "user@example.com",
  "cc": [
    "finance@example.com"
  ],
  "bcc": [
    "audit@example.com"
  ],
  "reply_to": "support@acme.com",
  "headers": {
    "x-entity-ref-id": "order-1234"
  },
  "tags": [
    {
      "name": "category",
      "value": "confirm_email"
    }
  ],
  "subject": "string",
  "topic_id": "3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c",
  "attachments": [
    {
      "filename": "invoice-1234.pdf",
      "content": "JVBERi0xLjcKJcfsj6IKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c+PgplbmRvYmoK",
      "path": "https://files.acme.com/invoices/1234.pdf",
      "content_type": "application/pdf",
      "content_id": "logo"
    }
  ],
  "tracking": {},
  "scheduled_at": "in 2 hours"
}

Response

{
  "id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05",
  "accepted": true,
  "from": "Acme <hello@acme.com>",
  "to": "user@example.com",
  "subject": "string",
  "email_id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05",
  "scheduled_at": "2026-11-18T09:00:00.000Z"
}