Bulk send customised transactional emails

When should I use this functionality ?

Let's say you would like to compose a series of transactional messages which use the same transactional template but with dynamic content each. You don't need to call the Send a Transactional Email endpoint multiple times for every version you create, you can instead define up to 100 message versions within the same single call.

📘

Bulk Sending Limits

Note: This feature is currently in beta, so here are some sending limits you might want to consider prior to any integration you create:

  • You can send up to 100 email messages in one single API call.
  • You can call the transactional API call making use of the messageVersions parameter up to 100 times per hour.

What does this mean?

You can call this endpoint 100 times per hour. Each time you call it you can define up to 100 versions to be sent out in a single call.

This means you're allowed to send up to 10 000 email versions in one hour.


Creating a transactional template

In order to create multiple message versions we will need in the first place a transactional template which will be later dynamically defined in the API call. Let's overview how to get our template.

  1. Head to your "Templates" under your Transactional tab and hit "New Template" in the upper right corner.
New Template ButtonNew Template Button

New Template Button



  1. Now we will need to define some default variables for our template. For our purpose, we will just need to add a value to Template Name and Subject Line.



  1. Once we have our template we can work on its design. Here we will set which parts of the template can be dynamic and customizable when building our API call.




We will now change the titles on this template so that we can override them in our API call. The placeholders should also be set to this format: {{ params.<variableName> }}

That's it ! Click on "Save and Activate" in the upper right corner.

You will be redirected to the templates list. Ours should be at the top of the list with an ID (#27). You can copy it, we will need it to build our API call.



🚧

Public Beta Program

We are releasing the bulk sending feature for some of our customers. If you would like to beta test it you can apply here.

Creating the API Call

We will now create the payload for 2 different versions of the template we just created. Each one of them will be defined in a single API request. It would look like this:


Request

curl --request POST \
  --url https://api.sendinblue.com/v3/smtp/email \
  --header 'accept: application/json' \
  --header 'api-key: xxxxxxxxxx' \
  --header 'content-type: application/json'
  --data ...




Payload

{
   "sender":{
      "email":"[email protected]",
      "name":"Sendinblue"
   },
   "subject":"This is my default subject line",
   "templateId":27,
   "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..."
         }
      }
   ]
}

Be sure not to pass an outer to parameter. Every list of recipients should be defined inside each message version.

If you look closely, we have set outside the scope of the messageVersions object global values for subject and params . These will be the default if they are not re defined inside a message version.

For this example we have overridden the value of these variables in such way that for each node inside messageVersion there's a dynamic definition for them.

In the same way you can re define other common used variables such as:

  • cc
  • bcc
  • replyTo
  • subject
  • params

📘

Transactional Attributes

params will always be a custom object where you can define all your transactional attributes. These are the ones which will be later rendered inside the template. For our example we defined as transactional attributes:

  • {{ params.heading }}
  • {{ params.greetings }}

After the call is successfully completed you will get a response containing a list of messageId 's. They match with the number of Message Versions you define in your call.

With these identifiers you can check your transactional logs or webhooks and check the status of your messages.


Response

{
    "messageIds": [
         "[email protected]", // message version 1
         "[email protected]"  // message version 2
    ]
}



The Result

From the previous call, we will get as a result two template versions for templateId #27 . They should look like this:




Message Version 1


To: Bob, Anne
From: Sendinblue
Subject : We are happy to be working with you




Message Version 2


To: Jim, Mark, Andrea
From: Sendinblue
Subject : This is my default subject line



Check the step-by-step recipe:




Did this page help you?