Transactional Email skill for Claude Code

Done well means: mail is sent from a dedicated subdomain that passes SPF and DKIM with DMARC alignment, every send is queued and idempotent, bounces and complaints flow back through verified webhooks into a suppression list, and every template has a plain-text part and renders in the major clients.

Ground rules

• API keys in env vars (RESEND_API_KEY, POSTMARK_SERVER_TOKEN, AWS credentials via IAM role). Scope keys to sending only; one key per environment.
• Send transactional mail from a subdomain (mail.example.com or notify.example.com), separate from marketing streams, so a campaign complaint spike does not hurt password resets.
• Never send from the request path synchronously when the provider may be slow: enqueue and return. Exception: magic links where the user waits, and even then set a short timeout.
• Never put secrets, full tokens in logs, or PII beyond need into provider metadata/tags.
• Do not use transactional infrastructure for marketing. Mailbox providers and ToS treat them differently (unsubscribe rules, consent).

Choose the provider

Situation	Default	Notes
TypeScript app, React templates, fast setup	Resend	First-class React Email; Svix-signed webhooks
Deliverability-first transactional, strict separation of streams	Postmark	Message Streams (outbound vs. broadcast); fast delivery
High volume, AWS-native, lowest unit cost	Amazon SES (v2 API)	You build more: event destinations, suppression, warm-up
Already on a platform with built-in mail (Supabase Auth, Clerk)	Use it for auth mail only, custom SMTP for branding	Default shared senders have low limits

Workflow

- [ ] 1. Inventory: existing sends, templates, provider, sending domain
- [ ] 2. Set up the sending subdomain DNS (SPF, DKIM, DMARC, optional return-path)
- [ ] 3. Build templates with a plain-text part; preview in clients
- [ ] 4. Implement a single send function: queue, idempotency, error handling
- [ ] 5. Wire bounce/complaint/delivery webhooks with signature verification
- [ ] 6. Maintain suppression; respect it before every send
- [ ] 7. Verify DNS, headers, rendering, and webhook paths

1. Inventory

grep -rnE "nodemailer|resend|postmark|@aws-sdk/client-sesv2|sendgrid|mailgun" package.json requirements*.txt pyproject.toml 2>/dev/null
grep -rn "sendMail\|emails.send\|sendEmail\|SendEmailCommand" --exclude-dir=node_modules . | head -30

2. DNS for the sending domain

Minimum for any provider, enforced by Gmail, Yahoo (since February 2024) and Outlook (since May 2025) for bulk senders, and good practice at any volume:

Record	Requirement
SPF	Exactly one v=spf1 TXT per hostname, ≤ 10 DNS lookups, ends in ~all or -all
DKIM	Provider-issued CNAME/TXT keys at <selector>._domainkey, 2048-bit where offered
DMARC	_dmarc.<org domain> TXT, start p=none; rua=mailto:..., move to quarantine/reject once reports are clean
Alignment	DKIM d= or SPF return-path domain shares the org domain with the visible From:
PTR / TLS	Handled by the provider unless self-hosting SMTP

Check what is published:

sh scripts/check_email_dns.sh example.com mail.example.com resend   # domain, sending host, DKIM selector(s)

Record syntax, alignment examples, DMARC rollout steps, and per-provider DNS specifics: read references/dns-authentication.md when setting up a new domain or diagnosing spam placement.

3. Templates

Default: React Email (@react-email/components) for TS projects; MJML for other stacks.

// emails/password-reset.tsx
import { Html, Head, Preview, Body, Container, Text, Button } from "@react-email/components";
export default function PasswordReset({ url, minutes = 30 }: { url: string; minutes?: number }) {
  return (
    <Html lang="en">
      <Head />
      <Preview>Reset your password (link expires in {minutes} minutes)</Preview>
      <Body style={{ fontFamily: "Arial, sans-serif", backgroundColor: "#ffffff" }}>
        <Container style={{ maxWidth: 560, padding: 24 }}>
          <Text>Someone requested a password reset for your account.</Text>
          <Button href={url} style={{ background: "#111", color: "#fff", padding: "12px 20px" }}>Reset password</Button>
          <Text>If you did not request this, ignore this email. Your password will not change.</Text>
        </Container>
      </Body>
    </Html>
  );
}

import { render } from "@react-email/render";   // async in current versions
const html = await render(<PasswordReset url={url} />);
const text = await render(<PasswordReset url={url} />, { plainText: true });

Template rules:

• Max width 600 px, inline styles (the components handle this), table-based layout via the components; no flexbox/grid reliance, no JS, no web fonts without fallbacks.
• Always include a text part and a meaningful <Preview>.
• Absolute HTTPS URLs for images and links; images have alt; content readable with images off. Dark mode: avoid transparent PNG logos on dark backgrounds.
• Keep HTML under ~100 KB or Gmail clips it.
• Preview locally with the React Email dev server (email dev script from the react-email package) and test in Gmail, Outlook (desktop renders with Word), Apple Mail.

