Mail guides
03 · First send

Send your first transactional email.

With a verified domain (Chapter 2), one API call sends your own HTML. Or author a template once and send it by name. No mailbox needed — mailboxes are for receiving.


1

Send an email

POST /emails sends your own html and/or text as-is. Leave out text and the plain-text part is derived from the HTML. Send to one address or up to 50 across to, cc and bcc. Use reply_to for replies, headers for custom headers (X-*, List-*, In-Reply-To, References) and tags to label the send.

POST /workspaces/:ws/emails
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/emails \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: order-1234-shipped' \
  -d '{
    "from": "Acme <orders@mail.acme.com>",
    "to": ["ada@example.com"],
    "cc": "finance@acme.com",
    "reply_to": "support@acme.com",
    "subject": "Your order has shipped",
    "html": "<p>Hi Ada, your order is on its way.</p>",
    "headers": { "X-Entity-Ref-ID": "order-1234" },
    "tags": [{ "name": "category", "value": "shipping" }]
  }'
202 Accepted
{ "id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05" }

Each recipient gets its own copy. Every copy shows the same To and Cc headers, and no header names a bcc recipient. Each recipient also has its own message in GET /messages and its own delivery status. GET /emails/{id} returns the whole send: its recipients, its tags, and last_event, which is the worst status across the recipients. GET /emails?tag[category]=shipping finds sends by tag. Each recipient counts as one send against the workspace limits.

A recipient on your suppression list is left out: it gets a message with status suppressed, and the email is still accepted. To send a saved template here, pass "template": { "name": "welcome", "data": { … } } instead of html/text. POST /emails/batch takes up to 100 emails, and each row gets its own status.


2

Author a template

POST /workspaces/:ws/templates
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/templates \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "name": "welcome",
    "subject": "Welcome to {{product}}, {{name}}!",
    "body_html": "<h1>Hi {{name}},</h1><p>Thanks for signing up for {{product}}. Get started at {{startUrl}}.</p>",
    "body_text": "Hi {{name}}, thanks for signing up for {{product}}. Get started: {{startUrl}}",
    "tags": ["onboarding"]
  }'

name is the lookup key — lowercase letters, digits, _, -. Posting the same name again overwrites (the endpoint is an upsert). body_text is optional — Mail derives a plain-text body from the HTML if you omit it.

Name variables in camelCase ({{startUrl}}, not {{start_url}}). Keys inside data are normalized on the wire — start_url arrives as startUrl, so a snake_case variable never receives its value.


3

Preview the rendered output

Before sending to a real recipient, render the template with sample data and inspect the output. Pure validation; doesn't dispatch anything.

POST /workspaces/:ws/templates/:name/render
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/templates/welcome/render \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "data": {
      "name": "Ada",
      "product": "Acme",
      "startUrl": "https://app.acme.com/onboarding"
    }
  }'
{
  "subject": "Welcome to Acme, Ada!",
  "html": "<!doctype html>\n<html>\n<head>...</head>\n<body ...><h1>Hi Ada,</h1><p>Thanks for signing up for Acme. Get started at https://app.acme.com/onboarding.</p></body></html>",
  "text": "Hi Ada, thanks for signing up for Acme. Get started: https://app.acme.com/onboarding"
}

The html comes back wrapped in a dark-mode-safe document head — that's what actually ships. Missing variables render as empty strings (Handlebars default), not errors — eyeball the preview.


4

Send to a test recipient

The test-send endpoint targets one address with the template fully rendered — for “does this actually look right in Gmail” checks. It bypasses the suppression list and rate limits, prefixes the subject with [TEST], and renders unsupplied variables as [varname] placeholders.

POST /workspaces/:ws/templates/:name/test-send
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/templates/welcome/test-send \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "from": "noreply@acme.com",
    "to": "yourself@acme.com",
    "data": { "name": "Ada", "product": "Acme", "startUrl": "https://..." }
  }'

from must be an address on a verified workspace domain — same rule as a production send.


5

Production send

POST /workspaces/:ws/templates/:name/send
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/templates/welcome/send \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: welcome-2026-05-22-ada' \
  -d '{
    "from": "noreply@acme.com",
    "to": "ada@example.com",
    "data": {
      "name": "Ada",
      "product": "Acme",
      "startUrl": "https://app.acme.com/onboarding"
    }
  }'
202 Accepted
{
  "id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05",
  "email_id": "4f8b2c1e-9a3d-4e57-b6f0-2d1c8e7a9b05",
  "accepted": true,
  "from": "noreply@acme.com",
  "to": "ada@example.com",
  "subject": "Welcome to Acme, Ada!"
}

