Mail API reference

Mail API · Emails

post/v1/workspaces/{workspace_id}/emailsAuth

Send an email

Send your own `html` and/or `text`, or a saved `template`, to up to 50 recipients across `to`, `cc` and `bcc`, with `reply_to`, custom `headers` and `tags`. Every recipient gets its own copy (its own message in `GET /messages`, suppression check and delivery status) showing the same `To` and `Cc` headers; `bcc` recipients appear in no header. A recipient on the suppression list (or unsubscribed, for a template with an unsubscribe link) is left out with a `suppressed` message, and the email is still accepted. Counts one send per recipient against the workspace limits. Pass an `Idempotency-Key` header to make retries safe.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

Opaque client-generated string (1–256 chars, `[A-Za-z0-9._:-]`) used to deduplicate retries within a 24h window. A retry with the same key and body returns the original response with `Idempotent-Replay: true`.

Request body

from*string

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`).

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

to*object

Recipient: one address, or an array. At most 50 distinct recipients across `to`, `cc` and `bcc` (400 `RECIPIENT_LIMIT`). Each recipient gets its own copy, with its own suppression check, message (`GET /messages`) and delivery status, showing the full `To` and `Cc` lists.

Example: ["success@simulator.amazonses.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"

subjectstring

Subject line. Required with `html`/`text`; with a `template` it overrides the template's subject.

Example: "Your order has shipped"

htmlstring

HTML body, sent exactly as given (no templating). With no `text`, the plain-text part is derived from it.

Example: "<p>Your order has shipped.</p>"

textstring

Plain-text body, sent exactly as given.

Example: "Your order has shipped."

templateobject

Send a saved template instead of `html`/`text` (400 `EMAIL_CONTENT_CONFLICT` with both, or with neither).

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"}]

Response · 202 Accepted; queued for delivery.

id*string · uuid

The email's id. Pass it to `GET /emails/{id}`; it is also the id of the first recipient's message (`GET /messages/{id}`), and webhook events of every recipient carry their own message id as `email_id`.

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

Example

Request

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

{
  "from": "Acme <hello@mail.acme.com>",
  "to": [
    "success@simulator.amazonses.com"
  ],
  "cc": [
    "finance@example.com"
  ],
  "bcc": [
    "audit@example.com"
  ],
  "reply_to": "support@acme.com",
  "subject": "Your order has shipped",
  "html": "<p>Your order has shipped.</p>",
  "text": "Your order has shipped.",
  "template": {},
  "headers": {
    "x-entity-ref-id": "order-1234"
  },
  "tags": [
    {
      "name": "category",
      "value": "confirm_email"
    }
  ]
}

Response

{
  "id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05"
}