Mail guides
05 · Deliverability

Land in the inbox. Stay there.

Bounce handling, complaint handling, the suppression list, webhook config, and the hygiene practices that keep your sender reputation healthy.


1

The suppression list

Workspace-scoped. Hard wall — once an address is on it, production sends to it fail with a 422 regardless of sender or template (only test-sends bypass it). Goal: never send to an address that has bounced or complained, both for the recipient's benefit and for your sender reputation.

Entries land on the list:

  • Automatically on hard bounce (mailbox doesn't exist, domain rejects) reported back by your delivery route.
  • Automatically on complaint (recipient hits “Mark as spam”) — treated as a permanent suppression.
  • Manually via POST /workspaces/:ws/suppression (your unsubscribe form posts here).

Soft bounces (mailbox full, temporary deferral) are deliberately not suppressed — your provider already retries them, and suppressing a recipient over a transient hiccup hurts more than it helps.


2

Listing

GET /workspaces/:ws/suppression
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/suppression \
  -H 'authorization: Bearer pcft_live_...'
{
  "data": [
    {
      "id":           "3b187ca9-...",
      "workspace_id": "24fab978-...",
      "email":        "bounced@example.com",
      "reason":       "hard bounce (550: user unknown)",
      "source":       "bounce",
      "added_at":     "2026-04-12T..."
    }
  ]
}

Most-recent first, capped at 500 rows; no filter or pagination parameters. source is one of manual / bounce / complaint; reason is free text.


3

Manual add (unsubscribe)

When a recipient hits unsubscribe on your form, POST to the suppression list. Idempotent upsert — re-adding an address updates its reason and timestamp instead of creating a duplicate row (you get a 201 either way).

POST /workspaces/:ws/suppression
curl https://api.mail.productcraft.co/v1/workspaces/<ws>/suppression \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -d '{
    "email":  "userwhowantsout@example.com",
    "reason": "unsubscribed via preferences page"
  }'

reason is optional free text (≤255 chars); manual adds are recorded with "source": "manual".


4

Remove from suppression

Rarely needed. A customer changes their mind, an address is wrongly suppressed (false-positive bounce), an internal test address. 204 on success, 404 if the address isn't on the list.

DELETE /workspaces/:ws/suppression/:email
curl -X DELETE https://api.mail.productcraft.co/v1/workspaces/<ws>/suppression/userwhowantsback@example.com \
  -H 'authorization: Bearer pcft_live_...'

5

Webhooks — learn what happened

Mail's send is async. Webhooks are how your system learns about delivery, bounces and complaints. Add an endpoint and subscribe it to the events you care about.

The email events (the full catalogue, domain and suppression events included, is at GET /workspaces/:ws/webhooks/event-types):

  • email.sent — the message was accepted and we are delivering it to the recipient's mail server. This is hand-off, not arrival.
  • email.delivered — the recipient's mail server accepted the message. Emails sent before delivery tracking started, or through your own SMTP relay, never produce it: a relay's SMTP response proves hand-off, not delivery. We would rather tell you the number is unknown than tell you a number that is wrong.
  • email.delivery_delayed — a temporary failure: greylisting, a rate limit or a reputation block, and the message is being retried. It never suppresses the recipient, but a sender collecting these is a sender in trouble.
  • email.bounced — permanent delivery failure. The address goes on your suppression list.
  • email.complained — the recipient marked the message as spam. The address is suppressed with source complaint.
  • email.failed — the message was refused before sending. Nothing went out.
  • email.suppressed — a send was refused because the recipient is on the suppression list.
  • email.opened and email.clicked — the first open, and each click, of an email sent with tracking on. Tracking is off unless you turn it on, per domain or per email (section 9), so most mail never produces these.
  • email.scheduled and email.canceled — a send with scheduled_at was accepted, or canceled before it went out.

The old message.* names (message.sent, message.deferred, message.bounced, …) are still accepted as aliases for one release, and an endpoint subscribed under an alias receives that alias as the event type. Switch to the email.* names.

