Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Validate batch ID



API Overview

api-overview page anchor

The Cancel Scheduled Sends API allows you to cancel or pause the send of one or more emails using a batch ID.

A batch_id groups multiple scheduled mail/send requests together with the same ID. You can cancel or pause all of the mail/send requests associated with a batch ID up to 10 minutes before the scheduled send time by passing a batch_id to the "Cancel or pause a scheduled send" endpoint.

For a guide on creating a batch_id, assigning it to a scheduled send, and modifying the send, see "Canceling a Scheduled Send".

The Cancel Scheduled Sends API also make it possible to validate a batch_id and retrieve all scheduled sends as an array.

When a batch is canceled, all messages associated with that batch will stay in your sending queue. When their send_at value is reached, they will be discarded.

When a batch is paused, all messages associated with that batch will stay in your sending queue, even after their send_at value has passed. This means you can remove a pause status, and your scheduled send will be delivered once the pause is removed. Any messages left with a pause status that are more than 72 hours old will be discarded as Expired.


GET/v3/mail/batch/{batch_id}

Base url: https://api.sendgrid.com

This operation allows you to validate a mail batch ID.

If you provide a valid batch ID, this operation will return a 200 status code and the batch ID itself. If you provide an invalid batch ID, you will receive a 400 level status code and an error message. A batch ID does not need to be assigned to a send to be considered valid. A successful response means only that the batch ID has been created, but it does not indicate that the ID has been assigned to a send.


Authentication

authentication page anchor
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>

on-behalf-ofstring

Use the on-behalf-of header to make API calls for a particular Subuser through the parent account. You can use this header to automate bulk updates or to administer a Subuser without changing the authentication in your code. You will use the parent account's API key when using this header.

batch_idstringrequired

Set this parameter to the batch ID that's associated with the mail send you want to retrieve.

200400401403405500

Batch ID success response.

SchemaExample
batch_idstring

A mail batch ID.

Validate batch ID

validate-batch-id page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_19
const client = require('@sendgrid/client');
_19
client.setApiKey(process.env.SENDGRID_API_KEY);
_19
_19
const batch_id = "ZGkrHSypTsudrGkmdpJJ";
_19
_19
const request = {
_19
url: `/v3/mail/batch/${batch_id}`,
_19
method: 'GET',
_19
_19
}
_19
_19
client.request(request)
_19
.then(([response, body]) => {
_19
console.log(response.statusCode);
_19
console.log(response.body);
_19
})
_19
.catch(error => {
_19
console.error(error);
_19
});


Rate this page: