home / skills / velcrafting / codex-skills / email-best-practices-main

email-best-practices-main skill

/skills/resend/email-best-practices-main

This skill helps you implement email best practices to improve deliverability, compliance, and user engagement across transactional and marketing emails.

This is most likely a fork of the email-best-practices skill from resend

npx playbooks add skill velcrafting/codex-skills --skill email-best-practices-main

Review the files below or copy the command above to add this skill to your agents.

Files (12)

SKILL.md

3.2 KB

---
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](./resources/deliverability.md) |
| Build password reset, OTP, confirmations | [Transactional Emails](./resources/transactional-emails.md) |
| Plan which emails your app needs | [Transactional Email Catalog](./resources/transactional-email-catalog.md) |
| Build newsletter signup, validate emails | [Email Capture](./resources/email-capture.md) |
| Send newsletters, promotions | [Marketing Emails](./resources/marketing-emails.md) |
| Ensure CAN-SPAM/GDPR/CASL compliance | [Compliance](./resources/compliance.md) |
| Decide transactional vs marketing | [Email Types](./resources/email-types.md) |
| Handle retries, idempotency, errors | [Sending Reliability](./resources/sending-reliability.md) |
| Process delivery events, set up webhooks | [Webhooks & Events](./resources/webhooks-events.md) |
| Manage bounces, complaints, suppression | [List Management](./resources/list-management.md) |

## Start Here

**New app?**
Start with the [Catalog](./resources/transactional-email-catalog.md) to plan which emails your app needs (password reset, verification, etc.), then set up [Deliverability](./resources/deliverability.md) (DNS authentication) before sending your first email.

**Spam issues?**
Check [Deliverability](./resources/deliverability.md) first—authentication problems are the most common cause. Gmail/Yahoo reject unauthenticated emails.

**Marketing emails?**
Follow this path: [Email Capture](./resources/email-capture.md) (collect consent) → [Compliance](./resources/compliance.md) (legal requirements) → [Marketing Emails](./resources/marketing-emails.md) (best practices).

**Production-ready sending?**
Add reliability: [Sending Reliability](./resources/sending-reliability.md) (retry + idempotency) → [Webhooks & Events](./resources/webhooks-events.md) (track delivery) → [List Management](./resources/list-management.md) (handle bounces).

Overview

This skill provides practical guidance for building reliable, compliant, and deliverable email features. It focuses on architecture, deliverability, consent capture, sending reliability, and list hygiene to reduce bounces and spam complaints. Use it to design email flows, authentication, and compliance checks before sending at scale.

How this skill works

The skill describes a deterministic email flow: capture and validate addresses, apply double opt-in and consent recording, run suppression checks, and perform idempotent sends with retry logic. It covers DNS authentication (SPF/DKIM/DMARC), webhook processing for delivery events, and automated list-management jobs for bounces and complaints. Guidance is organized into targeted topics so you can apply the correct practices for transactional vs marketing emails.

When to use it

Building password reset, OTP, or other transactional email flows
Troubleshooting emails that land in spam or experience high bounce rates
Setting up SPF, DKIM, and DMARC DNS records for deliverability
Designing email capture and consent flows to satisfy GDPR/CAN-SPAM/CASL
Implementing webhooks, event processing, and retry/idempotency logic

Best practices

Authenticate your domain (SPF/DKIM/DMARC) before sending to major providers
Use double opt-in and store consent timestamps and sources for compliance
Separate transactional and marketing streams; ensure transactional emails bypass marketing suppression where appropriate
Implement idempotent send keys and exponential retry for transient failures
Process webhook events to update suppression lists and trigger list-hygiene jobs regularly

Example use cases

New app: plan required transactional messages, then configure DNS auth before first send
Fix spam deliverability: verify SPF/DKIM/DMARC, monitor provider feedback loops, and adjust sending patterns
Marketing campaign: collect consent via a validated capture flow, then honor unsubscribes and regional legal requirements
Production sending: add idempotency, retry logic, and webhook-driven bounce handling to keep lists healthy

FAQ

How do I decide transactional vs marketing for an email?

Transactional emails contain account- or activity-driven content (password resets, receipts) and should be delivered reliably; marketing emails promote or advertise and require explicit consent and unsubscribe handling.

What is the first thing to check when emails go to spam?

Start with domain authentication (SPF/DKIM/DMARC); unauthenticated mail is the most common cause of rejections by major providers.