POST /workspaces/:ws/webhooks/endpoints
curl -X POST https://api.mail.productcraft.co/v1/workspaces/<ws>/webhooks/endpoints \
  -H 'authorization: Bearer pcft_live_...' \
  -H 'content-type: application/json' \
  -H 'idempotency-key: create-bounces-hook' \
  -d '{
    "url":         "https://acme.example.com/webhooks/mail",
    "event_types": ["email.delivered", "email.bounced", "email.complained"]
  }'

A workspace has up to 10 endpoints, each with its own event list (event_types; leave it empty for every event, including ones added later; the older name events is still accepted), an optional domain_id filter and an on/off switch. The response includes the whsec_… signing secret, shown once. Verifying the signature, Send test, automatic retries, auto-disable, the event log, replay and secret rotation work the same in every ProductCraft product and are in the Webhooks guide, with Node code you can paste.

Deprecated: the older single-slot routes (/webhooks/default, /webhooks/domains/:domain_id and GET /webhooks) still work, show up in the endpoint list as legacy slots, and answer with Deprecation: true and Sunset: Fri, 15 Jan 2027 00:00:00 GMT. After 2027-01-15 they return 410. Move to /webhooks/endpoints: a legacy slot is already an endpoint there, so you can manage it by its id today.


6

Webhook payload + signature

Every delivery is signed with Standard Webhooks; the Webhooks guide shows how to verify it. Endpoints created before 2026-10-17, and slots set through the deprecated routes, also receive the older X-Mail-Signature header until 2027-01-15. New endpoints get only the Standard Webhooks headers, so verify those.

Bounce event
POST https://acme.example.com/webhooks/mail
webhook-id:        evt_5b2c1a3e-...
webhook-timestamp: 1778499378
webhook-signature: v1,...

{
  "id":           "evt_5b2c1a3e-...",
  "type":         "email.bounced",
  "created_at":   "2026-05-07T09:36:18.412Z",
  "workspace_id": "24fab978-...",
  "domain_id":    "9c1d...",
  "data": {
    "email_id":    "3f0c...",
    "from":        "noreply@acme.com",
    "to":          "bounced@example.com",
    "bounce_type": "Permanent",
    "occurred_at": "2026-05-07T09:36:17.998Z"
  }
}

With the SDK, mail.webhooks.unwrap() checks the signature over the raw body (both header schemes, several secrets during a rotation) and returns the event typed by type:

app/webhooks/mail/route.ts
import { Mail, WebhookVerificationError } from "@productcraft/mail";

const mail = new Mail();

export async function POST(req: Request) {
  try {
    // Verifies the signature over the raw body and returns a typed
    // event. The secret defaults to PRODUCTCRAFT_MAIL_WEBHOOK_SECRET;
    // pass several during a rotation.
    const event = await mail.webhooks.unwrap({
      payload: await req.text(),
      headers: req.headers,
    });
    if (event.type === "email.bounced") {
      console.log(event.data.to, event.data.bounce_type);
    }
    return new Response(null, { status: 204 });
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      return new Response("bad signature", { status: 400 });
    }
    throw err;
  }
}

A delivery succeeds on any 2xx within 15 seconds. A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours (7 attempts in all); each event shows when the next attempt is due. Deliveries go out within a few seconds of the event. Every event is kept for 30 days: list them with GET /workspaces/:ws/webhooks/events and send one again with POST /workspaces/:ws/webhooks/events/:id/replay. After 20 consecutive failures, or 24 hours of unbroken failure, the endpoint is auto-disabled (status: auto_disabled). Fix the receiver and switch it back on with PATCH { "enabled": true }.


7

Reputation hygiene

  • Don't send to addresses you haven't verified. Customer signs up → ask them to verify before sending anything beyond the verification email itself. Bounces on unverified addresses dent your domain's reputation across receivers.
  • Watch your bounce AND deferral rates. Above 2% bounces is the widely-cited threshold where receivers start filtering, but deferrals move first: a reputation block shows up as repeated email.delivery_delayed long before anything hard-bounces. Count both webhook event types against sends, or call GET /workspaces/:ws/deliverability, which rolls the same rows up into a verdict.
  • Read unconfirmed as “unknown”, not “fine”. The deliverability verdict returns unconfirmed when your mail has no delivery tracking (sent before tracking started, or through your own SMTP relay) and nothing has come back in either direction. That is the honest state of the world for a sender with no arrival evidence — and it is also exactly the shape a totally blackholed sender makes, which is why we refuse to call it healthy.
  • Don't reuse a long-dormant domain without warming it up. If you stop sending for months then resume at full volume, receivers treat the spike as suspicious. Ramp over 7–14 days.
  • One sender intent per address. noreply@ for operational mail, support@ for inbound, billing@ for receipts. Mixing intents on one address (transactional + marketing + replies) confuses receivers' reputation tracking.
  • Marketing mail needs an unsubscribe link. Mail doesn't inject one for you — put it in your template (or use {{> bp.footer}} with footer text that includes it) and wire it to the suppression POST above. The lint flags bodies without one (body.no_unsubscribe); transactional mail is exempt.

