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.

Retrieve all scheduled sends

GET /user/scheduled_sends

This endpoint allows you to retrieve all cancelled and paused scheduled send information.

This endpoint will return only the scheduled sends that are associated with a batch_id. If you have scheduled a send using the /mail/send endpoint and the send_at field but no batch_id, the send will be scheduled for delivery; however, it will not be returned by this endpoint. For this reason, you should assign a batch_id to any scheduled send you may need to pause or cancel in the future.

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.

Responses

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

The status of the scheduled send.

Allowed Values: cancel, 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