Email Best Practices

From the author

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, making emails accessible (alt text, headings, contrast, screen readers), or deciding transactional vs marketing.

— the description by Resend

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured framework for managing the entire lifecycle of email communications. It covers technical infrastructure like SPF/DKIM/DMARC authentication, legal compliance across major jurisdictions (GDPR, CAN-SPAM, CASL), and accessibility standards for screen readers and diverse email clients. It also offers guidance on transactional versus marketing email strategies, list management, and building reliable delivery pipelines with retry logic and webhooks.

What it does

Provides technical guidance for email authentication (SPF, DKIM, DMARC) to improve deliverability.
Outlines legal requirements for global email compliance including GDPR, CAN-SPAM, and CASL.
Defines accessibility standards for email content, including screen reader support and contrast.
Offers architectural patterns for transactional and marketing email workflows.
Details best practices for list management, bounce handling, and suppression lists.
Explains how to implement reliable sending with idempotency, retries, and webhook event tracking.

When to use it

When setting up a new email infrastructure for an application.
When troubleshooting high bounce rates or emails landing in spam folders.
When designing transactional email templates like password resets or order confirmations.
When implementing email capture forms that require legal consent tracking.
When auditing existing email templates for accessibility and compliance.

Advantages

Reduces the risk of legal penalties by providing clear compliance guidelines.
Improves email deliverability by standardizing authentication and list hygiene.
Ensures emails are accessible to all users, including those using assistive technology.
Provides a clear architectural path for building production-ready email systems.
Helps distinguish between transactional and marketing email strategies to optimize engagement.

Usage examples

“What are the legal requirements for sending marketing emails to users in the EU versus the US?”: The agent provides a comparison of GDPR and CAN-SPAM, highlighting the need for explicit opt-in consent for GDPR and the requirement for physical addresses and opt-out mechanisms for CAN-SPAM.
“How do I make my transactional email templates accessible for screen readers?”: The agent outlines specific HTML requirements, such as setting lang/dir attributes, using role='presentation' for layout tables, and ensuring proper heading hierarchy.
“My emails are going to spam. What should I check first?”: The agent directs the user to the deliverability reference to verify DNS authentication (SPF, DKIM, DMARC) and check for common configuration issues.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/resend/email-best-practices/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip email-best-practices.zip -d .agents/skills

Documentation by Resend

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
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.

Files

ATTRIBUTION.mdAdded by AutoGineer904 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md3.9 KiB
references/accessibility.md9.3 KiB
references/compliance.md4.1 KiB
references/deliverability.md3.3 KiB
references/email-capture.md3.4 KiB
references/email-types.md5.7 KiB
references/list-management.md4.5 KiB
references/marketing-emails.md3.2 KiB
references/sending-reliability.md4.5 KiB
references/transactional-email-catalog.md10.1 KiB
references/transactional-emails.md2.4 KiB
references/webhooks-events.md4.2 KiB

references/sending-reliability.md

Sending Reliability

Ensuring emails are sent exactly once and handling failures gracefully.

Idempotency

Prevent duplicate emails when retrying failed requests.

The Problem

Network issues, timeouts, or server errors can leave you uncertain if an email was sent. Retrying without idempotency risks sending duplicates.

Solution: Idempotency Keys

Send a unique key with each request. If the same key is sent again, the server returns the original response instead of sending another email.

// Generate deterministic key based on the business event
const idempotencyKey = `password-reset-${userId}-${resetRequestId}`;

await resend.emails.send({
  from: '[email protected]',
  to: user.email,
  subject: 'Reset your password',
  html: emailHtml,
}, {
  headers: {
    'Idempotency-Key': idempotencyKey
  }
});

Key Generation Strategies

Strategy	Example	Use When
Event-based	`order-confirm-${orderId}`	One email per event (recommended)
Request-scoped	`reset-${userId}-${resetRequestId}`	Retries within same request
UUID	`crypto.randomUUID()`	No natural key (generate once, reuse on retry)

