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.
- Single transactional email →
POST /emails
- Many distinct sends in one call →
POST /emails/batch
- Campaign to a segment or list → Broadcasts + Segments + Topics
- Reusable content → Templates
- Verified sender domain or receiving domain → Domains
- Scoped credentials → API Keys
- Subscriber model and profile data → Contacts, Topics, Contact Properties, Segments
- Inbound email processing → Receiving Emails API +
email.received webhook
- Event delivery to your app → Webhooks
- 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:
- Load
references/core-reference.md.
- Confirm
RESEND_API_KEY is present.
- Use
python3 scripts/resend_api.py schema METHOD PATH if you need an offline schema summary.
- Use
python3 scripts/resend_api.py request ... or an equivalent HTTP client for the live call.
- Include
Authorization: Bearer ... and a User-Agent.
- For
POST /emails and POST /emails/batch, add an Idempotency-Key before any retry.
- 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:
- Wrong or missing API key
- Missing
User-Agent on raw HTTP
- Unverified or test-only sender domain
- Retried send without idempotency
- Invalid attachment or from-address format
- Batch limitations (no attachments, no scheduling)
- Template not published before send
- 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:
- The exact endpoint(s) involved
- The minimal payload or code needed
- The operational caveats that matter for this task
- 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?”
1---
2name: resend-api
3description: "Use this skill when the user wants to integrate with, call, debug, or operate the Resend API or official SDKs/MCP tooling. Covers sending and scheduling emails, batch sends, templates, domains and DNS verification, API keys, contacts, segments, topics, broadcasts, inbound email, webhooks, receiving attachments, and Resend workflows/events. Also use it when the user mentions Resend, resend.emails.send, verified domains, email.received, broadcast campaigns, template publishing, or needs help choosing between single email, batch, broadcast, inbound, or workflow patterns."
4compatibility: "Designed for skills-compatible coding agents. Live API calls require network access and a RESEND_API_KEY. The bundled helper script uses Python 3.10+ standard library only."
5metadata:
6 author: OpenAI
7 version: "1.0.0"
8 source: https://skillmd.com/skills/tristanmanchester/resend-api
9 upstream: "https://resend.com/docs/api-reference/introduction"
10 last-reviewed: "2026-03-13"
11---
12
13
14# Resend API
15
16Use this skill for tasks that specifically involve Resend's API, SDKs, webhook model, receiving
17API, or official agent-facing tooling. Do **not** use it for generic email-platform advice unless
18the user is clearly working with Resend.
19
20## Read only what you need
21
22Start with the smallest relevant file instead of loading everything.
23
24- `references/core-reference.md` — auth, headers, rate limits, pagination, idempotency, error triage
25- `references/sending-and-templates.md` — transactional sends, batch sends, scheduling, templates
26- `references/domains-and-api-keys.md` — verified domains, DNS records, regions, tracking, key scope
27- `references/contacts-broadcasts-and-subscriptions.md` — contacts, segments, topics, properties, broadcasts
28- `references/webhooks-inbound-and-beta.md` — webhook verification, receiving, replay/retry, workflows, events
29- `assets/endpoint-catalog.json` — compact stable-endpoint catalogue plus beta notes
30- `assets/resend-openapi.yaml` — raw stable OpenAPI snapshot for deeper schema inspection
31- `assets/*.json` — reusable payload templates for common operations
32
33## Quick routing
34
35Choose the product primitive before generating code or making live calls.
36
371. **Single transactional email** → `POST /emails`
382. **Many distinct sends in one call** → `POST /emails/batch`
393. **Campaign to a segment or list** → Broadcasts + Segments + Topics
404. **Reusable content** → Templates
415. **Verified sender domain or receiving domain** → Domains
426. **Scoped credentials** → API Keys
437. **Subscriber model and profile data** → Contacts, Topics, Contact Properties, Segments
448. **Inbound email processing** → Receiving Emails API + `email.received` webhook
459. **Event delivery to your app** → Webhooks
4610. **Custom event-driven automations** → Workflows + Events, but treat them as beta/private alpha
47
48## Workflow
49
50### 1) Identify the job type
51
52Classify the request first:
53
54- **Code generation** — add or edit Resend integration code in an existing project
55- **Live API execution** — make a real call against a Resend account
56- **Debugging** — explain an error, fix a payload, or diagnose a failed flow
57- **Architecture** — choose between Resend features and design the right flow
58
59### 2) Choose the best execution surface
60
61Prefer the most native surface for the user's environment:
62
63- If the project already uses an official Resend SDK, generate or modify code in that language.
64- If the user wants a reproducible example or is stack-agnostic, prefer raw REST or cURL.
65- If the environment already has the official Resend MCP server installed, it is fine to use it
66 for live operations, but still follow the payload and workflow guidance in this skill.
67
68### 3) Before any live request
69
70Always do these checks for real API calls:
71
721. Load `references/core-reference.md`.
732. Confirm `RESEND_API_KEY` is present.
743. Use `python3 scripts/resend_api.py schema METHOD PATH` if you need an offline schema summary.
754. Use `python3 scripts/resend_api.py request ...` or an equivalent HTTP client for the live call.
765. Include `Authorization: Bearer ...` and a `User-Agent`.
776. For `POST /emails` and `POST /emails/batch`, add an `Idempotency-Key` before any retry.
787. Avoid automatic retries on unsafe mutations unless idempotency is in place.
79
80### 4) Generate code or payloads
81
82When writing code or examples:
83
84- Keep them minimal, runnable, and explicit about required environment variables.
85- Use absolute ISO 8601 timestamps for scheduling.
86- Call out feature limits that affect the request shape.
87- Mention the exact endpoint(s), payload keys, and next verification step.
88- Use the sample payload files in `assets/` as a starting point when helpful.
89
90### 5) Debug in the right order
91
92When something fails, inspect these first:
93
941. Wrong or missing API key
952. Missing `User-Agent` on raw HTTP
963. Unverified or test-only sender domain
974. Retried send without idempotency
985. Invalid attachment or from-address format
996. Batch limitations (no attachments, no scheduling)
1007. Template not published before send
1018. Expecting full inbound message content directly inside the webhook payload
102
103### 6) Special handling rules
104
105- **Scheduling**: use an exact timestamp and mention the 72-hour limit.
106- **Templates**: publish before sending; if a template is used, do not also send raw `html` or `text`.
107- **Subscriptions**: prefer Topics + Segments over deprecated Audiences.
108- **Receiving**: treat the webhook as the trigger; fetch the full message and attachments via the
109 receiving endpoints.
110- **Webhooks**: verify the signature against the raw request body before parsing JSON.
111- **Workflows/Events**: explicitly label them as beta/private alpha and confirm availability before
112 proposing them as production-critical building blocks.
113
114## Bundled tools
115
116### `scripts/resend_api.py`
117
118The bundled helper script is designed for agents:
119
120- `catalog` — list stable endpoints from the bundled catalogue
121- `schema` — show a compact schema/parameter summary for an endpoint
122- `request` — make a live request with auth, user-agent, JSON parsing, optional pagination, and
123 cautious retry behaviour
124
125Examples:
126
127```bash
128python3 scripts/resend_api.py catalog --group Emails
129python3 scripts/resend_api.py schema POST /emails
130python3 scripts/resend_api.py request GET /domains
131python3 scripts/resend_api.py request POST /emails --json-file assets/send-email.json --idempotency-key welcome-001
132python3 scripts/resend_api.py request GET /emails --paginate --page-limit 3
133```
134
135## Common pitfalls
136
137- Using `/emails/batch` when attachments or scheduling are required
138- Forgetting that `/emails` is the right primitive for one logical email, even when `to` is an array
139- Generating template-send code before the template has been published
140- Using deprecated Audiences for new subscriber flows
141- Expecting inbound webhooks to include the full raw message or attachment bytes
142- Treating beta workflow/event APIs as stable
143- Ignoring the default per-team rate limit and flooding the API with parallel requests
144
145## Output expectations
146
147When this skill is active, return:
148
1491. The **exact endpoint(s)** involved
1502. The **minimal payload or code** needed
1513. The **operational caveats** that matter for this task
1524. The **next verification step**, such as listing resources, confirming DNS records, or replaying
153 a webhook
154
155## Example prompts this skill should handle
156
157- “Add Resend to this Next.js app and send a scheduled password-reset email”
158- “Why is my raw Resend API call returning 403?”
159- “Create a verified sending domain in eu-west-1 and turn receiving on”
160- “Set up topic-based newsletter subscriptions with contacts and broadcasts”
161- “Build an inbound email webhook for support@”
162- “Should I use batch sends, broadcasts, or templates for this flow?”
163- “Can Resend workflows wait for a custom event and then send follow-ups?”