/v1/workspaces/{workspace_id}/emailsAuthSend 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. `attachments` adds files and inline images (`content_id`, referenced as `cid:` in the html): up to 20 files, 10 MB in total, given as base64 `content` or an https `path` we fetch; executables are refused.
Path parameters
workspace_id*string · uuidId of the workspace.
Headers
Idempotency-KeystringOpaque 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*stringSender. 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*objectRecipient: 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. To test without a real mailbox, send to `delivered@`, `bounced@`, `complained@` or `suppressed@test.productcraft.co` (`+label` allowed on the first three).
Example: ["success@simulator.amazonses.com"]
ccobjectCc recipients: one address or an array. Shown in the `Cc` header to every recipient.
Example: ["finance@example.com"]
bccobjectBcc recipients: one address or an array. Each gets the message; no header names them.
Example: ["audit@example.com"]
reply_toobjectReply-To address(es): one address or an array. This is the only way to set `Reply-To`.
Example: "support@acme.com"
subjectstringSubject line. Required with `html`/`text`; with a `template` it overrides the template's subject.
Example: "Your order has shipped"
htmlstringHTML 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>"
textstringPlain-text body, sent exactly as given.
Example: "Your order has shipped."
templateobjectSend a saved template instead of `html`/`text` (400 `EMAIL_CONTENT_CONFLICT` with both, or with neither).
headersobjectCustom 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"}
tagsarrayUp 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"}]
attachmentsarrayFiles 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`).
trackingobjectOpen 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_atstringSend 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 Accepted; queued for delivery.
id*string · uuidThe 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"
scheduled_atstring · date-timeOnly for a send with `scheduled_at`: when it goes out.
Example: "2026-11-18T09:00:00.000Z"
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"
}
],
"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"
}import { Mail } from "@productcraft/mail";
// Reads PRODUCTCRAFT_API_KEY from the environment
const mail = new Mail();
const result = await mail.emails.send({
from: "Acme <hello@mail.acme.com>",
html: "<p>Your order has shipped.</p>",
subject: "Your order has shipped",
to: ["success@simulator.amazonses.com"],
});mail.emails.send(params, options?): Mail.EmailSendResponse
Response
{
"id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05",
"scheduled_at": "2026-11-18T09:00:00.000Z"
}