<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for DeepSeek: scripts/model-profiles.json -->

#Task boundary

1. Implement exactly the task as stated. Do not add abstractions, options, config, or files the task did not name.
2. Comments, identifiers, commit messages and log strings are English only.
3. Stop when the checklist at the end passes. Do not refactor or "improve" surrounding code.
4. Every checklist item below is backed by an assertion in a test or by pasted command output, never by a sentence.

---

#Purpose

Rules for transactional email — password resets, receipts, notifications. The hard part is not sending; it is arriving. An email that lands in spam is worse than one that fails loudly, because nothing tells you.

Marketing email is a different discipline with different consent rules. Keep it on a different subdomain so its reputation cannot damage your password resets.

---

#Authenticate the domain, or nothing else matters

Three DNS records. Without all three, major providers will filter you regardless of content.

dns
; SPF — which servers may send as this domain. One record only.
example.com.  TXT  "v=spf1 include:_spf.provider.com -all"

; DKIM — the provider's public key; it signs each message
sel1._domainkey.example.com.  CNAME  sel1.domainkey.provider.com.

; DMARC — what to do when SPF and DKIM fail, and where to report
_dmarc.example.com.  TXT  "v=DMARC1; p=reject; rua=mailto:dmarc@example.com; pct=100"

Roll DMARC out as p=none → p=quarantine; pct=25 → p=reject, reading the aggregate reports at each step. Going straight to p=reject will silently break whatever legitimate sender you forgot about.

Use a subdomain for sending (mail.example.com). It isolates reputation and keeps your root domain's DNS simpler.

---

#Use a provider, and one abstraction

Do not run your own SMTP server. Deliverability depends on IP reputation, feedback loops and relationships with mailbox providers that a provider already has.

ts
interface Mailer {
  send(msg: { to: string; template: TemplateId; data: Record<string, unknown>;
              idempotencyKey: string }): Promise<{ messageId: string }>;
}

One interface, one implementation per provider. Providers have outages and price changes, and a direct SDK call from forty places is a migration nobody schedules.

1. Warm up a new sending domain or dedicated IP gradually. A cold domain sending 50,000 messages on day one is filtered as a spam source.
2. A shared IP pool is usually better for low volume — you inherit the provider's reputation instead of building your own. A dedicated IP only pays off above a consistent high volume.

---

#Send asynchronously and idempotently

ts
// The request must not depend on the provider's availability or latency
await queue.add("send-email", { userId, template: "password-reset" },
                { jobId: `pwreset:${userId}:${tokenId}` });

1. Never send inline in a request handler. A slow provider becomes your latency, and an outage becomes your outage.
2. Enqueue after the transaction commits — a receipt for an order that rolled back is a support ticket. → Backend/background-jobs
3. Deduplicate: retries must not send the message twice. The deterministic job id above is the guard.
4. Retry on 5xx and timeouts only. A 4xx for an invalid address is permanent — retrying it damages your reputation.

---

#Content and templating

1. Multipart: HTML and plain text. A missing text part is a spam signal, and some clients only render text.
2. Table-based layout with inline CSS. Email clients are twenty years behind browsers; flexbox, grid and external stylesheets do not work reliably.
3. Width around 600px, images with alt text, and a design that still communicates with images blocked — which is the default in many clients.
4. Escape every interpolated value. A user-controlled display name in an HTML email is an injection vector, especially where the email is later viewed in a web client. → Security/xss
5. Never put a secret in a URL you also log, and never email a password.
6. Localise using the recipient's stored preference, not the sending server's.
7. Test rendering across clients (Litmus, Email on Acid, or at minimum Gmail, Outlook, Apple Mail) — Outlook's rendering engine will break a layout that works everywhere else.

---

#Handle bounces and complaints

Ignoring these is how a sending domain gets blocked.

Consume the provider's webhooks and maintain a suppression list checked before every send. → API/webhooks

Continuing to send to hard-bounced addresses is the fastest way to be classified as a spam source, because it is exactly what a spammer's list looks like.

Watch bounce rate (< 2%), complaint rate (< 0.1%), and delivery rate. Alert when they move — a deploy that breaks the unsubscribe link shows up here first.

Verify your setup against a diagnostic tool (mail-tester.com, MXToolbox, or dig TXT _dmarc.example.com) before launch, and re-verify after any DNS change.

---

#Anti-patterns

---

#Checklist

• SPF, DKIM and DMARC are published and verified for the sending domain
• Exactly one SPF record exists
• DMARC has progressed beyond p=none and reports are reviewed
• Transactional and marketing mail use separate subdomains
• A provider is used; no self-hosted SMTP
• New domains and IPs are warmed up gradually
• All sending goes through one internal interface
• Email is sent from a background job, after the transaction commits
• Sends are deduplicated by a deterministic key
• Retries cover transient failures only
• Every message is multipart HTML and plain text
• Templates use table layout and inline CSS, tested in real clients
• Emails remain useful with images blocked
• All interpolated values are escaped
• Bounce, complaint and unsubscribe webhooks feed a suppression list
• The suppression list is checked before every send
• Bounce rate, complaint rate and delivery rate are monitored and alerted