Reschedule an email

Move a scheduled send to a different time.

PATCH /v1/emails/{id}

Works with a Sending key — rescheduling is part of getting a message out, so a key embedded in your app can do it without also being able to read your mail.

Parameters

Parameter	Type	Required	Description
scheduled_at	string	Yes	ISO 8601, in the future — 2026-08-05T11:52:01Z.

Example

curl

curl -X PATCH "https://api.sendgrail.com/v1/emails/$ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-08-05T11:52:01Z" }'

Node.js

await fetch(`https://api.sendgrail.com/v1/emails/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ scheduled_at: '2026-08-05T11:52:01Z' }),
});

Response

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

Only while it's still waiting

A message can be rescheduled only while its last_event is scheduled. Once it's queued, the fan-out has started and the message is on its way to the mail servers — there is nothing left to move.

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

To stop a scheduled send outright rather than move it, use Cancel an email.