/resend

name: resend
description: Use when working with the Resend email API — sending transactional emails (single or batch), receiving inbound emails via webhooks, managing email templates, tracking delivery events, managing domains, contacts, broadcasts, webhooks, API keys, automations, events, viewing API request logs, checking account usage and quotas, or setting up the Resend SDK. Always use this skill when the user mentions Resend, even for simple tasks like "send an email with Resend" — the skill contains critical gotchas (idempotency keys, webhook verification, template variable syntax) that prevent common production issues.
license: MIT
metadata:
    author: resend
    version: "3.12.0"
    homepage: https://resend.com/agent-skills
    source: https://github.com/resend/resend-skills
    openclaw:
        primaryEnv: RESEND_API_KEY
        requires:
            env:
                - RESEND_API_KEY
        envVars:
            - name: RESEND_API_KEY
              required: true
              description: Resend API key for sending and receiving emails
            - name: RESEND_WEBHOOK_SECRET
              required: false
              description: Webhook signing secret for verifying event payloads
        links:
            repository: https://github.com/resend/resend-skills
            documentation: https://resend.com/docs/resend-skill
inputs:
    - name: RESEND_API_KEY
      description: Resend API key for sending and receiving emails. Get yours at https://resend.com/api-keys
      required: true
    - name: RESEND_WEBHOOK_SECRET
      description: Webhook signing secret for verifying event payloads. Found in the Resend dashboard under Webhooks after creating an endpoint.
      required: false
references:
    - sending
    - receiving.md
    - templates.md
    - webhooks.md
    - domains.md
    - contacts.md
    - broadcasts.md
    - api-keys.md
    - logs.md
    - contact-properties.md
    - segments.md
    - topics.md
    - automations.md
    - events.md
    - usage.md
    - installation.md
    - fetch-all-templates.mjs

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 <onboarding@resend.dev>',
    to: ['delivered@resend.dev'],
    subject: 'Hello World',
    html: '<p>Email body here</p>',
  },
  { 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 <onboarding@resend.dev>",
    "to": ["delivered@resend.dev"],
    "subject": "Hello World",
    "html": "<p>Email body here</p>",
}, 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)** | `<event-type>/<entity-id>` (e.g., `welcome-email/user-123`) | | **Format (batch)** | `batch-<event-type>/<batch-id>` (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, retrieve metrics** | [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, ret