Resend API

Resend API

Use this skill for tasks that specifically involve Resend's API, SDKs, webhook model, receiving API, or official agent-facing tooling. Do not use it for generic email-platform advice unless the user is clearly working with Resend.

Read only what you need

Start with the smallest relevant file instead of loading everything.

• references/core-reference.md — auth, headers, rate limits, pagination, idempotency, error triage
• references/sending-and-templates.md — transactional sends, batch sends, scheduling, templates
• references/domains-and-api-keys.md — verified domains, DNS records, regions, tracking, key scope
• references/contacts-broadcasts-and-subscriptions.md — contacts, segments, topics, properties, broadcasts
• references/webhooks-inbound-and-beta.md — webhook verification, receiving, replay/retry, workflows, events
• assets/endpoint-catalog.json — compact stable-endpoint catalogue plus beta notes
• assets/resend-openapi.yaml — raw stable OpenAPI snapshot for deeper schema inspection
• assets/*.json — reusable payload templates for common operations

Quick routing

Choose the product primitive before generating code or making live calls.

1. Single transactional email → POST /emails
2. Many distinct sends in one call → POST /emails/batch
3. Campaign to a segment or list → Broadcasts + Segments + Topics
4. Reusable content → Templates
5. Verified sender domain or receiving domain → Domains
6. Scoped credentials → API Keys
7. Subscriber model and profile data → Contacts, Topics, Contact Properties, Segments
8. Inbound email processing → Receiving Emails API + email.received webhook
9. Event delivery to your app → Webhooks
10. Custom event-driven automations → Workflows + Events, but treat them as beta/private alpha

Workflow

1) Identify the job type

Classify the request first:

• Code generation — add or edit Resend integration code in an existing project
• Live API execution — make a real call against a Resend account
• Debugging — explain an error, fix a payload, or diagnose a failed flow
• Architecture — choose between Resend features and design the right flow

2) Choose the best execution surface

Prefer the most native surface for the user's environment:

• If the project already uses an official Resend SDK, generate or modify code in that language.
• If the user wants a reproducible example or is stack-agnostic, prefer raw REST or cURL.
• If the environment already has the official Resend MCP server installed, it is fine to use it for live operations, but still follow the payload and workflow guidance in this skill.

3) Before any live request

Always do these checks for real API calls:

1. Load references/core-reference.md.
2. Confirm RESEND_API_KEY is present.
3. Use python3 scripts/resend_api.py schema METHOD PATH if you need an offline schema summary.
4. Use python3 scripts/resend_api.py request ... or an equivalent HTTP client for the live call.
5. Include Authorization: Bearer ... and a User-Agent.
6. For POST /emails and POST /emails/batch, add an Idempotency-Key before any retry.
7. Avoid automatic retries on unsafe mutations unless idempotency is in place.

4) Generate code or payloads

When writing code or examples:

• Keep them minimal, runnable, and explicit about required environment variables.
• Use absolute ISO 8601 timestamps for scheduling.
• Call out feature limits that affect the request shape.
• Mention the exact endpoint(s), payload keys, and next verification step.
• Use the sample payload files in assets/ as a starting point when helpful.

5) Debug in the right order

When something fails, inspect these first:

1. Wrong or missing API key
2. Missing User-Agent on raw HTTP
3. Unverified or test-only sender domain
4. Retried send without idempotency
5. Invalid attachment or from-address format
6. Batch limitations (no attachments, no scheduling)
7. Template not published before send
8. Expecting full inbound message content directly inside the webhook payload

6) Special handling rules

• Scheduling: use an exact timestamp and mention the 72-hour limit.
• Templates: publish before sending; if a template is used, do not also send raw html or text.
• Subscriptions: prefer Topics + Segments over deprecated Audiences.
• Receiving: treat the webhook as the trigger; fetch the full message and attachments via the receiving endpoints.
• Webhooks: verify the signature against the raw request body before parsing JSON.
• Workflows/Events: explicitly label them as beta/private alpha and confirm availability before proposing them as production-critical building blocks.

Bundled tools

scripts/resend_api.py

The bundled helper script is designed for agents:

• catalog — list stable endpoints from the bundled catalogue
• schema — show a compact schema/parameter summary for an endpoint
• request — make a live request with auth, user-agent, JSON parsing, optional pagination, and cautious retry behaviour

Examples:

python3 scripts/resend_api.py catalog --group Emails
python3 scripts/resend_api.py schema POST /emails
python3 scripts/resend_api.py request GET /domains
python3 scripts/resend_api.py request POST /emails --json-file assets/send-email.json --idempotency-key welcome-001
python3 scripts/resend_api.py request GET /emails --paginate --page-limit 3

Common pitfalls

• Using /emails/batch when attachments or scheduling are required
• Forgetting that /emails is the right primitive for one logical email, even when to is an array
• Generating template-send code before the template has been published
• Using deprecated Audiences for new subscriber flows
• Expecting inbound webhooks to include the full raw message or attachment bytes
• Treating beta workflow/event APIs as stable
• Ignoring the default per-team rate limit and flooding the API with parallel requests

Output expectations

When this skill is active, return:

1. The exact endpoint(s) involved
2. The minimal payload or code needed
3. The operational caveats that matter for this task
4. The next verification step, such as listing resources, confirming DNS records, or replaying a webhook

Example prompts this skill should handle

• “Add Resend to this Next.js app and send a scheduled password-reset email”
• “Why is my raw Resend API call returning 403?”
• “Create a verified sending domain in eu-west-1 and turn receiving on”
• “Set up topic-based newsletter subscriptions with contacts and broadcasts”
• “Build an inbound email webhook for support@”
• “Should I use batch sends, broadcasts, or templates for this flow?”
• “Can Resend workflows wait for a custom event and then send follow-ups?”