All skills
resend avatar

/email-best-practices

@376d1c3 official
by resendresend/resend-skills193 stars
28

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.

Use this Skill: https://skilld.dev/gh/resend/resend-skills/email-best-practices

This session only. Nothing lands on disk.

referencesemail-types.md

≈1.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Email Types: Transactional vs Marketing

Understanding the difference between transactional and marketing emails is crucial for compliance, deliverability, and user experience. This guide explains the distinctions and provides a catalog of transactional emails your app should include.

When to Use This

  • Deciding whether an email should be transactional or marketing
  • Understanding legal distinctions between email types
  • Planning what transactional emails your app needs
  • Ensuring compliance with email regulations
  • Setting up separate sending infrastructure

Transactional vs Marketing: Key Differences

Transactional Emails

Definition: Emails that facilitate or confirm a transaction the user initiated or expects. They're directly related to an action the user took or are legal notices you're required to serve.

Characteristics:

  • User-initiated or expected
  • Time-sensitive and actionable
  • Required for the user to complete an action
  • Does not include promotional material or offers
  • Can be sent without explicit opt-in (with limitations)

Examples:

  • Password reset links
  • Order confirmations
  • Account verification
  • OTP/2FA codes
  • Shipping notifications

Analogy: Think of transactional emails for everything that would leave you with a paper receipt in the real world: invoices, parking ticket, booking confirmation, etc.

Marketing Emails

Definition: Emails sent for promotional, advertising, or informational purposes that are not directly related to a specific transaction or legal requirement.

Characteristics:

  • Promotional or informational content
  • Not time-sensitive to complete a transaction
  • Require explicit opt-in (consent)
  • Must include unsubscribe options
  • Subject to stricter compliance requirements

Examples:

  • Newsletters
  • Abandoned cart
  • Product announcements
  • Promotional offers
  • Company updates
  • Educational content

Legal Distinctions

CAN-SPAM Act (US)

Transactional emails:

  • Can be sent without opt-in
  • Must be related to a transaction
  • Cannot contain promotional content (with exceptions)
  • Must identify sender and provide contact information

Marketing emails:

  • Require opt-out mechanism (not opt-in in US)
  • Must include clear sender identification
  • Must include physical mailing address
  • Must honor opt-out requests within 10 business days

GDPR (EU)

Transactional emails:

  • Can be sent based on legitimate interest or contract fulfillment
  • Must be necessary for service delivery
  • Cannot contain marketing content without consent

Marketing emails:

  • Require explicit opt-in consent
  • Must clearly state purpose of data collection
  • Must provide easy unsubscribe
  • Subject to data protection requirements

CASL (Canada)

Transactional emails:

  • Can be sent without consent if related to ongoing business relationship
  • Must be factual and not promotional

Marketing emails:

  • Require express or implied consent
  • Must include unsubscribe mechanism
  • Must identify sender clearly

When to Use Each Type

Use Transactional When:

  • User needs the email to complete an action
  • Email confirms a transaction or account change
  • Email provides security-related information
  • Email is expected based on user action
  • Content is time-sensitive and actionable
  • You're required to serve a notification for compliance

Use Marketing When:

  • Promoting products or services
  • Sending newsletters or updates
  • Sharing educational content
  • Announcing features or company news
  • Content is not required for a transaction

Hybrid Emails: The Gray Area

Some emails mix transactional and marketing content. This isn't best practice and should be avoided.

Best practice: Keep transactional and marketing separate.

Example of problematic hybrid:

  • Newsletter (marketing) with a small order status update (transactional)

Transactional Email Catalog

For a complete catalog of transactional emails and recommended combinations by app type, see Transactional Email Catalog.

Quick reference - Essential emails for most apps:

  1. Email verification - Required for account creation
  2. Password reset - Required for account recovery
  3. Welcome email - Good user experience

The catalog includes detailed guidance for:

  • Authentication-focused apps
  • Newsletter / content platforms
  • E-commerce / marketplaces
  • SaaS / subscription services
  • Financial / fintech apps
  • Social / community platforms
  • Developer tools / API platforms
  • Healthcare / HIPAA-compliant apps

Sending Infrastructure

Separate subdomains

Best practice: Use separate sending subdomains for transactional and marketing emails.

Benefits:

  • Protect transactional deliverability
  • Different authentication domains
  • Independent reputation
  • Easier compliance management

Implementation:

  • Use different subdomains (e.g., t.example.com for transactional, m.example.com for marketing)

Email Service Considerations

Choose an email service that:

  • Provides reliable delivery for transactional emails
  • Offers separate sending domains
  • Has good API for programmatic sending
  • Provides webhooks for delivery events
  • Supports authentication setup (SPF, DKIM, DMARC)

Services like Resend are designed for transactional emails and provide the infrastructure and tools needed for reliable delivery. They also offer powerful marketing features.

Related Topics

Source: SKILL.md on GitHub

No alerts16d4 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill is a comprehensive knowledge base for email best practices, including deliverability, accessibility, compliance, and reliability. It contains educational content and code examples for developers. No malicious patterns or security risks were detected.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 376d1c3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 4 months ago
Other metadata
metadata
{
  "author": "Resend",
  "version": "1.0.2",
  "homepage": "https://resend.com/agent-skills",
  "source": "https://github.com/resend/email-best-practices",
  "openclaw": {
    "links": {
      "repository": "https://github.com/resend/email-best-practices",
      "documentation": "https://resend.com/docs/email-best-practices-skill"
    }
  }
}
  • email
  • transactional
  • marketing
  • deliverability
  • spf-dkim-dmarc
  • compliance
  • webhooks
  • accessibility
  • list-management
  • resend

README badge

README badge for resend/resend-skills/email-best-practices

Provides decision trees and reference guides for deliverability (SPF/DKIM/DMARC), compliance (CAN-SPAM/GDPR/CASL), transactional vs marketing email classification, webhook handling, list management, and accessibility (alt text, headings, contrast). Targets teams building email features with Resend or similar transactional email APIs.

Generated from the current SKILL.md.

Does this skill cover setting up SPF, DKIM, and DMARC?
Yes. The Deliverability section covers authentication setup and is the first step recommended for fixing spam issues, as unauthenticated emails are commonly rejected by Gmail and Yahoo.
What compliance standards does this skill address?
It covers CAN-SPAM, GDPR, and CASL requirements, with a dedicated Compliance section for legal obligations around email capture and marketing sends.
Does this skill include guidance on making emails accessible?
Yes. The Accessibility section covers screen reader support, alt text, headings, contrast requirements, and proper HTML structure for inclusive email design.
How does this skill handle bounces and list hygiene?
The List Management section covers bounce handling, suppression list updates, and list hygiene jobs. Webhooks & Events section covers processing delivery events to track bounces and complaints.
Does this skill cover retry logic and idempotent sending?
Yes. The Sending Reliability section covers retry strategy, idempotency, and error handling for production-ready email sending.

Generated from the current SKILL.md. These answers refresh after source changes.