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

Delete the cancellation/pause 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 "past due" messages (such as those that were paused) will be attempted to be delivered immediately.

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