Resend

Resend

Quick Send — Node.js

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send(
  {
    from: 'Acme ',
    to: ['delivered@resend.dev'],
    subject: 'Hello World',
    html: 'Email body here',
  },
  { idempotencyKey: `welcome-email/${userId}` }
);

if (error) {
  console.error('Failed:', error.message);
  return;
}
console.log('Sent:', data.id);

Key gotcha: The Resend Node.js SDK does NOT throw exceptions — it returns { data, error }. Always check error explicitly instead of using try/catch for API errors.

Quick Send — Python

import resend
import os

resend.api_key = os.environ["RESEND_API_KEY"]

email = resend.Emails.send({
    "from": "Acme ",
    "to": ["delivered@resend.dev"],
    "subject": "Hello World",
    "html": "Email body here",
}, idempotency_key=f"welcome-email/{user_id}")

Single vs Batch Decision

| Choose | When | |--------|------| | Single (POST /emails) | 1 email, needs attachments, needs scheduling | | Batch (POST /emails/batch) | 2-100 distinct emails, no attachments, no scheduling |

Batch is atomic — if one email fails validation, the entire batch fails. Always validate before sending. Batch does NOT support attachments or scheduled_at.

Idempotency Keys (Critical for Retries)

Prevent duplicate emails when retrying failed requests:

| Key Facts | | |-----------|---| | Format (single) | / (e.g., welcome-email/user-123) | | Format (batch) | batch-/ (e.g., batch-orders/batch-456) | | Expiration | 24 hours | | Max length | 256 characters | | Same key + same payload | Returns original response without resending | | Same key + different payload | Returns 409 error |

Quick Receive (Node.js)

import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

export async function POST(req: Request) {
  const payload = await req.text(); // Must use raw text, not req.json()

  const event = resend.webhooks.verify({
    payload,
    headers: {
      'svix-id': req.headers.get('svix-id'),
      'svix-timestamp': req.headers.get('svix-timestamp'),
      'svix-signature': req.headers.get('svix-signature'),
    },
    secret: process.env.RESEND_WEBHOOK_SECRET,
  });

  if (event.type === 'email.received') {
    // Webhook has metadata only — call API for body
    const { data: email } = await resend.emails.receiving.get(
      event.data.email_id
    );
    console.log(email.text);
  }

  return new Response('OK', { status: 200 });
}

Key gotcha: Webhook payloads do NOT contain the email body. You must call resend.emails.receiving.get() separately.

What Do You Need?

| Task | Reference | |------|-----------| | Send a single email | [sending/overview.md](references/sending/overview.md) — parameters, deliverability, testing | | Send batch emails | [sending/overview.md](references/sending/overview.md) → [sending/batch-email-examples.md](references/sending/batch-email-examples.md) | | Full SDK examples (Node.js, Python, Go, cURL) | [sending/single-email-examples.md](references/sending/single-email-examples.md) | | Idempotency, retries, error handling | [sending/best-practices.md](references/sending/best-practices.md) | | Get, list, reschedule, cancel emails | [sending/email-management.md](references/sending/email-management.md) | | Receive inbound emails | [receiving.md](references/receiving.md) — domain setup, webhooks, attachments | | Manage templates (CRUD, variables) | [templates.md](references/templates.md) — lifecycle, aliases, pagination | | Set up webhooks (events, verification) | [webhooks.md](references/webhooks.md) — verification, CRUD, retry schedule, IP allowlist | | Manage domains (create, verify, claim, DNS) | [domains.md](references/domains.md) — regions, TLS, tracking, claiming, capabilities | | Manage contacts (CRUD, properties) | [contacts.md](references/contacts.md) — segments, topics, custom properties, bulk CSV import | | Send broadcasts (marketing campaigns) | [broadcasts.md](references/broadcasts.md) — lifecycle, scheduling, template variables | | Manage API keys | [api-keys.md](references/api-keys.md) — permission scoping, domain restrictions | | View API request logs | [logs.md](references/logs.md) — list and retrieve API call history, debugging | | Define contact properties | [contact-properties.md](references/contact-properties.md) — custom fields for contacts | | Manage segments (contact groups) | [segments.md](references/segments.md) — broadcast targeting, contact grouping | | Manage topics (subscriptions) | [topics.md](references/topics.md) — opt-in/out preferences, broadcast filtering | | Create automations (event-driven workflows) | [automations.md](references/automations.md) — steps, connections, runs, conditions | | Define and send events (automation triggers) | [events.md](references/events.md) — schemas, payloads, contact association | | Install SDK (8+ languages) | [installation.md](references/installation.md) | | Set up an AI agent inbox | Install the agent-email-inbox skill — covers security levels for untrusted input |

SDK Version Requirements

Always install the latest SDK version. These are the minimum versions for full functionality (sending, receiving, webhook verification):

| Language | Package | Min Version | Install | |----------|---------|-------------|---------| | Node.js | resend | >= 6.14.0 | npm install resend | | Python | resend | >= 2.21.0 | pip install resend | | Go | resend-go/v3 | >= 3.1.0 | go get github.com/resend/resend-go/v3 | | Ruby | resend | >= 1.0.0 | gem install resend | | PHP | resend/resend-php | >= 1.1.0 | composer require resend/resend-php | | Rust | resend-rs | >= 0.20.0 | cargo add resend-rs | | Java | resend-java | >= 4.11.0 | See [installation.md](references/installation.md) | | .NET | Resend | >= 0.2.1 | dotnet add package Resend |