Best practice: Use deterministic keys based on the business event. If you retry the same logical send, the same key must be generated. Avoid Date.now() or random values generated fresh on each attempt.

Key expiration: Idempotency keys are typically cached for 24 hours. Retries within this window return the original response. After expiration, the same key triggers a new send—so complete your retry logic well within 24 hours.

Retry Logic

Handle transient failures with exponential backoff.

When to Retry

Error Type	Retry?	Notes
5xx (server error)	✅ Yes	Transient, likely to resolve
429 (rate limit)	✅ Yes	Wait for rate limit window
4xx (client error)	❌ No	Fix the request first
Network timeout	✅ Yes	Transient
DNS failure	✅ Yes	May be transient

Exponential Backoff

async function sendWithRetry(emailData, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const { data, error } = await resend.emails.send(emailData);
    if (!error) {
      return data;
    }
    if (!isRetryable(error) || attempt === maxRetries - 1) {
      throw error;
    }
    const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
    await sleep(delay + Math.random() * 1000); // Add jitter
  }
}

function isRetryable(error) {
  return error.statusCode >= 500 ||
         error.statusCode === 429;
}

Backoff schedule: 1s → 2s → 4s → 8s (with jitter to prevent thundering herd)

Error Handling

Common Error Codes

Code	Meaning	Action
400	Bad request	Fix payload (invalid email, missing field)
401	Unauthorized	Check API key
403	Forbidden	Check permissions, domain verification
404	Not found	Check endpoint URL
422	Validation error	Fix request data
429	Rate limited	Back off, retry after delay
500	Server error	Retry with backoff
503	Service unavailable	Retry with backoff

Error Handling Pattern

const { data, error } = await resend.emails.send(emailData);

if (error) {
  if (error.statusCode === 429) {
    await queueForRetry(emailData, error.retryAfter);
  } else if (error.statusCode >= 500) {
    await queueForRetry(emailData);
  } else {
    await logFailure(error, emailData);
    await alertOnCriticalEmail(emailData); // For password resets, etc.
  }
} else {
  await logSuccess(data.id, emailData);
}

Queuing for Reliability

For critical emails, use a queue to ensure delivery even if the initial send fails.

Benefits:

Survives application restarts
Automatic retry handling
Rate limit management
Audit trail

Simple pattern:

Write email to queue/database with "pending" status
Process queue, attempt send
On success: mark "sent", store message ID
On retryable failure: increment retry count, schedule retry
On permanent failure: mark "failed", alert

Timeouts

Set appropriate timeouts to avoid hanging requests.

const signal = new AbortSignal.timeout(10000);

await resend.emails.send(emailData, { signal });

Recommended: 10-30 seconds for email API calls.

Webhooks & Events - Process delivery confirmations and failures
List Management - Handle bounces and suppress invalid addresses

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Copywriting
Corey Haines· Community
Expert conversion copywriting for marketing pages that avoids AI-generated patterns and focuses on clarity, specificity, and customer-centric messaging.
Business and productivityClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository59k
Popups
Corey Haines· Community
Expert guidelines for designing and optimizing conversion-focused popups, modals, and banners that respect user experience.
Business and productivityClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository59k
Content Strategy
Corey Haines· Community
A strategic framework for planning, prioritizing, and managing content that drives traffic, builds authority, and generates leads.
Business and productivityClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository59k
Ad Creative
Corey Haines· Community
Generates and iterates on paid advertising creative, including headlines, ad copy, and visual concepts based on performance data and brand context.
Business and productivityClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository59k
Attribution
Corey Haines· Community
Analyze marketing performance by reconciling attribution models, tracking journeys, and identifying the true drivers of revenue.
Business and productivityClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository59k
Reverse Engineer Marketing
Corey Haines· Community
A growth analysis framework that reverse engineers competitor marketing strategies using public data to identify actionable growth plays.
Business and productivityClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository59k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download email-best-practices.zip