---
name: resend
description: Use when building email sending features, managing transactional
  and marketing emails, handling inbound email workflows, setting up email
  authentication, or integrating email delivery into applications. Reach for
  this skill when working with email APIs, templates, webhooks, contacts,
  broadcasts, automations, or domain configuration.
metadata:
  mintlify-proj: resend
  version: "1.0"
---

# Resend Skill

## Product summary

Resend is an email API for developers to send transactional and marketing emails programmatically. Use it to send personalized event-driven emails, manage contacts and broadcasts, receive inbound emails, and track delivery metrics. Access Resend via REST API, official SDKs (Node.js, Python, PHP, Ruby, Go, Java, Rust, .NET), CLI, or SMTP. Store your API key as `RESEND_API_KEY` environment variable. Primary docs: https://resend.com/docs

## When to use

Reach for this skill when:
- Sending transactional emails (password resets, order confirmations, notifications)
- Building marketing campaigns with broadcasts and contact segments
- Setting up email authentication (SPF, DKIM, DMARC) for a domain
- Receiving and processing inbound emails via webhooks
- Creating reusable email templates with variables
- Building event-driven automation workflows
- Handling email delivery tracking and bounce management
- Integrating email into a multi-tenant SaaS application
- Debugging email deliverability issues or API errors

## Quick reference

### Essential API endpoints

| Task | Endpoint | Method |
|------|----------|--------|
| Send email | `POST /emails` | REST |
| Send batch (≤100) | `POST /emails/batch` | REST |
| List emails | `GET /emails` | REST |
| Create template | `POST /templates` | REST |
| Send with template | `POST /emails` (with `template_id`) | REST |
| Create domain | `POST /domains` | REST |
| Verify domain | `POST /domains/{id}/verify` | REST |
| Create contact | `POST /contacts` | REST |
| Create segment | `POST /segments` | REST |
| Send broadcast | `POST /broadcasts/{id}/send` | REST |
| Create webhook | `POST /webhooks` | REST |
| Create automation | `POST /automations` | REST |

### CLI commands

```bash
# Authentication
resend login                          # Save API key
resend logout                         # Remove saved key

# Sending
resend emails send --from "..." --to "..." --subject "..." --html "..."
resend emails batch --file emails.json
resend emails list                    # View sent emails
resend emails cancel <id>             # Cancel scheduled email

# Domains
resend domains create --name example.com --region us-east-1
resend domains verify <id>            # Trigger DNS verification
resend domains list                   # View all domains

# Contacts & Segments
resend contacts create --email user@example.com --first-name John
resend segments create --name "VIPs"
resend contacts imports create --file contacts.csv

# Templates
resend templates create --name "Welcome" --react-email ./emails/welcome.tsx
resend templates list
resend templates publish <id>

# Webhooks
resend webhooks create --endpoint https://example.com/webhook --events email.sent email.delivered
resend webhooks listen --url https://public-url.example.com

# Automations
resend automations create --file automation.json
resend automations list
```

### SDK patterns (Node.js)

```javascript
import { Resend } from 'resend';

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

// Send email
const { data, error } = await resend.emails.send({
  from: 'noreply@example.com',
  to: 'user@example.com',
  subject: 'Hello',
  html: '<p>Welcome!</p>',
});

// Send batch
const { data, error } = await resend.emails.sendBatch([
  { from: '...', to: '...', subject: '...', html: '...' },
  { from: '...', to: '...', subject: '...', html: '...' },
]);

// Send with template
const { data, error } = await resend.emails.send({
  from: 'noreply@example.com',
  to: 'user@example.com',
  template_id: 'tmpl_xxxxx',
  props: { name: 'John' },
});
```

### Configuration files

| File | Purpose |
|------|---------|
| `.env` | Store `RESEND_API_KEY` (never commit) |
| `emails.json` | Batch email payload (array of email objects) |
| `automation.json` | Automation workflow definition (steps + connections) |
| `contacts.csv` | Contact import file (email, first_name, last_name columns) |

### Domain setup checklist

1. Add domain in dashboard or via API
2. Copy DNS records (DKIM, SPF) from Resend
3. Add records to your DNS provider
4. Wait for verification (typically 15 min, up to 72 hours)
5. Add DMARC record for authentication
6. Enable receiving (if needed) by adding MX record
7. Configure TLS and tracking (optional)

## Decision guidance

| Scenario | Use | Why |
|----------|-----|-----|
| Send 1–10 emails per request | `POST /emails` (single) | Simpler, immediate response |
| Send 11–100 emails per request | `POST /emails/batch` | Efficient, single API call |
| Send 100+ emails | Batch in loops + rate limiting | Respect 10 req/sec limit |
| Personalized event-driven emails | Transactional API + templates | Fast, reliable, tracked |
| Bulk marketing emails | Broadcasts + segments + topics | Built-in unsubscribe handling |
| Reusable email layouts | Templates with variables | Version control, team collaboration |
| Custom email logic | React Email components | Type-safe, hot reload preview |
| Plain HTML/text emails | `html` or `text` parameter | No build step required |
| Receive emails | Inbound + webhooks | Process incoming mail at your domain |
| Automate workflows | Automations API | Trigger on custom events |
| Track engagement | Webhooks (email.opened, email.clicked) | Real-time delivery insights |
| Suppress bounces | Suppressions API | Maintain list hygiene |

## Workflow

### Sending your first email

