Cancellation of Scheduled Sends

Canceling scheduled send

Batch IDs

If you set the SMTPAPI header batch_id, it allows you to then cancel a scheduled send based on that batch_id by calling the Cancel Scheduled Send endpoint.Generate a new Batch ID to associate with scheduled sends

Generate Batch ID [POST]

Request

1
POST https://api.sendgrid.com/v3/mail/batch HTTP/1.1

Response

1
2
3
4
HTTP/1.1 201
{
  "batch_id": "YOUR_BATCH_ID"
}
Generate a new Batch ID to associate with scheduled sends

Validate Batch ID [GET]

Validate whether or not a batch id is valid
URI Parameter Required Requirements Description
batch_id Yes string The batch ID you want to check
Example: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi

Request

1
GET https://api.sendgrid.com/v3/mail/batch/{batch_id} HTTP/1.1

Response

1
2
3
4
HTTP/1.1 200
{
  "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi"
}
URI Parameter Required Requirements Description
batch_id Yes string The batch ID you want to check
Example: HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi

Request

1
GET https://api.sendgrid.com/v3/mail/batch/{batch_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 400
{
  "errors": [
    {
      "field": null,
      "message": "invalid batch id"
    }
  ]
}

Cancel Scheduled Sends

The Cancel Scheduled Sends feature allows the customer to cancel a scheduled send based on a Batch ID included in the SMTPAPI header. Scheduled sends cancelled less than 10 minutes before the scheduled time are not guaranteed to be cancelled.

You can have no more than 10 different batches, or 10 different groups of emails with each group identified by a unique batch id, pending cancellation at one time.

If you submit a cancel or pause request after the maximum number of cancellation/pause requests has already been reached, an HTTP 400 error will be returned.

Cancel or pause a scheduled send [POST]

Cancel or pause a scheduled send.

Request

1
POST https://api.sendgrid.com/v3/user/scheduled_sends HTTP/1.1
Request Body
1
2
3
4
{
  "batch_id": "YOUR_BATCH_ID",
  "status": "pause"
}

Response

1
HTTP/1.1 201
1
HTTP/1.1 400

Possible 400 Error Messages

Field Error Message
max limit reached
batch_idinvalid batch id
batch_ida status for this batch id exists, try PATCH to update the status

Retrieve all scheduled sends [GET]

Get all cancel/paused scheduled send information.

Request

1
GET https://api.sendgrid.com/v3/user/scheduled_sends HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
HTTP/1.1 200
[
  {
    "batch_id": "BATCH_ID_1",
    "status": "cancel"
  },
  {
    "batch_id": "BATCH_ID_2",
    "status": "pause"
  }
]
A CRUD for managing user scheduled send cancellations

Retrieve a scheduled send [GET]

Get a single cancel/paused scheduled send information.

Request

1
GET https://api.sendgrid.com/v3/user/scheduled_sends/{batch_id} HTTP/1.1

Response

1
2
3
4
5
6
7
HTTP/1.1 200
[
  {
    "batch_id": "BATCH_ID_1",
    "status": "cancel"
  }
]

Update user scheduled send information [PATCH]

Update the status of a scheduled send.

Request

1
PATCH https://api.sendgrid.com/v3/user/scheduled_sends/{batch_id} HTTP/1.1
Request Body
1
2
3
{
  "status": "pause"
}

Response

1
HTTP/1.1 204
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
batch id not found

Delete a cancellation or pause of a scheduled send [DELETE]

Delete the cancellation/pause of a scheduled send.

Request

1
DELETE https://api.sendgrid.com/v3/user/scheduled_sends/{batch_id} HTTP/1.1

Response

1
HTTP/1.1 204
1
HTTP/1.1 404

Possible 404 Error Messages

Field Error Message
batch id not found