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

Update a scheduled send



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.


PATCH/v3/user/scheduled_sends/{batch_id}

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

This endpoint allows you to update the status of a scheduled send for the given batch_id.

If you have already set a cancel or pause status on a scheduled send using the "Cancel or pause a scheduled send" endpoint, you can update it's status using this endpoint. Attempting to update a status once it has been set with the "Cancel or pause a scheduled send" endpoint will result in a 400 error.


Authentication

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

on-behalf-ofstring

The on-behalf-of header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be "account-id" followed by the customer account's ID (e.g., on-behalf-of: account-id <account-id>). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., on-behalf-of: <subuser-username>). See On Behalf Of for more information.

batch_idstringrequired
SchemaExample
statusenum<string>required

The status you would like the scheduled send to have.

Possible values:
cancelpause
204400401403404500
Schema

No properties defined

Update a scheduled send

update-a-scheduled-send page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_22
const client = require('@sendgrid/client');
_22
client.setApiKey(process.env.SENDGRID_API_KEY);
_22
_22
const batch_id = "ZGkrHSypTsudrGkmdpJJ";
_22
const data = {
_22
"status": "pause"
_22
};
_22
_22
const request = {
_22
url: `/v3/user/scheduled_sends/${batch_id}`,
_22
method: 'PATCH',
_22
body: data
_22
}
_22
_22
client.request(request)
_22
.then(([response, body]) => {
_22
console.log(response.statusCode);
_22
console.log(response.body);
_22
})
_22
.catch(error => {
_22
console.error(error);
_22
});


Rate this page: