Idempotency in batch emails

This is an improvement over the basic batch sending transactional emails. Lets consider a case, where you are sending batches of emails and the same kind of Transactional emails are sent twice, so to prevent this we use Idempotency. Idempotency would process the request for Transactional emails just once, so that repeated requests or email are not sent to the recipients.

This requires having another parameter in the batch sending Transactional email endpoint. You can add an additional header as a parameter with the keyword idempotencyKey.

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

The above idempotencyKey is a UUID key which is a unique random number set by the user everytime to implement Idempotency. The cURL request is mentioned below.

curl --request POST \
     --url https://api.sendinblue.com/v3/smtp/email \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "sender": {
          "name": "Ann",
          "email": "[email protected]"
     },
     "to": [
          {
               "email": "[email protected]",
               "name": "Jenny"
          }
     ],
     "headers": {
          "idempotencyKey": "b52dbf-81dd-4a08-b807-085c" -----> New attribute πŸŽ‰πŸŽ‰πŸŽ‰ !
     },
     "subject": "This is a unique email",
     "templateId": 1
}
'

The TTL for the idempotencyKey is 30 minutes.

πŸ“˜

The endpoint would not accept the entry for the same idempotencyKey as it accepts one key only once and the request will not run. The API will throw the duplicate_parameter error code.

Idempotency in different messageVersions

Idempotency also works with different messageVersions as depicted below in the payload.

{
    "sender": {
        "email": "[email protected]",
        "name": "Brevo"
    },
    "subject": "This is my default subject line",
    "htmlContent": "<!DOCTYPE html><html><body><p>{{params.greeting}}</p></body></html>",
    "headers": {
        "idempotencyKey": "b530bf-810d-4a08-b807-075c"
    },
    "params": {
        "greeting": "This is my default greeting",
        "headline": "This is my default headline"
    },
    "messageVersions": [
        //Definition for Message Version 1 
        {
            "to": [
                {
                    "email": "[email protected]",
                    "name": "Bob Anderson"
                },
                {
                    "email": "[email protected]",
                    "name": "Anne Smith"
                }
            ],
            "params": {
                "greeting": "Welcome onboard!",
                "headline": "Be Ready for Takeoff."
            },
            "subject": "We are happy to be working with you"
        },
        // Definition for Message Version 2
        {
            "to": [
                {
                    "email": "[email protected]",
                    "name": "Jim Stevens"
                },
                {
                    "email": "[email protected]",
                    "name": "Mark Payton"
                },
                {
                    "email": "[email protected]",
                    "name": "Andrea Wallace"
                }
            ],
            "params": {
                "greeting": "Hello there..."
            }
        }
    ]
}

There will be two message ids in the response after the request runs successfully.