Canceling a scheduled send

To batch emails for later sending, the SendGrid API v3 provides a group of endpoints. To define a batch, you need to create a batch ID, then assign that ID to one or more messages. Once you define a batch, you can pause or cancel sending that batch using the API.

To create a batch ID via the SendGrid API v3, send a POST /v3/mail/batch request.

1
curl --request POST "https://api.sendgrid.com/v3/mail/batch" \
2
     --header 'Accept: application/json' \
3
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
4
     --header 'Content-Type: application/json'

A successful call returns an HTTP 201 Created response header and your batch ID in a JSON block.

1
{
2
  "batch_id": "YOUR_BATCH_ID"
3
}

To schedule an email via the SendGrid API v3, make a POST /v3/mail/send request. This request must include two parameters:

• The generated batch ID (batch_id) you created in the preceeding section.
• A UNIX timestamp (sent_at) for when you want this batch sent.

1
curl --request POST "https://api.sendgrid.com/v3/mail/send" \
2
     --header 'Accept: application/json' \
3
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
4
     --header 'Content-Type: application/json' \
5
     --data '{
6
         "personalizations": [{
7
           "to": [ { "email": "john@example.com" } ],
8
           "subject": "Hello, World!" } ],
9
           "from": { "email": "from_address@example.com" },
10
           "content": [ { "type": "text/plain", "value": "Hello, World!" } ],
11
           "send_at": 1484913600,
12
           "batch_id": "YOUR_BATCH_ID"
13
       }'

A successful call returns an HTTP 202 Accepted response header and no response body.

Twilio SendGrid recommends scheduling mail for "off-peak" times. As many senders schedule emails at the top of the hour or half hour, avoid those times when scheduling your batch. An example would be scheduling your send at 10:53 AM. This can lower deferral rates because your batch won't cross our servers when everyone else's mail does.

To schedule an email via the SendGrid API v3, make a POST /v3/user/scheduled_sends request. You can pause or cancel a send no later than 10 minutes before the scheduled send time.

1
curl --request POST "https://api.sendgrid.com/v3/user/scheduled_sends" \
2
     --header 'Accept: application/json' \
3
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
4
     --header 'Content-Type: application/json' \
5
     --data '{"batch_id": "YOUR_BATCH_ID", "status": "pause"}'

1
curl --request POST "https://api.sendgrid.com/v3/user/scheduled_sends" \
2
     --header 'Accept: application/json' \
3
     --header "Authorization: Bearer $SENDGRID_API_KEY" \
4
     --header "Content-Type: application/json" \
5
     --data '{"batch_id": "YOUR_BATCH_ID", "status": "cancel"}'

To discover additional features of this API, consult the Cancel Scheduled Sends API reference.

You can cancel a marketing campaign using the SendGrid UI. To cancel a legacy marketing campaign, you need to use the API.

If you scheduled a specific time to send your campaign, you can remove it from your schedule. You might do so to make changes or reschedule the campaign.

1. Click Marketing Campaigns in the left-side navigation menu.
2. Click Single Sends.
3. Next to the Single Send you want to stop, click the dropdown menu and select Unschedule.

To remove a campaign from your schedule, make a DELETE/v3/campaigns/{campaign_id}/schedules request.

The endpoint includes {campaign_id} as a path parameter. This ID identifies the campaign you want to unschedule.

1
curl --request DELETE "https://api.sendgrid.com/v3/campaigns/42/schedules" \
2
     --header "Authorization: Bearer $SENDGRID_API_KEY"

A successful unschedule returns an HTTP 204 No Content header.