> If the project already has a Resend SDK installed, check the version and upgrade if it's below the minimum. Older SDKs may be missing webhooks.verify(), emails.receiving.get(), or domains.claims.*.

See [installation.md](references/installation.md) for full installation commands, language detection, and cURL fallback.

Common Setup

API Key

Store in environment variable — never hardcode:

export RESEND_API_KEY=re_xxxxxxxxx

Get your key at resend.com/api-keys.

Detect Project Language

Check for these files: package.json (Node.js), requirements.txt/pyproject.toml (Python), go.mod (Go), Gemfile (Ruby), composer.json (PHP), Cargo.toml (Rust), pom.xml/build.gradle (Java), *.csproj (.NET).

Common Mistakes

| # | Mistake | Fix | |---|---------|-----| | 1 | Retrying without idempotency key | Always include idempotency key — prevents duplicate sends on retry. Format: / | | 2 | Not verifying webhook signatures | Always verify with resend.webhooks.verify() — unverified events can't be trusted | | 3 | Template variable name mismatch | Variable names are case-sensitive — must match the template definition exactly. Use triple mustache {{{VAR}}} syntax | | 4 | Expecting email body in webhook payload | Webhooks contain metadata only — call resend.emails.receiving.get() for body content | | 5 | Using try/catch for Node.js SDK errors | SDK returns { data, error } — check error explicitly, don't wrap in try/catch | | 6 | Using batch for emails with attachments | Batch doesn't support attachments — use single sends instead | | 7 | Testing with fake emails (test@gmail.com) | Use delivered@resend.dev — fake addresses bounce and hurt reputation | | 8 | Sending with draft template | Templates must be published before sending — call .publish() first | | 9 | html + template in same send call | Mutually exclusive — remove html/text/react when using template | | 10 | MX record not lowest priority for inbound | Ensure Resend's MX has the lowest number (highest priority) or emails won't route | | 11 | 403 when sending from resend.dev | The default onboarding@resend.dev is a sandbox — it can only deliver to your Resend account email. Verify your own domain first | | 12 | 403 domain mismatch | The from address domain must exactly match a verified domain. Verified send.acme.com but sending from user@acme.com will fail | | 13 | Calling Resend API from the browser (CORS) | The API does not support CORS — this is intentional to protect your API key. Always call from server-side (API routes, serverless functions) | | 14 | 401 restricted_api_key | A sending-only API key was used on a non-sending endpoint (domains, contacts, etc.). Create a full-access key instead |

Cross-Cutting Concerns

Send + Receive Together

Auto-replies, email forwarding, or any receive-then-send workflow requires both capabilities:

1. Set up inbound domain first (see [receiving.md](references/receiving.md))
2. Set up sending (see [sending/overview.md](references/sending/overview.md))
3. Note: batch sending does NOT support attachments or scheduling — use single sends when forwarding with attachments

AI Agent Inbox

If your system processes untrusted email content and takes actions (refunds, database changes, forwarding), install the agent-email-inbox skill. This applies whether or not AI is involved — any system interpreting freeform email content from external senders needs security measures.

Marketing Emails

The sending capabilities in this skill are for transactional email (receipts, confirmations, notifications). For marketing campaigns to large subscriber lists with unsubscribe links and engagement tracking, use Resend Broadcasts — see [broadcasts.md](references/broadcasts.md) for the API.

Domain Warm-up

New domains must gradually increase sending volume. Day 1 limit: ~150 emails (new domain) or ~1,000 (existing domain). See the warm-up schedule in [sending/overview.md](references/sending/overview.md).

Testing

Never test with fake addresses at real email providers (test@gmail.com, fake@outlook.com) — they bounce and destroy sender reputation.

| Address | Result | |---------|--------| | delivered@resend.dev | Simulates successful delivery | | bounced@resend.dev | Simulates hard bounce | | complained@resend.dev | Simulates spam complaint |

Suppression List

Resend automatically suppresses hard-bounced and spam-complained addresses. Sending to suppressed addresses fires the email.suppressed webhook event instead of attempting delivery. Manage in Dashboard → Suppressions.

Webhook Event Types

| Event | Trigger | |-------|---------| | email.sent | API request successful | | email.delivered | Reached recipient's mail server | | email.bounced | Permanently rejected (hard bounce) | | email.complained | Recipient marked as spam | | email.opened / email.clicked | Recipient engagement | | email.delivery_delayed | Soft bounce, Resend retries | | email.received | Inbound email arrived | | domain.* / contact.* | Domain/contact changes |

See [webhooks.md](references/webhooks.md) for full details, signature verification, and retry schedule.

Error Handling Quick Reference

| Code | Action | |------|--------| | 400, 422 | Fix request parameters, don't retry | | 401 | Check API key — restricted_api_key means sending-only key used on non-sending endpoint | | 403 | Verify domain ownership — common causes: resend.dev sandbox, from domain mismatch, unverified domain | | 409 | Idempotency conflict — use new key or fix payload | | 429 | Rate limited — retry with exponential backoff (default rate limit: 2 req/s) | | 500 | Server error — retry with exponential backoff |

Resources

• Resend Documentation
• API Reference
• Dashboard

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: resend
• Source: resend/resend-skills
• License: MIT

Install and usage instructions live in the source repository linked above.