Email Best Practices (Resend)

tl;dr: the opinionated email checklist from Resend, packaged as an Agent Skill and synced from resend/email-best-practices. It’s the only one of the five skills in resend/resend-skills that is provider-neutral — it does not teach the Resend API, it teaches the rules for deliverable, compliant, accessible email. The rest of the bundle (resend, resend-cli, react-email, agent-email-inbox) assumes you already follow these rules.

What it actually does

Fetched SKILL.md (~4 KB) is a router: an ASCII architecture diagram (User → form → validation → double opt-in → consent → suppression check → idempotent send → API → webhooks → suppression list), a 10-row “Need to… → See” quick-reference table, and five “Start Here” paths. All content lives in references/:

Five “Start Here” paths from the skill itself:

• New app. Catalog first → Deliverability before the first send.
• Spam issues. Deliverability first — authentication problems are the most common cause; Gmail / Yahoo reject unauthenticated mail.
• Marketing emails. Email Capture (collect consent) → Compliance (CAN-SPAM/GDPR/CASL) → Marketing Emails best practices.
• Production-ready sending. Sending Reliability (retry + idempotency) → Webhooks & Events → List Management (handle bounces).
• Accessibility. Most emails fail basic checks; the reference covers lang/dir, presentational tables, headings, alt text, <title>, contrast.

The skill ships no executable scripts and no MCP tools — it’s a routing + procedural document. Pairing it with resend (the API skill) or react-email (templates) is the intended usage.

Install

# Wizard — install the bundle, then pick email-best-practices from the picker
npx skills add resend/resend-skills

# Manual — clone and copy the single skill folder
git clone https://github.com/resend/resend-skills
cp -r resend-skills/skills/email-best-practices \
  your-project/.claude/skills/

The same repo ships plugin manifests for three hosts via per-host directories at the root:

• Claude Code — .claude-plugin/marketplace.json and .claude-plugin/plugin.json.
• Cursor — .cursor-plugin/marketplace.json and .cursor-plugin/plugin.json.
• Grok — .grok-plugin/plugin.json.

The README also notes that synced skills (resend-cli, react-email, email-best-practices) are auto-updated from their source repos — do not edit them in resend/resend-skills, edit in the source repo instead. resend and agent-email-inbox are authored in place.

RESEND_API_KEY env var is required by the bundle’s prerequisite, not by this specific skill — but if you install the full bundle, you’ll want it set before the agent can do anything useful.

Gotchas

• Provider-neutral despite the publisher. This skill does not teach the Resend API. It teaches the rules. If you load it expecting Resend-specific code, you’ll get a generic checklist and a redirect to the resend skill or the bundle’s MCP server (mcp.resend.com/mcp, OAuth, streamable HTTP) for tool access.
• Most-common-cause order. Per the skill: “authentication problems are the most common cause [of spam placement]. Gmail / Yahoo reject unauthenticated emails.” If you only read one reference file, read deliverability.md.
• Suppression check before send. The architecture diagram is non-negotiable: idempotent send → webhook events → suppression list. The skill explicitly routes bounces and complaints through the suppression list before the next send — skip the loop and you burn your sender reputation.
• Transactional vs marketing is a routing decision. email-types.md is gatekeeping before transactional-email-catalog.md — sending a marketing blast through the transactional pipeline is the most common CAN-SPAM / Gmail-POSTMASTER violation the skill flags.
• Accessibility ≠ alt text only. references/accessibility.md covers lang / dir, presentational tables, heading order, alt text vs <Img> defaults, WCAG AA 4.5:1 contrast, dark mode preview. Most emails fail at least three of these.
• Double opt-in is non-optional in EU/CA. The diagram puts Double Opt-In before the Ready-to-Send stage. CAN-SPAM, GDPR, and CASL are covered in references/compliance.md.
• Synced from source. Per the resend-skills README, this skill is regenerated from resend/email-best-practices — local edits get overwritten on the next sync. Submit changes upstream.
• sandbox_test untested. We read SKILL.md, the bundle README, and the references index this session. We did not author an end-to-end opt-in + send + webhook loop in the sandbox.
• Static scan verdict: allow. No BLOCK patterns. No REVIEW patterns (all external URLs are github.com or resend.com/docs, both whitelisted). The skill is text-only routing — no scripts/, no mcp.json of its own, no shell-out.

Related

• Redis Semantic Cache (LangCache) — same shelf, different domain; pair this skill with the semantic cache when the LLM-generated body of a transactional email should not be regenerated for every recipient.
• Vercel Find Skills — meta-skill that routes “emails going to spam” or “set up SPF DKIM” to this one instead of guessing.
• Skill Creator (microsoft/skills) — meta-procedure for authoring Agent Skills; useful background if your team forks email-best-practices and wants the token-budget discipline applied to the fork.
• Refactoring UI Audit — operator-authored gold example for the catalog; this page mirrors its structure for the email-deliverability sub-domain.