Generated banner for Email Best Practices
Generated logo for Email Best Practices

Email Best Practices

ResendOfficialCreated by Resend

  • Skill
  • Guidelines
  • Business and productivity
  • MIT
  • No issues found

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

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/resend/email-best-practices/download
  2. 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

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.

Files

references/webhooks-events.md

Webhooks and Events

Receiving and processing email delivery events in real-time.

Event Types

EventWhen FiredUse For
email.sentEmail accepted by ResendConfirming send initiated
email.deliveredEmail delivered to recipient serverConfirming delivery
email.bouncedEmail bounced (hard or soft)List hygiene, alerting
email.complainedRecipient marked as spamImmediate unsubscribe
email.openedRecipient opened emailEngagement tracking
email.clickedRecipient clicked linkEngagement tracking

Webhook Setup

1. Create Endpoint

Your endpoint must:

  • Accept POST requests

  • Return 2xx status quickly (within 5 seconds)

  • Handle duplicate events (idempotent processing)

app.post('/webhooks/resend', async (req, res) => {
  // Return 200 immediately to acknowledge receipt
  res.status(200).send('OK');

  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
2. Verify Signatures

Always verify webhook signatures to prevent spoofing.

import { Webhook } from 'svix';

const webhook = new Webhook(process.env.RESEND_WEBHOOK_SECRET);

app.post('/webhooks/resend', (req, res) => {
  try {
    const payload = webhook.verify(
      JSON.stringify(req.body),
      {
        'svix-id': req.headers['svix-id'],
        'svix-timestamp': req.headers['svix-timestamp'],
        'svix-signature': req.headers['svix-signature'],
      }
    );
    // Process verified payload
  } catch (err) {
    return res.status(400).send('Invalid signature');
  }
});
3. Register Webhook URL

Configure your webhook endpoint in the Resend dashboard or via API.

Processing Events

Bounce Handling
async function handleBounce(event) {
  const { email_id, email, bounce_type } = event.data;

  if (bounce_type === 'hard') {
    // Permanent failure - remove from all lists
    await suppressEmail(email, 'hard_bounce');
    await removeFromAllLists(email);
  } else {
    // Soft bounce - track and remove after threshold
    await incrementSoftBounce(email);
    const count = await getSoftBounceCount(email);
    if (count >= 3) {
      await suppressEmail(email, 'soft_bounce_limit');
    }
  }
}
Complaint Handling
async function handleComplaint(event) {
  const { email } = event.data;

  // Immediate suppression - no exceptions
  await suppressEmail(email, 'complaint');
  await removeFromAllLists(email);
  await logComplaint(event); // For analysis
}
Delivery Confirmation
async function handleDelivered(event) {
  const { email_id } = event.data;
  await updateEmailStatus(email_id, 'delivered');
}

Idempotent Processing

Webhooks may be sent multiple times. Use event IDs to prevent duplicate processing.

async function processWebhook(event) {
  const eventId = event.id;

  // Check if already processed
  if (await isEventProcessed(eventId)) {
    return; // Skip duplicate
  }

  // Process event
  await handleEvent(event);

  // Mark as processed
  await markEventProcessed(eventId);
}

Error Handling

Retry Behavior

If your endpoint returns non-2xx, webhooks will retry with exponential backoff:

  • Retry 1: ~30 seconds

  • Retry 2: ~1 minute

  • Retry 3: ~5 minutes

  • (continues for ~24 hours)

Best Practices
  • Return 200 quickly - Process asynchronously to avoid timeouts

  • Be idempotent - Handle duplicate deliveries gracefully

  • Log everything - Store raw events for debugging

  • Alert on failures - Monitor webhook processing errors

  • Queue for processing - Use a job queue for complex handling

Testing Webhooks

Local development: Use ngrok or similar to expose localhost.

ngrok http 3000
# Use the ngrok URL as your webhook endpoint

Verify handling: Send test events through Resend dashboard or manually trigger each event type.

Ingest webhooks for data storage

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.

Attribution and licence

Created by
Resend
Publisher
Resend (Official)
Source
resend/resend-skills · skills/email-best-practices · commit 389de56
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Resend.

Download ZIP

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