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.
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" }]
}'import { Mail } from "@productcraft/mail";
// Reads PRODUCTCRAFT_API_KEY from the environment. A workspace key
// finds its own workspace; pass { workspaceId } to skip that lookup.
const mail = new Mail();
const email = await mail.emails.send(
{
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" }],
},
// Optional: the SDK sends a generated key on every write.
{ idempotencyKey: "order-1234-shipped" },
);
const sent = await mail.emails.retrieve(email.id);
console.log(sent.last_event);{ "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
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.
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.
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
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"
}
}'import { Mail } from "@productcraft/mail";
// Reads PRODUCTCRAFT_API_KEY from the environment. A workspace key
// finds its own workspace; pass { workspaceId } to skip that lookup.
const mail = new Mail();
const accepted = await mail.templates.send(
"welcome",
{
from: "noreply@acme.com",
to: "ada@example.com",
data: {
name: "Ada",
product: "Acme",
startUrl: "https://app.acme.com/onboarding",
},
},
// The SDK generates an Idempotency-Key and reuses it on retries.
// Pass your own to dedupe across processes: a replay returns the
// original response with Idempotent-Replay: true for 24 h.
{ idempotencyKey: "welcome-2026-05-22-ada" },
);
console.log(accepted.id);{
"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;messagelists each field - 400
TEMPLATE_DATA_INVALID—datafails the template's variable schema;details.errorslists 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— thefromdomain is not a verified sending domain of this workspace (details.reason:not_registeredornot_verified) - 422
RECIPIENT_SUPPRESSED,TEMPLATE_RENDER_FAILED,INVALID_FROM_ADDRESS— recipient on the suppression list, render failure, or unparseablefrom - 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.
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" } }
]
}'{
"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.
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
scheduleduntil then, and you getemail.scheduled. Move it withPATCH /emails/:idand a newscheduled_at, or cancel it withPOST /emails/:id/cancel(each recipient then readscanceledand you getemail.canceled). Both answer 409MAIL_EMAIL_NOT_SCHEDULEDonce 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, thendelivered(email.sent,email.delivered).bounced@test.productcraft.co:sent, thenbouncedwith a permanent 5.1.1 bounce (email.bounced).complained@test.productcraft.co: delivered, thencomplained(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.