SKILL.md
enhance-email-deliverability — Inbox placement & lawful send
Degree of freedom: MIXED — T1 is the priority. 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) |
Keep enhance-* here (audit-and-fix, same family as enhance-web-seo). Do not steal "build a welcome email" from design-email.
How to reason
- Observe — SPF/DKIM/DMARC records and a real message's Authentication-Results
- Interpret — pass raw SPF/DKIM but fail alignment?
+all? DNS-only DKIM? - Classify — auth fail / hygiene hole / compliance miss / template (hand off)
- Severity — no DMARC or
+allblocks inbox placement
Worked example
Observe: one SPF with
+all; DKIM TXT present; no DMARC; marketing and
password-resets shareexample.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~allwhile warming), DMARCp=none+ruathen
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]
- Real headers — DKIM scored from a sent message, not DNS-only
- Alignment — From domain matches SPF/DKIM domains
- Streams split — marketing must not share the transactional domain
- Right owner — markup/copy →
design-email - Apply only on approval
Output format
- Auth table — SPF / DKIM / DMARC / alignment — pass/fail + exact fix
- Hygiene — bounce / complaint / list / warming
- Compliance — unsubscribe / footer / law
- Fix plan — auth first, then hygiene, then compliance
- Apply approved DNS/config; templates →
design-email
Related
design-email— markup and copyplan-privacy-compliance— consent to collect / to mailaudit-analytics— open/click instrumentationbackend-patterns— webhook + suppression store