Schedule transactional emails.

Schedule individual emails or message batches

Scheduling transactional batches comes in handy when you need to send high volumes at the same time. If you hit the transactional endpoint in bursts at the same time you might have trouble handling all the asynchronous calls. Having the possibility to schedule ahead your send out makes it easier to process all the API calls in advance.

In this guide we will cover:

📘

This feature is currently a Beta release

We will soon release an updated version of all our SDKs to support this feature.

Defining scheduled batches

In order to define a scheduled batch or an individual scheduled message you need to make use of the scheduledAt parameter when calling the Send a Transactional Message Endpoint. This parameter takes a standard ISO formatted datetime value to which you can specify a different timezone by adding hours like so :

{
    "sender": {
        "email": "[email protected]"
    },
    "subject": "This is my default subject line",
    "templateId": 43,
    "params": {
        "greeting": "This is the default greeting",
        "headline": "This is the default headline"
    },
    "scheduledAt":"2022-02-28T14:22:51.970+05:30",
    "messageVersions": [
        {
            "to": [
                {
                    "email": "[email protected]"
                }
            ],
            "params": {
                "greeting": "Hello again!",
                "headline": "Take advantage of our summer deals, taylored just for you"
            },
            "subject": "Some deals worth to be looked at!"
        },
        {
            "to": [
                {
                    "email": "[email protected]"
                }
            ],
            "params": {
                "greeting": "Hello Marie, we have prepared some exclusive summer deals for you.",
                "headline": "Some bathing suits you might like"
            },
            "subject": "Marie, new bathing suits are here."
        }
    ]
}

📘

Sending multiple correlated batches at a specific time.

If you would like to execute the transactional endpoint multiple times at a specific time in the future, you can easily track the state of your send outs by simply passing a batchId parameter, this will allow you to link all your messages to a unique identifier and simplify the overall tracking of your batch operations.

We reccomend making use of UUIDs for thus purpose.

batchId: 275d3289-d5cb-4768-9460-a990054b6c81

Retrieve scheduled batches

Here is where we will make use of our earlier dicussed batchId. In the request parameters you simply need to pass your UUID value and you will get an API response containing all the information about the state of your scheduled job.

If you have scheduled a single transactional email , then you can simply pass the messageId you got in the API response from that action.

Endpoint: Fetch scheduled emails by batchId or messageId

GET https://api.sendinblue.com/v3/smtp/emailStatus/{identifier}

📘

The identifier field should be either:

-The messageId, if it's a single email.
-The batchId, if it's a batch sending.

{
  "count": 3,
  "batches": [
    {
      "scheduledAt": "2022-02-28T11:36:43.576000000Z",
      "createdAt": "2022-02-26T11:36:43.576000000Z",
      "status": "queued"
    },
    {
      "scheduledAt": "2022-02-25T11:36:43.576000000Z",
      "createdAt": "2022-02-24T11:36:43.576000000Z",
      "status": "processed"
    },
    {
      "scheduledAt": "2022-02-26T11:36:43.576000000Z",
      "createdAt": "2022-02-25T11:36:43.576000000Z",
      "status": "inProgress"
    }
  ]
}

Canceling scheduled batches

In case you mistakenly scheduled one or a series of batch calls by mistake you can always delete them from the queue by passing the batchId this will abort the scheduled operation once you receive a successful response status.

Endpoint: Delete scheduled emails by batchId or messageId

DELETE https://api.sendinblue.com/v3/smtp/email/{identifier}

📘

The identifier field should be either:

-The messageId, if it's a single email.
-The batchId, if it's a batch sending.

You should receive a 204 status code once the delete action has gone through.


Did this page help you?