---
name: send-email
description: Use when sending transactional emails (welcome messages, order confirmations, password resets, receipts), notifications, or bulk emails via Resend API.
---

# Send Email with Resend

## Overview

Resend provides two endpoints for sending emails:

| Approach   | Endpoint             | Use Case                                                                  |
| ---------- | -------------------- | ------------------------------------------------------------------------- |
| **Single** | `POST /emails`       | Individual transactional emails, emails with attachments, scheduled sends |
| **Batch**  | `POST /emails/batch` | Multiple distinct emails in one request (max 100), bulk notifications     |

**Choose batch when:**

- Sending 2+ distinct emails at once
- Reducing API calls is important (by default, rate limit is 2 requests per second)
- No attachments or scheduling needed

**Choose single when:**

- Sending one email
- Email needs attachments
- Email needs to be scheduled
- Different recipients need different timing

## Quick Start

1. **Detect project language** from config files (package.json, requirements.txt, go.mod, etc.)
2. **Install SDK** (preferred) or use cURL - See [references/installation.md](references/installation.md)
3. **Choose single or batch** based on the decision matrix above
4. **Implement best practices** - Idempotency keys, error handling, retries

## Best Practices (Critical for Production)

Always implement these for production email sending. See [references/best-practices.md](references/best-practices.md) for complete implementations.

### Idempotency Keys

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                                                   |
| **Duplicate payload** | Returns original response without resending                      |
| **Different payload** | Returns 409 error                                                |

### Error Handling

| Code     | Action                                                                                      |
| -------- | ------------------------------------------------------------------------------------------- |
| 400, 422 | Fix request parameters, don't retry                                                         |
| 401, 403 | Check API key / verify domain, don't retry                                                  |
| 409      | Idempotency conflict - use new key or fix payload                                           |
| 429      | Rate limited - retry with exponential backoff (by default, rate limit is 2 requests/second) |
| 500      | Server error - retry with exponential backoff                                               |

### Retry Strategy

- **Backoff:** Exponential (1s, 2s, 4s...)
- **Max retries:** 3-5 for most use cases
- **Only retry:** 429 (rate limit) and 500 (server error)
- **Always use:** Idempotency keys when retrying

## Single Email

**Endpoint:** `POST /emails` (prefer SDK over cURL)

### Required Parameters

| Parameter        | Type     | Description                                         |
| ---------------- | -------- | --------------------------------------------------- |
| `from`           | string   | Sender address. Format: `"Name <email@domain.com>"` |
| `to`             | string[] | Recipient addresses (max 50)                        |
| `subject`        | string   | Email subject line                                  |
| `html` or `text` | string   | Email body content                                  |

### Optional Parameters

