Cancel scheduled sends
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.
Cancel or pause a scheduled send
POST /v3/user/scheduled_sends
Base url: https://api.sendgrid.com
This endpoint allows you to cancel or pause a scheduled send associated with a batch_id
.
Passing this endpoint a batch_id
and status will cancel or pause the scheduled send.
Once a scheduled send is set to pause
or cancel
you must use the "Update a scheduled send" endpoint to change its status or the "Delete a cancellation or pause from a scheduled send" endpoint to remove the status. Passing a status change to a scheduled send that has already been paused or cancelled will result in a 400
level status code.
If the maximum number of cancellations/pauses are added to a send, a 400
level status code will be returned.
Authentication
- API Key
Headers
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.
Request Body
The batch ID is the identifier that your scheduled mail sends share.
pattern: ^[a-zA-Z0-9]The status of the send you would like to implement. This can be pause or cancel. To delete a pause or cancel status see DELETE /v3/user/scheduled_sends/{batch_id}
default: pauseAllowed Values: pause, cancel{
"batch_id": "YOUR_BATCH_ID",
"status": "pause"
}
Responses
The status of the scheduled send.
The status of the scheduled send.
Allowed Values: cancel, pause{
"batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi",
"status": "pause"
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
the error message
the field that generated the error
helper text or docs for troubleshooting
{
"errors": [
{
"field": "field_name",
"message": "error message"
}
]
}
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.