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.
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.
Bearer <<YOUR_API_KEY_HERE>>Optional
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.
Set this parameter to the batch ID that's associated with the mail send you want to retrieve.
Batch ID success response.
A mail batch ID.
1const client = require("@sendgrid/client");2client.setApiKey(process.env.SENDGRID_API_KEY);34const batch_id = "ZGkrHSypTsudrGkmdpJJ";56const request = {7url: `/v3/mail/batch/${batch_id}`,8method: "GET",9};1011client12.request(request)13.then(([response, body]) => {14console.log(response.statusCode);15console.log(response.body);16})17.catch((error) => {18console.error(error);19});