Idempotency Keys

When sending emails at scale, it's important to ensure your emails are sent only once. Emails may accidentally be sent multiple times for a variety of reasons:

• Retry logic that attempts to send an email due to a server error or timeout
• When different services might trigger the same email
• Multiple form submissions on a website
• When handling network failures

Duplicate emails can be frustrating for your users, cost you money, and potentially have other side effects, like when email sending triggers other state changes in your application.

Today, we're excited to announce that the Resend Email API now supports idempotency keys.

What are idempotency keys?

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.

# First request sent
curl -X POST 'http://localhost:3000/emails' \
  -H 'Authorization: re_123456789' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: foo-bar' ...

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

# Both return the same email id
{"id":"49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"}

How does it work?

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.

How to use idempotency keys?

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

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

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.

Future improvements

Adding idempotency keys not only helps you avoid sending duplicate emails, but also enables us to add additional features like automatic retries and more. For more details, see our idempotency documentation.

We are excited to see how idempotency keys empower your sending.