4. One send function

// lib/email.ts
import { Resend } from "resend";
const resend = new Resend(process.env.RESEND_API_KEY);

export async function sendTransactional(msg: {
  to: string; subject: string; html: string; text: string; tag: string; dedupeKey: string;
}) {
  if (await isSuppressed(msg.to)) return { skipped: "suppressed" as const };
  const { data, error } = await resend.emails.send(
    {
      from: "Acme <[email protected]>",
      replyTo: "[email protected]",
      to: msg.to, subject: msg.subject, html: msg.html, text: msg.text,
      tags: [{ name: "category", value: msg.tag }],
    },
    { idempotencyKey: msg.dedupeKey },          // e.g. `password-reset/${resetTokenId}`
  );
  if (error) throw new EmailError(error.name, error.message);   // let the job retry
  await recordSend(msg.dedupeKey, data!.id);
  return { id: data!.id };
}

Provider equivalents:

• Postmark (postmark package): new ServerClient(token).sendEmail({ From, To, Subject, HtmlBody, TextBody, MessageStream: "outbound", Tag }).
• SES: @aws-sdk/client-sesv2 SendEmailCommand with Content.Simple (or Raw) and a ConfigurationSetName that routes events.

Call it from a background job with retries and exponential backoff on 429/5xx only. 4xx validation errors (bad address, unverified domain) will never succeed: log and stop. If the provider has no idempotency support, dedupe with your own sent_emails table keyed on dedupeKey before calling the API.

5. Event webhooks

Provider	Signature	Events to handle
Resend	Svix headers svix-id, svix-timestamp, svix-signature	email.bounced, email.complained, email.delivered, email.delivery_delayed
Postmark	No HMAC: protect with HTTP basic auth in the webhook URL plus a long random path; optionally IP allowlist	Bounce (check Type), SpamComplaint, Delivery
SES	SNS message signature (verify cert URL host is sns.<region>.amazonaws.com, check TopicArn), confirm subscription	Bounce (Permanent vs. Transient), Complaint, Delivery

// Resend webhook, verified with the svix package
import { Webhook } from "svix";
export async function POST(req: Request) {
  const payload = await req.text();
  const headers = Object.fromEntries(["svix-id", "svix-timestamp", "svix-signature"].map(h => [h, req.headers.get(h) ?? ""]));
  let evt: any;
  try { evt = new Webhook(process.env.RESEND_WEBHOOK_SECRET!).verify(payload, headers); }
  catch { return new Response("bad signature", { status: 400 }); }
  if (evt.type === "email.bounced" || evt.type === "email.complained") await suppress(evt.data.to, evt.type);
  return new Response("ok");
}

6. Suppression policy

• Hard bounce (permanent, invalid mailbox): suppress immediately and permanently.
• Soft bounce (mailbox full, transient): retry per provider; suppress after ~3–5 consecutive.
• Complaint: suppress from everything non-essential at once. Security mail (password reset the user just requested) may still be sent; nothing else.
• Keep spam complaint rate under 0.1% (Gmail’s hard ceiling is 0.3%); watch Google Postmaster Tools for the domain.
• Expose suppression in admin tooling so support can lift it after the user fixes the address.

Gotchas

• Second SPF record added for the new provider instead of merging into the existing one: both fail (permerror).
• DMARC p=reject turned on before checking reports: legit mail from a forgotten tool (CRM, helpdesk) starts bouncing.
• From: on the apex domain while DKIM signs only the subdomain with relaxed alignment off: DMARC fails.
• Sending password resets in the same stream as newsletters.
• No-reply addresses that bounce: users reply with real issues; set Reply-To to a monitored inbox.
• Link tracking rewrites magic links and password reset URLs; disable click tracking for auth mail (corporate scanners also pre-click links, so make tokens survive one GET or use a confirm button page).
• SES sandbox: only verified recipients until production access is granted.
• Retrying a timed-out send without an idempotency key: duplicate receipts.

Verification

1. sh scripts/check_email_dns.sh <domain> <sending-host> <selector> exits 0.
2. Send a real message to a Gmail account; “Show original” reports SPF, DKIM, DMARC all PASS with the expected domains.
3. Bad signature to the webhook returns 400; a provider “test event” lands in the suppression path. Send to the provider’s bounce test address (Resend [email protected], SES [email protected]) and confirm the address is suppressed.
4. The same job retried twice produces one email.
5. Templates checked in Gmail web, Outlook desktop, and iOS Mail, with images off.

Output contract

**Provider:** Resend (stream: transactional, domain mail.acme.com)
**DNS:** SPF pass, DKIM pass (selector resend), DMARC p=none with rua → plan quarantine after 2 weeks of clean reports
**Templates:** password-reset, receipt, invite (HTML + text, previewed in 3 clients)
**Sending:** lib/email.ts via job queue, idempotency key per business event
**Webhooks:** /api/webhooks/email (svix-verified) → suppression table
**Open items:** enable Google Postmaster Tools, raise DMARC policy