Batch IDs

Generate a new Batch ID to associate with scheduled sends. A Batch ID is good for 864,000 seconds from creation -- 10 days.

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"
}
Validate whether or not a batch id is valid for the authenticating account.

Validate Batch ID [GET]

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

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 Cancelled and Paused 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"
  }
]

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 state of a scheduled send [DELETE]

Delete the cancellation/pause state of a scheduled send. Any messages still in the sending queue with this Batch ID will revert to an active state, and delivery will be attempted when their send_at value is reached. Any paused messages past their scheduled send time will be attempted to be delivered immediately. Any cancelled messages past their scheduled sent time will be dropped.

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