1. **Create API key**: Go to https://resend.com/api-keys, click "Create API Key", select "Sending access", copy the key.
2. **Store key**: Add `RESEND_API_KEY=re_xxxxx` to `.env` file (add `.env` to `.gitignore`).
3. **Verify domain**: Go to https://resend.com/domains, click "Add Domain", enter subdomain (e.g., `notifications.example.com`), select region, copy DNS records, add to your DNS provider, wait for verification.
4. **Install SDK**: `npm install resend` (or use your language's SDK).
5. **Send email**: Call `resend.emails.send()` with verified domain in `from` field.
6. **Check logs**: View sent emails in dashboard at https://resend.com/emails.

### Creating and sending with templates

1. **Write template**: Create `emails/welcome.tsx` as React component with props.
2. **Preview locally**: Run `npx react-email dev` to see hot-reload preview.
3. **Upload to Resend**: Run `npx react-email resend` to authenticate and upload.
4. **Get template ID**: Copy ID from dashboard or API response.
5. **Send email**: Call `resend.emails.send()` with `template_id` and `props` object.
6. **Version control**: Templates in dashboard support version history; use API for programmatic updates.

### Setting up inbound email

1. **Enable receiving**: Go to domain details, toggle "Receiving" on, copy MX record value.
2. **Add MX record**: In your DNS provider, add MX record with Resend's value and priority 10.
3. **Create webhook**: Go to https://resend.com/webhooks, click "Add Webhook", enter endpoint URL, select `email.received` event.
4. **Build endpoint**: Create POST route that accepts webhook payload, verify signature with webhook secret.
5. **Retrieve email**: Call `resend.emails.retrieveReceived(id)` to get full email body and headers (webhook only includes metadata).
6. **Process attachments**: Use `resend.emails.listReceivedAttachments(id)` to get attachment metadata and download URLs.

### Building an automation

1. **Define trigger**: Create custom event (e.g., `user.created`) or use existing event type.
2. **Design workflow**: Map steps (condition, delay, send email, update contact, add to segment).
3. **Create automation**: Use dashboard or API with JSON payload defining steps and connections.
4. **Publish template**: Automation can only use published templates.
5. **Send trigger event**: Call `resend.events.send()` with event name and contact ID or email.
6. **Monitor runs**: View execution status and debug failed steps in dashboard.

## Common gotchas

- **Hardcoded API keys**: Never hardcode keys in source. Always use environment variables. If exposed, immediately delete the key and create a new one.
- **Missing User-Agent header**: Direct HTTP requests must include `User-Agent` header or you'll get 403 error 1010. SDKs handle this automatically.
- **Using onboarding@resend.dev in production**: This test domain only works for testing. Always use a verified custom domain in production.
- **Batch validation**: Entire batch fails if any email is invalid. Validate all emails before sending (required fields: `from`, `to`, `subject`, `html` or `text`).
- **Batch size limit**: Maximum 100 emails per batch request. Loop and batch in chunks if sending more.
- **Rate limiting**: Default 10 requests/second per team. Implement exponential backoff on 429 responses. Contact support to increase limit.
- **Event ordering**: Webhook events are not guaranteed in order. Use `created_at` timestamp to sort events after receipt.
- **Webhook signature verification**: Always verify webhook signatures using the signing secret. Some frameworks auto-parse JSON, breaking signature verification—use raw request body.
- **Template variables**: Pass React Email components as function calls (`WelcomeEmail({ name: 'John' })`), not JSX (`<WelcomeEmail name="John" />`).
- **Domain verification delays**: DNS changes can take up to 72 hours to propagate. Use https://dns.email to check record visibility. Click "Restart verification" if stuck.
- **Subdomain vs root domain**: Always verify a subdomain (e.g., `notifications.example.com`) instead of root domain to avoid MX record conflicts.
- **Receiving domain conflicts**: If domain is already registered by another team, use "Claim domain" to transfer it (generates new DKIM keys).
- **Idempotency keys**: Use unique keys (max 256 chars) to prevent duplicate sends. Keys expire after 24 hours.
- **Suppression list**: Bounced and complained emails are auto-suppressed. Check suppression list before sending to avoid wasted API calls.
- **Topic vs segment confusion**: Topics are recipient preferences (shown on unsubscribe page); segments are sender-controlled targeting. Use both together for broadcasts.
- **Attachment size**: Max 40MB per email after Base64 encoding. Attachments not supported in batch sends.
- **Scheduled email failures**: Scheduled emails can fail if API key is deleted, account is under review, or domain is unverified. Check email details for failure reason.

## Verification checklist

Before submitting work with Resend:

- [ ] API key is stored in environment variable, not hardcoded
- [ ] `from` address uses a verified custom domain (not `onboarding@resend.dev` in production)
- [ ] All required fields present: `from`, `to`, `subject`, and either `html` or `text`
- [ ] Email addresses are valid format
- [ ] Batch size is ≤100 emails
- [ ] Webhook endpoint is publicly accessible HTTPS URL
- [ ] Webhook signature verification implemented using raw request body
- [ ] Rate limiting handled with exponential backoff on 429 responses
- [ ] Error handling checks both `data` and `error` in SDK responses
- [ ] Template variables passed as function calls, not JSX
- [ ] Domain is verified and DNS records are propagated (check https://dns.email)
- [ ] Idempotency keys are unique per request (if deduplication needed)
- [ ] Suppression list checked before bulk sends
- [ ] Webhook events sorted by `created_at` if ordering matters
- [ ] Contact imports use correct CSV format or column mapping
- [ ] Automation steps reference published templates only
- [ ] Receiving domain has MX record added and verified

## Resources

- **Full documentation index**: https://resend.com/docs/llms.txt (comprehensive page-by-page navigation for agents)
- **API Reference**: https://resend.com/docs/api-reference/introduction
- **Sending Guide**: https://resend.com/docs/dashboard/emails/introduction
- **Webhooks & Events**: https://resend.com/docs/webhooks/introduction
- **Email Best Practices**: https://resend.com/docs/email-best-practices-skill

---

> For additional documentation and navigation, see: https://resend.com/docs/llms.txt