You can pass a top-level subject in the body to override the template's subject. A template send takes the same to array, cc, bcc, reply_to, headers and tags as POST /emails. The send is asynchronous — the 202 confirms queued for delivery, not delivered to inbox. The webhook (Chapter 5) and the message log (Chapter 6) are how you learn what actually happened.

Pre-flight failures (immediate, nothing queued). Every error body is { statusCode, message, code, details? }. Branch on code, not on the status or the message:

  • 400 VALIDATION_ERROR — the request body is malformed; message lists each field
  • 400 TEMPLATE_DATA_INVALID — data fails the template's variable schema; details.errors lists each variable
  • 403 FORBIDDEN / SERVICE_NOT_ENABLED — the key lacks the permission, or Mail is off for the workspace
  • 404 TEMPLATE_NOT_FOUND — template name doesn't exist
  • 409 IDEMPOTENCY_KEY_REUSE — same idempotency key reused with a different body
  • 422 from_domain_not_verified — the from domain is not a verified sending domain of this workspace (details.reason: not_registered or not_verified)
  • 422 RECIPIENT_SUPPRESSED, TEMPLATE_RENDER_FAILED, INVALID_FROM_ADDRESS — recipient on the suppression list, render failure, or unparseable from
  • 429 RATE_LIMITED — slow down and retry

Surface the message from the error body in your operator UI so config errors don't silently swallow sends.


6

Batch send

For sending one template to many recipients with per-recipient data, use the batch endpoint. Each row is processed independently; partial failures don't abort the batch.

POST /workspaces/:ws/templates/:name/send-batch
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/templates/order-receipt/send-batch \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "messages": [
      { "from": "billing@acme.com", "to": "ada@example.com",  "data": { "name": "Ada",  "total": "$29" } },
      { "from": "billing@acme.com", "to": "alan@example.com", "data": { "name": "Alan", "total": "$49" } }
    ]
  }'
200 OK
{
  "data": [
    { "index": 0, "id": "6f0c...", "status": "accepted" },
    { "index": 1, "status": "rejected", "error": { "code": "INVALID_INPUT", "message": "Recipient \"alan@example.com\" is on this workspace's suppression list" } }
  ],
  "summary": { "accepted": 1, "rejected": 1 }
}

Accepted rows carry the outbound message id; rejected rows carry an error. Rows can also take subject and idempotency_key per message; an Idempotency-Key header makes the whole request retry-safe (use a value that differs from every row key). Hard limit: 100 messages per call (400 above that) — chunk client-side for larger blasts. An unverified from domain fails the whole batch upfront with a 422.


7

Send later

Add scheduled_at to POST /emails, a batch row, or POST /templates/:name/send. Give an ISO 8601 time with an offset, or one of in 10 minutes, in 2 hours, in 1 day and tomorrow at 9am (UTC). It has to be between 1 minute and 7 days away.

POST /workspaces/:ws/emails
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/emails \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "from": "Acme <hello@mail.acme.com>",
    "to": "ada@example.com",
    "subject": "Your trial ends tomorrow",
    "html": "<p>Your trial ends tomorrow.</p>",
    "scheduled_at": "2026-11-18T09:00:00+01:00"
  }'

# → { "id": "4f8b2c1e-…", "scheduled_at": "2026-11-18T08:00:00.000Z" }
  • Checked now: the content, the template and its data, the From domain and any attachments. A problem is an error straight away, not a failure later.
  • Done when it goes out: rendering (a template you edit in the meantime is used), the suppression list, and the send limits. A send over the limits waits a minute and tries again; it is never dropped.
  • Every recipient's message reads scheduled until then, and you get email.scheduled. Move it with PATCH /emails/:id and a new scheduled_at, or cancel it with POST /emails/:id/cancel (each recipient then reads canceled and you get email.canceled). Both answer 409 MAIL_EMAIL_NOT_SCHEDULED once it has gone out. The console shows the same two buttons on the email's page.

8

Test addresses

To try your integration and your webhook handlers without a real mailbox, send to one of these. Mail runs the whole pipeline, and the Amazon SES mailbox simulator answers in place of a real server, so your sending reputation is never touched.

  • delivered@test.productcraft.co: sent, then delivered (email.sent, email.delivered).
  • bounced@test.productcraft.co: sent, then bounced with a permanent 5.1.1 bounce (email.bounced).
  • complained@test.productcraft.co: delivered, then complained (email.complained).
  • suppressed@test.productcraft.co: refused as if it were on your suppression list (suppressed, email.suppressed); nothing is sent.

Add a label to tell your tests apart: delivered+signup-42@test.productcraft.co (not on suppressed@). Test mail counts against your send limits, is marked “Test address” in the message log (is_test in the API), stays out of your deliverability verdict and metrics, and a simulated bounce or complaint never adds anyone to your suppression list. Nothing can be delivered to test.productcraft.co for real: the domain accepts no mail.