Scheduling Parameters

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 queues the messages and releases them when the timestamp indicates. 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.

Cancel Scheduled sends by including a batch ID with your send. For more information, check out Cancel Scheduled Sends!

When passing send_at or send_each_at please make sure to only use UNIX timestamps passed as integers, as shown in our examples. Any other type could result in unintended behavior.

Using both send_at and send_each_at is not valid. Setting both causes 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

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

{
  "to": [
    "ben@example.com",
    "john@example.com",
    "mikeexampexample@example.com",
    "example@example.com",
    "example@example.com",
    "example@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. 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

{
  "to": [
    "ben@example.com",
    "john@example.com",
    "mikeexampexample@example.com",
    "example@example.com",
    "example@example.com",
    "example@example.com"
  ],
  "send_at": 1409348513,
  "batch_id": "MWQxZmIyODYtNjE1Ni0xMWU1LWI3ZTUtMDgwMDI3OGJkMmY2LWEzMmViMjYxMw"
}

Additional Resources

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.