Cancel an email

Stop a scheduled send before it goes out.

POST /v1/emails/{id}/cancel

Works with a Sending key.

Example

curl

curl -X POST "https://api.sendgrail.com/v1/emails/$ID/cancel" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

await fetch(`https://api.sendgrail.com/v1/emails/${id}/cancel`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
});

Response

{ "object": "email", "id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c" }

The message's last_event becomes cancelled, and a cancelled event lands on its timeline in the dashboard. Nothing is sent, and it costs nothing.

Only while it's still waiting

Cancelling is possible only while last_event is scheduled. Once the message is queued it has already been handed to the mail servers, and we can't recall it — no one can.

{
  "message": "Only a scheduled email can be cancelled. This one is sent.",
  "code": "email_not_pending",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

Cancelling an already-cancelled message returns the same error, so a retry after a network failure is harmless.