Idempotency Keys

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.

​

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.

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.

Here’s how you can add idempotency keys to your emails:

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

Idempotency keys are currently supported on the POST /emails endpoint on the Resend API.

​

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.