Schedule transactional emails.

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:

• Defining scheduled batches
• Retrieving scheduled batches
• Canceling scheduled batches

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 :

Note : You can schedule a message up to 72 hours in the future (from the moment the API request is executed)

{
    "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.brevo.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.brevo.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.