Schedule emails

Scheduling transactional batches is useful when you need to send high volumes at the same time. Hitting the transactional endpoint in bursts can make it hard to handle all the asynchronous calls. Scheduling sends ahead of time makes it easier to process API calls in advance.

This guide covers:

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

Defining scheduled batches

To define a scheduled batch or an individual scheduled message, use the scheduledAt parameter when calling the Send a Transactional Message Endpoint. This parameter takes a standard ISO-formatted datetime value, and you can specify a different timezone by adding hours:

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

1
{
2
    "sender": {
3
        "email": "hello@brevo.com"
4
    },
5
    "subject": "This is my default subject line",
6
    "templateId": 43,
7
    "params": {
8
        "greeting": "This is the default greeting",
9
        "headline": "This is the default headline"
10
    },
11
    "scheduledAt":"2022-02-28T14:22:51.970+05:30",
12
    "messageVersions": [
13
        {
14
            "to": [
15
                {
16
                    "email": "recipient0@brevo.com"
17
                }
18
            ],
19
            "params": {
20
                "greeting": "Hello again!",
21
                "headline": "Take advantage of our summer deals, taylored just for you"
22
            },
23
            "subject": "Some deals worth to be looked at!"
24
        },
25
        {
26
            "to": [
27
                {
28
                    "email": "recipient1@brevo.com"
29
                }
30
            ],
31
            "params": {
32
                "greeting": "Hello Marie, we have prepared some exclusive summer deals for you.",
33
                "headline": "Some bathing suits you might like"
34
            },
35
            "subject": "Marie, new bathing suits are here."
36
        }
37
    ]
38
}

Retrieve scheduled batches

Use the batchId discussed earlier. Pass your UUID value in the request parameters to receive an API response with the state of your scheduled job.

If you scheduled a single transactional email, pass the messageId from the API response of that action.

Endpoint: Fetch scheduled emails by batchId or messageId

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

1
{
2
  "count": 3,
3
  "batches": [
4
    {
5
      "scheduledAt": "2022-02-28T11:36:43.576000000Z",
6
      "createdAt": "2022-02-26T11:36:43.576000000Z",
7
      "status": "queued"
8
    },
9
    {
10
      "scheduledAt": "2022-02-25T11:36:43.576000000Z",
11
      "createdAt": "2022-02-24T11:36:43.576000000Z",
12
      "status": "processed"
13
    },
14
    {
15
      "scheduledAt": "2022-02-26T11:36:43.576000000Z",
16
      "createdAt": "2022-02-25T11:36:43.576000000Z",
17
      "status": "inProgress"
18
    }
19
  ]
20
}

Canceling scheduled batches

If you mistakenly scheduled one or a series of batch calls, delete them from the queue by passing the batchId. The scheduled operation aborts once you receive a successful response status.

Endpoint: Delete scheduled emails by batchId or messageId

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

You receive a 204 status code once the delete action goes through.