Idempotency for batch emails

Prevent duplicate emails by using idempotency keys in batch transactional email requests

When sending batch transactional emails, duplicate requests can cause the same emails to be sent multiple times. Use idempotency to ensure that identical requests are processed only once, preventing duplicate deliveries to recipients.

How idempotency works

To enable idempotency, include an idempotencyKey header in your request. The API processes a request only once per unique key, ignoring subsequent requests with the same key within the time-to-live (TTL) period.

The idempotencyKey must be a UUID (Universally Unique Identifier). Generate a unique key for each distinct batch request. If you need to retry the exact same request, reuse the same key.

1 "headers": {
2     "idempotencyKey": "abcdef-123y-234f-567h-897y"
3 }

Example request

A complete request using the idempotency key:

$ curl --request POST \
>      --url https://api.brevo.com/v3/smtp/email \
>      --header 'Accept: application/json' \
>      --header 'Content-Type: application/json' \
>      --header 'api-key: YOUR_API_KEY' \
>      --data '{
>      "sender": {
>           "name": "Ann",
>           "email": "example@brevo.com"
>      },
>      "to": [
>           {
>                "email": "example2@brevo.com",
>                "name": "Jenny"
>           }
>      ],
>      "headers": {
>           "idempotencyKey": "b52dbf-81dd-4a08-b807-085c"
>      },
>      "subject": "This is a unique email",
>      "templateId": 1
> }'

Time-to-live and error handling

The TTL for idempotencyKey is 30 minutes. After the TTL expires, you can reuse the same key for a new request.

If you submit a request with an idempotencyKey that was used within the last 30 minutes, the API returns a duplicate_parameter error and does not process the request. This prevents duplicate emails from being sent.

Using idempotency with message versions

Idempotency works with messageVersions for sending personalized batches. The same idempotency key applies to the entire batch, regardless of how many versions are included.

1 {
2     "sender": {
3         "email": "sender@example.com",
4         "name": "Brevo"
5     },
6     "subject": "This is my default subject line",
7     "htmlContent": "<!DOCTYPE html><html><body><p>{{params.greeting}}</p></body></html>",
8     "headers": {
9         "idempotencyKey": "b530bf-810d-4a08-b807-075c"
10     },
11     "params": {
12         "greeting": "This is my default greeting",
13         "headline": "This is my default headline"
14     },
15     "messageVersions": [
16         {
17             "to": [
18                 {
19                     "email": "bob@example.com",
20                     "name": "Bob Anderson"
21                 },
22                 {
23                     "email": "anne@example.com",
24                     "name": "Anne Smith"
25                 }
26             ],
27             "params": {
28                 "greeting": "Welcome onboard!",
29                 "headline": "Be Ready for Takeoff."
30             },
31             "subject": "We are happy to be working with you"
32         },
33         {
34             "to": [
35                 {
36                     "email": "jim@example.com",
37                     "name": "Jim Stevens"
38                 },
39                 {
40                     "email": "mark@example.com",
41                     "name": "Mark Payton"
42                 },
43                 {
44                     "email": "andrea@example.com",
45                     "name": "Andrea Wallace"
46                 }
47             ],
48             "params": {
49                 "greeting": "Hello there..."
50             }
51         }
52     ]
53 }

When using messageVersions with an idempotency key, the API returns one message ID per version. In the example above, the response contains two message IDs — one per message version.

1	"headers": {
2	"idempotencyKey": "abcdef-123y-234f-567h-897y"
3	}

$	curl --request POST \
>	--url https://api.brevo.com/v3/smtp/email \
>	--header 'Accept: application/json' \
>	--header 'Content-Type: application/json' \
>	--header 'api-key: YOUR_API_KEY' \
>	--data '{
>	"sender": {
>	"name": "Ann",
>	"email": "example@brevo.com"
>	},
>	"to": [
>	{
>	"email": "example2@brevo.com",
>	"name": "Jenny"
>	}
>	],
>	"headers": {
>	"idempotencyKey": "b52dbf-81dd-4a08-b807-085c"
>	},
>	"subject": "This is a unique email",
>	"templateId": 1
>	}'

1	{
2	"sender": {
3	"email": "sender@example.com",
4	"name": "Brevo"
5	},
6	"subject": "This is my default subject line",
7	"htmlContent": "<!DOCTYPE html><html><body><p>{{params.greeting}}</p></body></html>",
8	"headers": {
9	"idempotencyKey": "b530bf-810d-4a08-b807-075c"
10	},
11	"params": {
12	"greeting": "This is my default greeting",
13	"headline": "This is my default headline"
14	},
15	"messageVersions": [
16	{
17	"to": [
18	{
19	"email": "bob@example.com",
20	"name": "Bob Anderson"
21	},
22	{
23	"email": "anne@example.com",
24	"name": "Anne Smith"
25	}
26	],
27	"params": {
28	"greeting": "Welcome onboard!",
29	"headline": "Be Ready for Takeoff."
30	},
31	"subject": "We are happy to be working with you"
32	},
33	{
34	"to": [
35	{
36	"email": "jim@example.com",
37	"name": "Jim Stevens"
38	},
39	{
40	"email": "mark@example.com",
41	"name": "Mark Payton"
42	},
43	{
44	"email": "andrea@example.com",
45	"name": "Andrea Wallace"
46	}
47	],
48	"params": {
49	"greeting": "Hello there..."
50	}
51	}
52	]
53	}