8

When things go wrong

Symptoms + first-look:

  • “My emails are landing in spam” — check the DMARC report (sent to your rua=address). If SPF or DKIM are failing for any of your sends, that's the cause. Most often: missing or wrong DKIM record.
  • “Send is returning 422 ‘recipient is on this workspace's suppression list’” — list GET /workspaces/:ws/suppression and find the row to see the source and reason.
  • “Bounces aren't firing webhooks” — check GET /webhooks/endpoints for an endpoint with status: auto_disabled (sustained failures) or without the event in its events, and GET /webhooks/events for what Mail sent and what your endpoint answered; replay from there. If you send through your own SMTP relay, Mail only learns about bounces the relay rejects during the SMTP session; a bounce your provider reports later never reaches Mail, so no event fires.
  • “A specific recipient never gets mail” — they might be on the suppression list, OR their corporate filter is rejecting silently. Use the message log (Chapter 6) to confirm delivery status before suspecting the customer.

9

Open and click tracking

Off unless you turn it on, per domain or per email. Read what the numbers can and cannot tell you before you rely on them.

Turn tracking on for a domain on its Configuration tab, or with PATCH /domains/:id and open_tracking / click_tracking. One email can override the domain with tracking on the send body:

POST /workspaces/:ws/emails
{
  "from": "Acme <news@mail.acme.com>",
  "to": "ada@example.com",
  "subject": "What shipped in November",
  "html": "<p>Read the <a href=\"https://acme.com/blog/november\">post</a>.</p>",
  "tracking": { "opens": true, "clicks": true }
}
  • Opens add a 1x1 invisible image. Its first load records opened_at and fires email.opened, once per email.
  • Clicks send every http(s) link in the html through track.productcraft.co. That host records the click, fires email.clicked with the link, and redirects to the exact address you wrote. The address is signed into the link, so the redirect cannot be pointed anywhere else, and links keep working after the 30-day message log forgets the email. A repeat click on the same link within a minute counts once.
  • Left alone: the unsubscribe link, mailto: and tel: links, anchors, the plain-text part, and any link you mark <a data-pc-track="false">.
  • Broadcasts follow the domain settings, and their results show opens, clicks and the most clicked links.

Why a ProductCraft tracking host. Tracked links use track.productcraft.co rather than a subdomain of yours, so they work over HTTPS with no DNS records and no certificate to manage. A custom tracking subdomain is not offered (tracking_subdomain answers 422).

The numbers are inflated, and not evenly. Apple Mail Privacy Protection loads every image when the message arrives, read or not, so a large share of “opens” are Apple's servers. Corporate security gateways follow every link before the reader sees the email. Each event carries proxy (apple, google, yahoo, microsoft) and bot so you can discount them. Treat opens as a trend across many emails, never as proof that one person read one email. Clicks are the better signal.

Privacy. Tracking records the time, the user agent, the proxy and bot tags, and the network the request came from, cut down to its /24 (IPv4) or /48 (IPv6) so it never identifies a household. A request that sends Do Not Track or Global Privacy Control is answered normally and recorded nowhere. Everything is kept with the message log for 30 days, in the EU. Under the ePrivacy rules (in force across the EU, and the UK's PECR), a tracking pixel reads information from the reader's device, so you generally need their consent before you track marketing email, and you should say so in your privacy notice. Keep tracking off for transactional mail such as receipts, password resets and sign-in codes: it adds nothing there, and a rewritten link in a security email looks less trustworthy.