Menu

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 /user/scheduled_sends

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

Authorization
string
default: Bearer <<YOUR_API_KEY_HERE>>
required
on-behalf-of
string
default: The subuser's username. This header generates the API call as if the subuser account was making the call.

Request Body

object
batch_id
string

The batch ID is the identifier that your scheduled mail sends share.

pattern: ^[a-zA-Z0-9]
required
status
string

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
required
{
  "batch_id": "YOUR_BATCH_ID",
  "status": "pause"
}

Responses

object

The status of the scheduled send.

batch_id
string
pattern: ^[a-zA-Z0-9\-\_]
required
status
string

The status of the scheduled send.

Allowed Values: cancel, pause
required
{
  "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi",
  "status": "pause"
}
object
errors
array[object]
message
string
field
string
help
object
id
string
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string

the error message

field
string or null

the field that generated the error

help
object

helper text or docs for troubleshooting

id
string
{
  "errors": [
    {
      "field": "field_name",
      "message": "error message"
    }
  ]
}
object
errors
array[object]
message
string
Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

Thank you for your feedback!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more