With scheduling you can send large volumes of email in queued batches or target individual recipients by specifying a custom UNIX timestamp parameter. Using the parameters defined below, you can queue batches of emails targeting individual recipients.

Emails can be scheduled up to 72 hours in advance. However, this scheduling constraint does not apply to campaigns sent via Marketing Campaigns.

This parameter allows SendGrid to begin processing a customer’s email requests before sending. SendGrid will then queue those messages and release them when the timestamp is exceeded. This technique allows for a more efficient way to distribute large email requests and can improve overall mail delivery time performance. This functionality:

  • Improves efficiency of processing and distributing large volumes of email.
  • Reduces email pre-processing time.
  • Enables you to time email arrival to increase open rates.
  • Is available for free to all SendGrid customers.

Scheduled sends can be cancelled, if you include a batch ID with your send. For more information, check out Cancel Scheduled Sends!

Using both send_at and send_each_at is not valid and will cause your request to be dropped.

Send At

To schedule a send request for a large batch of emails use the send_at parameter which will send all emails at approximately the same time. send_at is a UNIX timestamp.

Example of send_at email header

1
2
3
{
  "send_at": 1409348513
}

Send Each At

To schedule a send request for individual recipients; use send_each_at to send emails to each recipient at the specified time. send_each_at is a sequence of UNIX timestamps, provided as an array. There must be one timestamp per email you wish to send.

Example of send_each_at email header

1
2
3
4
5
6
7
8
9
10
11
12
{
  "to": [
    "<ben@example.com>",
    "john@example.com",
    "mike@example.com"
  ],
  "send_each_at": [
    1409348513,
    1409348514,
    1409348515
  ]
}

To allow for the cancellation of a scheduled send, you must include a batch_id with your send. The endpoint for cancellation needs a batch_id to cancel with. To generate a valid batch_id, use the batch id generation endpoint. A batch_id is valid for 10 days (864,000 seconds) after generation.

Example of including a batch_id

1
2
3
4
5
6
7
8
9
{
  "to": [
    "<ben@example.com>",
    "john@example.com",
    "mike@example.com"
  ],
  "send_at": 1409348513,
  "batch_id": "MWQxZmIyODYtNjE1Ni0xMWU1LWI3ZTUtMDgwMDI3OGJkMmY2LWEzMmViMjYxMw"
}