Batch Idempotency Keys

We recently enabled idempotency keys for the /emails endpoint to help you avoid sending duplicate emails.

An idempotency key is a unique identifier for a specific email request. It ensures that the same email request is processed only once, even if the request is sent multiple times.

Idempotency for batch emails

While useful for single transactional emails, idempotency keys are also useful for sending emails in bulk.

Our bulk endpoint enables up to 100 emails to be sent in a single API call. Today, we're excited to announce that the /emails/batch endpoint now supports idempotency keys.

# First request sent
curl -X POST 'http://localhost:3000/emails/batch' \
  -H 'Authorization: re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: team-quota/123456789' ...

# Second request sent with the same idempotency key and parameters
curl -X POST 'http://localhost:3000/emails/batch' \
  -H 'Authorization: re_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: team-quota/123456789' ...

# Both return the same email ids
{
  data: [
    {"id":"49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"},
    {"id":"c11a2b12-c014-41df-9386-2b9b8240cbd5"}
  ]
}

How does it work?

Idempotency keys can be up to 256 characters and should be unique per API request.

We keep idempotency keys in our system for 24 hours. This should give you an ample window to retry any failed processes on your end without having to keep track of the sent status.

If you have multiple events related to an entity in your system, you can format your idempotency keys to take advantage of that entity's ID (i.e., <event-type>/<entity-id>). For batch sends, choose a key that represents the whole batch, like a team, workspace, or project (i.e., team-quota/123456789).

How to use idempotency keys for batch sends

As with all new features, we're supporting idempotency keys in all of our SDKs.

import { Resend } from 'resend';

const resend = new Resend('re_xxxxxxxxx');

await resend.batch.send(
  [
    {
      from: 'Acme <onboarding@resend.dev>',
      to: ['foo@gmail.com'],
      subject: 'hello world',
      html: '<h1>it works!</h1>',
    },
    {
      from: 'Acme <onboarding@resend.dev>',
      to: ['bar@outlook.com'],
      subject: 'world hello',
      html: '<p>it works!</p>',
    },
  ],
  {
    idempotencyKey: 'team-quota/123456789',
  },
);

Future improvements

We look forward to adding additional features like automatic retries and more. For more details, see our idempotency documentation.