Send Email with Resend

Overview

POST /emails

POST /emails/batch

• 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

• 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
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)

Idempotency Keys

<event-type>/<entity-id>

welcome-email/user-123

batch-<event-type>/<batch-id>

batch-orders/batch-456

Error Handling

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

POST /emails

Required Parameters

from

"Name <email@domain.com>"

to

subject

html

text

Optional Parameters

cc

bcc

reply_to

scheduled_at

attachments

tags

headers

replyTo

reply_to

Minimal Example (Node.js)

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

Batch Email

POST /emails/batch

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

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

Minimal Example (Node.js)

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

Large Batches (100+ Emails)

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

Deliverability

npx skills add resend/email-best-practices

Required

@acme.com

https://acme.com

html

text

support@

Recommended

notifications.acme.com

mail.acme.com

Tracking (Opens & Clicks)

• Marketing emails where engagement metrics matter
• Newsletters and announcements

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

Webhooks (Event Notifications)

email.delivered

email.bounced

email.complained

email.opened

email.clicked

Tags

tags: [
  { name: 'user_id', value: 'usr_123' },
  { name: 'email_type', value: 'welcome' },
  { name: 'plan', value: 'enterprise' }
]

• 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

Templates

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'
    }
  }
});

USER_NAME

user_name

FIRST_NAME

LAST_NAME

EMAIL

RESEND_UNSUBSCRIBE_URL

contact

this

html

text

react

Testing

test@gmail.com

example@outlook.com

fake@yahoo.com

• 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

delivered@resend.dev

bounced@resend.dev

complained@resend.dev

resend.dev

Domain Warm-up

Recommended Schedule

Monitor These Metrics

Suppression List

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

email.suppressed

Common Mistakes

support@

delivered@resend.dev

USER_NAME

user_name

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