mcpField
E
email-best-practices

email-best-practices

github.com/resendDevelopment1468.1k installsUpdated 3w ago
Repository

About email-best-practices

Email Best Practices is a reference skill for building deliverable, compliant, accessible emails. It guides application teams through email planning, authentication, consent, sending reliability, event handling, and list management.

Key features

  1. 01Email planning and type selection
  2. 02Deliverability and DNS authentication guidance
  3. 03Consent and compliance practices
  4. 04Retry and idempotent sending guidance
  5. 05Delivery events and webhook handling
  6. 06Accessibility and list management guidance

Use cases

  1. 01Plan transactional emails for an application
  2. 02Set up newsletter signup and consent
  3. 03Troubleshoot email delivery and spam issues
  4. 04Handle retries, bounces, and delivery events

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/resend/email-best-practices --skill email-best-practices

After installing, type/email-best-practicesin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
.github/workflows/
sync-skills.yml
references/
email-capture.md
email-types.md
marketing-emails.md
compliance.md
accessibility.md
deliverability.md
list-management.md
sending-reliability.md
transactional-emails.md
webhooks-events.md
transactional-email-catalog.md
tests/
README.md
tests/scenarios/
01-spam-deliverability.md
04-webhook-bounce-handling.md
02-multi-region-compliance.md
05-new-saas-email-plan.md
03-retry-idempotency.md

Details

From the project README

Email Best Practices

Guidance for building deliverable, compliant, user-friendly emails.

Architecture Overview

[User] → [Email Form] → [Validation] → [Double Opt-In]
                                              ↓
                                    [Consent Recorded]
                                              ↓
[Suppression Check] ←──────────────[Ready to Send]
        ↓
[Idempotent Send + Retry] ──────→ [Email API]
                                       ↓
                              [Webhook Events]
                                       ↓
              ┌────────┬────────┬─────────────┐
              ↓        ↓        ↓             ↓
         Delivered  Bounced  Complained  Opened/Clicked
                       ↓        ↓
              [Suppression List Updated]
                       ↓
              [List Hygiene Jobs]

Quick Reference

Need to...See
Set up SPF/DKIM/DMARC, fix spam issuesDeliverability
Build password reset, OTP, confirmationsTransactional Emails
Plan which emails your app needsTransactional Email Catalog
Build newsletter signup, validate emailsEmail Capture
Send newsletters, promotionsMarketing Emails
Ensure CAN-SPAM/GDPR/CASL complianceCompliance
Decide transactional vs marketingEmail Types
Handle retries, idempotency, errorsSending Reliability
Process delivery events, set up webhooksWebhooks & Events
Manage bounces, complaints, suppressionList Management
Make emails accessible (screen readers, alt text, contrast)Accessibility

Start Here

New app? Start with the Catalog to plan which emails your app needs (password reset, verification, etc.), then set up Deliverability (DNS authentication) before sending your first email.

Spam issues? Check Deliverability first—authentication problems are the most common cause. Gmail/Yahoo reject unauthenticated emails.

Marketing emails? Follow this path: Email Capture (collect consent) → Compliance (legal requirements) → Marketing Emails (best practices).

Production-ready sending? Add reliability: Sending Reliability (retry + idempotency) → Webhooks & Events (track delivery) → List Management (handle bounces).

Accessibility? Most emails fail basic accessibility checks. See Accessibility for lang/dir, presentational tables, headings, alt text, <title>, and contrast.

Comments

Markdown supported