| Parameter        | Type     | Description                                      |
| ---------------- | -------- | ------------------------------------------------ |
| `cc`             | string[] | CC recipients                                    |
| `bcc`            | string[] | BCC recipients                                   |
| `reply_to`\*     | string[] | Reply-to addresses                               |
| `scheduled_at`\* | string   | Schedule send time (ISO 8601)                    |
| `attachments`    | array    | File attachments (max 40MB total)                |
| `tags`           | array    | Key/value pairs for tracking (see [Tags](#tags)) |
| `headers`        | object   | Custom headers                                   |

\*Parameter naming varies by SDK (e.g., `replyTo` in Node.js, `reply_to` in Python).

### Minimal Example (Node.js)

```typescript
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);
```

See [references/single-email-examples.md](references/single-email-examples.md) for all SDK implementations with error handling and retry logic.

## Batch Email

**Endpoint:** `POST /emails/batch` (but prefer SDK over cURL)

### Limitations

- **No attachments** - Use single sends for emails with attachments
- **No scheduling** - Use single sends for scheduled emails
- **Atomic** - If one email fails validation, the entire batch fails
- **Max 100 emails** per request
- **Max 50 recipients** per individual email in the batch

### Pre-validation

Since the entire batch fails on any validation error, validate all emails before sending:

- Check required fields (from, to, subject, html/text)
- Validate email formats
- Ensure batch size <= 100

### Minimal Example (Node.js)

```typescript
import { Resend } from "resend";

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

const { data, error } = await resend.batch.send(
  [
    {
      from: "Acme <notifications@acme.com>",
      to: ["delivered@resend.dev"],
      subject: "Order Shipped",
      html: "<p>Your order has shipped!</p>",
    },
    {
      from: "Acme <notifications@acme.com>",
      to: ["delivered@resend.dev"],
      subject: "Order Confirmed",
      html: "<p>Your order is confirmed!</p>",
    },
  ],
  { idempotencyKey: `batch-orders/${batchId}` }
);

if (error) {
  console.error("Batch failed:", error.message);
  return;
}
console.log(
  "Sent:",
  data.map((e) => e.id)
);
```

See [references/batch-email-examples.md](references/batch-email-examples.md) for all SDK implementations with validation, error handling, and retry logic.

## Large Batches (100+ Emails)

For sends larger than 100 emails, chunk into multiple batch requests:

1. **Split into chunks** of 100 emails each
2. **Use unique idempotency keys** per chunk: `<batch-prefix>/chunk-<index>`
3. **Send chunks in parallel** for better throughput
4. **Track results** per chunk to handle partial failures

See [references/batch-email-examples.md](references/batch-email-examples.md) for complete chunking implementations.

## Deliverability

Follow these practices to maximize inbox placement.

For more help with deliverability, install the email-best-practices skill with `npx skills add resend/email-best-practices`.

### Required

| Practice                          | Why                                                                                                                                |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Valid SPF, DKIM, DMARC record** | authenticate the email and prevent spoofing                                                                                        |
| **Links match sending domain**    | If sending from `@acme.com`, link to `https://acme.com` - mismatched domains trigger spam filters                                  |
| **Include plain text version**    | Use both `html` and `text` parameters for accessibility and deliverability (Resend generates a plain text version if not provided) |
| **Avoid "no-reply" addresses**    | Use real addresses (e.g., `support@`) - improves trust signals                                                                     |
| **Keep body under 102KB**         | Gmail clips larger messages                                                                                                        |

### Recommended

| Practice                               | Why                                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Use subdomains**                     | Send transactional from `notifications.acme.com`, marketing from `mail.acme.com` - protects reputation |
| **Disable tracking for transactional** | Open/click tracking can trigger spam filters for password resets, receipts, etc.                       |

## Tracking (Opens & Clicks)

Tracking is configured at the **domain level** in the Resend dashboard, not per-email.

| Setting            | How it works                    | Recommendation                                                  |
| ------------------ | ------------------------------- | --------------------------------------------------------------- |
| **Open tracking**  | Inserts 1x1 transparent pixel   | Disable for transactional emails - can hurt deliverability      |
| **Click tracking** | Rewrites links through redirect | Disable for sensitive emails (password resets, security alerts) |

**When to enable tracking:**

- Marketing emails where engagement metrics matter
- Newsletters and announcements

**When to disable tracking:**

- Transactional emails (receipts, confirmations, password resets)
- Security-sensitive emails
- When maximizing deliverability is priority

Configure via dashboard: Domain → Configuration → Click/Open Tracking

## Webhooks (Event Notifications)

Track email delivery status in real-time using webhooks. Resend sends HTTP POST requests to your endpoint when events occur.

| Event                            | When to use                          |
| -------------------------------- | ------------------------------------ |
| `email.delivered`                | Confirm successful delivery          |
| `email.bounced`                  | Remove from mailing list, alert user |
| `email.complained`               | Unsubscribe user (spam complaint)    |
| `email.opened` / `email.clicked` | Track engagement (marketing only)    |

**CRITICAL: Always verify webhook signatures.** Without verification, attackers can send fake events to your endpoint.

See [references/webhooks.md](references/webhooks.md) for setup, signature verification code, and all event types.

## Tags

Tags are key/value pairs that help you track and filter emails.

```typescript
tags: [
  { name: "user_id", value: "usr_123" },
  { name: "email_type", value: "welcome" },
  { name: "plan", value: "enterprise" },
];
```

**Use cases:**

- Associate emails with customers in your system
- Categorize by email type (welcome, receipt, password-reset)
- Filter emails in the Resend dashboard
- Correlate webhook events back to your application

**Constraints:** Tag names and values can only contain ASCII letters, numbers, underscores, or dashes. Max 256 characters each.

## Templates

Use pre-built templates instead of sending HTML with each request.

```typescript
const { data, error } = await resend.emails.send({
  from: "Acme <hello@acme.com>",
  to: ["delivered@resend.dev"],
  subject: "Welcome!",
  template: {
    id: "tmpl_abc123",
    variables: {
      USER_NAME: "John", // Case-sensitive!
      ORDER_TOTAL: "$99.00",
    },
  },
});
```

**IMPORTANT:** Variable names are **case-sensitive** and must match exactly as defined in the template editor. `USER_NAME` ≠ `user_name`.

| Fact                   | Detail                                                                          |
| ---------------------- | ------------------------------------------------------------------------------- |
| **Max variables**      | 20 per template                                                                 |
| **Reserved names**     | `FIRST_NAME`, `LAST_NAME`, `EMAIL`, `RESEND_UNSUBSCRIBE_URL`, `contact`, `this` |
| **Fallback values**    | Optional - if not set and variable missing, send fails                          |
| **Can't combine with** | `html`, `text`, or `react` parameters                                           |

Templates must be **published** in the dashboard before use. Draft templates won't work.

## Testing

**WARNING: Never test with fake addresses at real email providers.**

Using addresses like `test@gmail.com`, `example@outlook.com`, or `fake@yahoo.com` will:

- **Bounce** - These addresses don't exist
- **Destroy your sender reputation** - High bounce rates trigger spam filters
- **Get your domain blocklisted** - Providers flag domains with high bounce rates

### Safe Testing Options

| Method             | Address                 | Result                        |
| ------------------ | ----------------------- | ----------------------------- |
| **Delivered**      | `delivered@resend.dev`  | Simulates successful delivery |
| **Bounced**        | `bounced@resend.dev`    | Simulates hard bounce         |
| **Complained**     | `complained@resend.dev` | Simulates spam complaint      |
| **Your own email** | Your actual address     | Real delivery test            |

**For development:** Use the `resend.dev` test addresses to simulate different scenarios without affecting your reputation.

**For staging:** Send to real addresses you control (team members, test accounts you own).

## Domain Warm-up

New domains must gradually increase sending volume to establish reputation.

**Why it matters:** Sudden high volume from a new domain triggers spam filters. ISPs expect gradual growth.

### Recommended Schedule

**Existing domain**

| Day | Messages per day    | Messages per hour |
| --- | ------------------- | ----------------- |
| 1   | Up to 1,000 emails  | 100 Maximum       |
| 2   | Up to 2,500 emails  | 300 Maximum       |
| 3   | Up to 5,000 emails  | 600 Maximum       |
| 4   | Up to 5,000 emails  | 800 Maximum       |
| 5   | Up to 7,500 emails  | 1,000 Maximum     |
| 6   | Up to 7,500 emails  | 1,500 Maximum     |
| 7   | Up to 10,000 emails | 2,000 Maximum     |

**New domain**

| Day | Messages per day   | Messages per hour |
| --- | ------------------ | ----------------- |
| 1   | Up to 150 emails   |                   |
| 2   | Up to 250 emails   |                   |
| 3   | Up to 400 emails   |                   |
| 4   | Up to 700 emails   | 50 Maximum        |
| 5   | Up to 1,000 emails | 75 Maximum        |
| 6   | Up to 1,500 emails | 100 Maximum       |
| 7   | Up to 2,000 emails | 150 Maximum       |

### Monitor These Metrics

| Metric                  | Target  | Action if exceeded        |
| ----------------------- | ------- | ------------------------- |
| **Bounce rate**         | < 4%    | Slow down, clean list     |
| **Spam complaint rate** | < 0.08% | Slow down, review content |

**Don't use third-party warm-up services.** Focus on sending relevant content to real, engaged recipients.

## Suppression List

Resend automatically manages a suppression list of addresses that should not receive emails.

**Addresses are added when:**

- Email hard bounces (address doesn't exist)
- Recipient marks email as spam
- You manually add them via dashboard

**What happens:** Resend won't attempt delivery to suppressed addresses. The `email.suppressed` webhook event fires instead.

**Why this matters:** Continuing to send to bounced/complained addresses destroys your reputation. The suppression list protects you automatically.

**Management:** View and manage suppressed addresses in the Resend dashboard under Suppressions.

## Common Mistakes

| Mistake                                   | Fix                                                                              |
| ----------------------------------------- | -------------------------------------------------------------------------------- |
| Retrying without idempotency key          | Always include idempotency key - prevents duplicate sends on retry               |
| Using batch for emails with attachments   | Batch doesn't support attachments - use single sends instead                     |
| Not validating batch before send          | Validate all emails first - one invalid email fails the entire batch             |
| Retrying 400/422 errors                   | These are validation errors - fix the request, don't retry                       |
| Same idempotency key, different payload   | Returns 409 error - use unique key per unique email content                      |
| Tracking enabled for transactional emails | Disable open/click tracking for password resets, receipts - hurts deliverability |
| Using "no-reply" sender address           | Use real address like `support@` - improves trust signals with email providers   |
| Not verifying webhook signatures          | Always verify - attackers can send fake events to your endpoint                  |
| Testing with fake emails (test@gmail.com) | Use `delivered@resend.dev` - fake addresses bounce and hurt reputation           |
| Template variable name mismatch           | Variable names are case-sensitive - `USER_NAME` ≠ `user_name`                    |
| Sending high volume from new domain       | Warm up gradually - sudden spikes trigger spam filters                           |

## Notes

- The `from` address must use a verified domain
- If the sending address cannot receive replies, set the `reply_to` parameter to a valid address.
- Store API key in `RESEND_API_KEY` environment variable
- Node.js SDK supports `react` parameter for React Email components
- Resend returns `error`, `data`, `headers` in the response.
- Data returns `{ id: "email-id" }` on success (single) or array of IDs (batch)
- For marketing campaigns to large lists, use Resend Broadcasts instead