enhance-email-deliverability git:20260923.68c095eA

Immutable. This exact content never changes and is served at /api/v1/blob/5cc3a595ff01a7df.

---
name: enhance-email-deliverability
description: >
  Audit and fix email deliverability: SPF, DKIM, DMARC, reputation, bounces
  and complaints, list hygiene, unsubscribe compliance. Use when "emails go to
  spam", "set up SPF/DKIM", or "check deliverability". Templates →
  design-email.
license: MIT
---

# enhance-email-deliverability — Inbox placement & lawful send

**Degree of freedom: MIXED.** Scoring auth/hygiene
`[HIGH freedom]`; DNS/config apply `[LOW freedom — after approval]`.
Audit-and-fix. Templates stay on `design-email`.

Close the gap between "the email sends" and "the email arrives". A beautiful
transactional template in spam is a broken signup flow.

Deliverability = authentication + reputation + hygiene + compliance. Miss any
one and placement collapses.

**Audit first. Apply DNS/config on approval.** Template markup stays on
`design-email`.

## This skill vs neighbors

| Skill | Owns |
|---|---|
| **enhance-email-deliverability** (this) | SPF/DKIM/DMARC, bounces, complaints, unsubscribe headers |
| `design-email` | Template markup, copy, React Email / MJML |
| `plan-privacy-compliance` | Consent to collect; this owns consent *to send* |
| `audit-analytics` | Whether open/click events fire (not inbox placement) |

"Build a welcome email" alone → `design-email`; this skill owns inbox placement, not templates.

## How to reason

1. **Observe** — SPF/DKIM/DMARC records and a real message's Authentication-Results
2. **Interpret** — pass raw SPF/DKIM but fail alignment? `+all`? DNS-only DKIM?
3. **Classify** — auth fail / hygiene hole / compliance miss / template (hand off)
4. **Severity** — no DMARC or `+all` blocks inbox placement

## Worked example

> **Observe:** one SPF with `+all`; DKIM TXT present; no DMARC; marketing and
> password-resets share `example.com`.
> **Interpret:** anyone can spoof; Gmail/Yahoo bulk will fail; a campaign
> complaint can sink transactional mail.
> **Classify:** auth fail + domain mixing.
> **Fix:** SPF `-all` (or `~all` while warming), DMARC `p=none`+`rua` then
> tighten, split transactional vs marketing domains — apply DNS only after approval.

---

## Phase 0 — Detect sending setup  [HIGH freedom]

- Provider: Resend / Postmark / SES / SendGrid / Mailgun / SMTP
- Sending domain(s) and DNS host
- Transactional vs marketing — **they should not share a domain**
- Where templates live (hand content issues to `design-email`)

---

## Phase 1 — Authentication (pass/fail gate)  [HIGH freedom; headers not DNS-only]

**SPF** — Authorizes the provider. Exactly one record. Under 10 DNS lookups.
Not `+all`.

**DKIM** — Signing on at the provider; public key in DNS; **real message
headers** signed (not DNS-only). 2048-bit keys.

**DMARC** — Record present. `p=none` (monitor) vs `quarantine` / `reject`.
`rua` reporting address. Gmail/Yahoo require DMARC for bulk senders.
**Alignment:** visible From domain matches SPF/DKIM domains. Misalignment
passes raw SPF/DKIM and still fails DMARC.

**PTR / dedicated IP** — if self-hosted or dedicated: PTR set, warmed, not
blocklisted.

---

## Phase 2 — Reputation & hygiene  [HIGH freedom]

**Bounces** — Hard bounces via webhook → suppression list honored on every send.

**Complaints** — Feedback loops / provider webhooks → immediate suppress.

**List hygiene (marketing)** — Opted-in only (cross-check
`plan-privacy-compliance`). No purchased lists. Inactive addresses removed.

**Sending patterns** — Warm new domains. Separate transactional vs marketing
so a campaign complaint does not sink password resets.

**Content flags** — Image-only, spammy phrasing, broken links, missing
plain-text → `design-email`.

---

## Phase 3 — Compliance footer  [HIGH freedom]

- Marketing: functional unsubscribe **and** one-click `List-Unsubscribe`
  headers (Gmail/Yahoo bulk). Transactional is exempt only if it is genuinely
  transactional.
- Physical address + sender ID — CAN-SPAM (US) and Japan 特定電子メール法
  for advertising mail.
- Unsubscribes honored on the *next* send.

---

## Definition of Done

- [ ] Streams identified and separated
- [ ] SPF / DKIM (real headers) / DMARC + alignment scored
- [ ] Bounce + complaint → suppression list
- [ ] Consent + inactive policy noted
- [ ] Warming addressed if cold
- [ ] One-click unsubscribe on marketing; legal footer present
- [ ] Template flags handed to `design-email`
- [ ] DNS/config applied only after approval

## Self-critique before applying DNS  [LOW freedom — do not skip]

1. **Real headers** — DKIM scored from a sent message, not DNS-only
2. **Alignment** — From domain matches SPF/DKIM domains
3. **Streams split** — marketing must not share the transactional domain
4. **Right owner** — markup/copy → `design-email`
5. **Apply only on approval**

## Output format

1. **Auth table** — SPF / DKIM / DMARC / alignment — pass/fail + exact fix
2. **Hygiene** — bounce / complaint / list / warming
3. **Compliance** — unsubscribe / footer / law
4. **Fix plan** — auth first, then hygiene, then compliance
5. Apply approved DNS/config; templates → `design-email`

## Related

- `design-email` — markup and copy
- `plan-privacy-compliance` — consent to collect / to mail
- `audit-analytics` — open/click instrumentation
- `backend-patterns` — webhook + suppression store