Email Best Practices
resend/email-best-practicesThis skill provides guidance on creating compliant, user-friendly emails and covers key practices such as setup, validation, and delivering transactional or marketing emails. It emphasizes establishing authentication via SPF/DKIM/DMARC, handling retries and webhooks, managing suppression lists, and ensuring legal compliance. It is suited for developers building email features, troubleshooting deliverability issues, or implementing email workflows.
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 issues Deliverability Build password reset, OTP, confirmations Transactional Emails Plan which emails your app needs Transactional Email Catalog Build newsletter signup, validate emails Email Capture Send newsletters, promotions Marketing Emails Ensure CAN-SPAM/GDPR/CASL compliance Compliance Decide transactional vs marketing Email Types Handle retries, idempotency, errors Sending Reliability Process delivery events, set up webhooks Webhooks & Events Manage bounces, complaints, suppression List Management
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).
GitHub Owner
Owner: resend
GitHub Links
- Website: https://resend.com
- Email: team@resend.com
Files
Deliverability
Transactional Emails
Transactional Email Catalog
- View: https://github.com/resend/email-best-practices/blob/HEAD/./resources/transactional-email-catalog.md
Email Capture
Marketing Emails
Compliance
Email Types
Sending Reliability
Webhooks & Events
List Management
Catalog
- View: https://github.com/resend/email-best-practices/blob/HEAD/./resources/transactional-email-catalog.md
Deliverability
Deliverability
Email Capture
Compliance
Marketing Emails
Sending Reliability
Webhooks & Events
List Management
SKILL.md
name: email-best-practices description: Use when building email features, emails going to spam, high bounce rates, setting up SPF/DKIM/DMARC authentication, implementing email capture, ensuring compliance (CAN-SPAM, GDPR, CASL), handling webhooks, retry logic, or deciding transactional vs marketing.
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 issues | Deliverability |
| Build password reset, OTP, confirmations | Transactional Emails |
| Plan which emails your app needs | Transactional Email Catalog |
| Build newsletter signup, validate emails | Email Capture |
| Send newsletters, promotions | Marketing Emails |
| Ensure CAN-SPAM/GDPR/CASL compliance | Compliance |
| Decide transactional vs marketing | Email Types |
| Handle retries, idempotency, errors | Sending Reliability |
| Process delivery events, set up webhooks | Webhooks & Events |
| Manage bounces, complaints, suppression | List Management |
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).