AI onboarding

import { Resend } from 'resend';

const resend = new Resend('YOUR_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);

import { Resend } from 'resend';

const resend = new Resend('YOUR_RESEND_API_KEY');

const { data, error } = await resend.batch.send(
  [
    {
      from: 'Acme <hello@example.com>',
      to: ['delivered@resend.dev'],
      subject: 'Order Shipped',
      html: '<p>Your order has shipped!</p>',
    },
    {
      from: 'Acme <hello@example.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),
);

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 10 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
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.

### 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 10 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      |
| `headers`        | object    | Custom headers                    |

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

### Minimal Example (Node.js)

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
import { Resend } from 'resend';

const resend = new Resend('YOUR_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);
```

## 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 is less than or equal to 100

### Minimal Example (Node.js)

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
import { Resend } from 'resend';

const resend = new Resend('YOUR_RESEND_API_KEY');

const { data, error } = await resend.batch.send(
  [
    {
      from: 'Acme <hello@example.com>',
      to: ['delivered@resend.dev'],
      subject: 'Order Shipped',
      html: '<p>Your order has shipped!</p>',
    },
    {
      from: 'Acme <hello@example.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),
);
```