Skip to main content
Include an idempotency key in any email requests to ensure that the same email request is processed only once, even if it’s sent multiple times.
Idempotency keys are currently supported on the POST /emails and the POST /emails/batch endpoints on the Resend API.

​
How does it work?

When you send an email with an idempotency key, we check if an email with the same idempotency key has already been sent in the last 24 hours. This is an optional feature that simplifies managing retries on your side. This makes it safe to retry requests that send an email. You don’t have to worry about checking if the original request was sent — you can just make the same request and our API will give the same response, without actually sending the email again.

​
How to use idempotency keys?

Idempotency keys can be up to 256 characters and should be unique per API request. We recommend using a UUID or other string that uniquely identifies that specific email.
If you have multiple events that trigger emails related to a single entity in your system, you can format your idempotency keys to take advantage of that entity’s ID. One idea is to format idempotency keys like <event-type>/<entity-id>, for example welcome-user/123456789. The specific format you use is up to you.
Send the key in the Idempotency-Key HTTP header in your API requests. Our SDKs also provide a convenient way to set this header. If you’re using SMTP, you can set the Resend-Idempotency-Key email header instead. 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.

​
POST /emails endpoint example

await resend.emails.send(
  {
    from: 'Acme <onboarding@resend.dev>',
    to: ['delivered@resend.dev'],
    subject: 'hello world',
    html: '<p>it works!</p>',
  },
  {
    idempotencyKey: 'welcome-user/123456789',
  },
);

​
POST /emails/batch endpoint example

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

​
Possible responses

After checking if an email with the same idempotency key has already been sent, Resend returns one of the following responses:
  • Successful responses will return the email ID of the sent email.
  • Error responses will return one of the following errors:
    • 400: invalid_idempotency_key - the idempotency key has to be between 1-256 characters. You can retry with a valid key or without supplying an idempotency key.
    • 409: invalid_idempotent_request - this idempotency key has already been used on a request that had a different payload. Retrying this request is useless without changing the idempotency key or payload.
    • 409: concurrent_idempotent_requests - another request with the same idempotency key is currently in progress. As it isn’t finished yet, Resend can’t return its original response, but it is safe to retry this request later if needed.