resend-api

What this skill does

# 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:

```bash
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?”