> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tawked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduling

> Send an e-mail at a time you choose, up to 30 days ahead, move it to another time, or cancel it before it goes.

## Schedule a message

Add `scheduled_at` to [a send](https://docs.tawked.com/email/messages.md#send), or to any message of a [batch](https://docs.tawked.com/email/batch.md): an ISO 8601 date and time with its offset or `Z`, within the next 30 days.

```bash theme={"dark"}
curl -X POST https://tawked.com/v1/email/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "متجر أكمي <orders@acme.sa>",
    "to": "sara@example.com",
    "subject": "موعد استلام طلبك غدًا",
    "html": "<p>نذكّرك بموعد استلام طلبك رقم 1042 غدًا.</p>",
    "scheduled_at": "2026-10-22T09:00:00+03:00"
  }'
```

The answer is `202` with the status `scheduled`, in the [extended shape](https://docs.tawked.com/email/messages.md#recipients):

```json theme={"dark"}
{
  "id": "0199f1c2-7a41-7c3e-9d2b-5e8f1a2b3c4d",
  "status": "scheduled",
  "scheduled_at": "2026-10-22T09:00:00+03:00",
  "recipients": [
    { "id": "0199f1c2-7a42-7b10-8c3d-1f2e3d4c5b6a", "address": "sara@example.com", "name": null, "type": "to", "status": "scheduled" }
  ]
}
```

(Shortened: the answer carries every field of a send's answer.)

* **Dates are exact**: `2026-10-22T09:00:00+03:00` or `2026-10-22T06:00:00Z`. Words such as "tomorrow at 9" are not read; compute the time on your side.
* **Within the next minute** the message is sent now (`accepted`, `scheduled_at` kept). More than a minute in the past, or more than 30 days ahead, is refused with `400 invalid_request`.
* **Charged when you call**, at the price and against the free e-mails of that moment, so a balance that runs low shows at once.
* **The daily limit of its day**: the message counts on the Riyadh day it is due, not the day you scheduled it.
* **No attachments**: only the body waits, kept encrypted until it is sent. A scheduled message with `attachments` is refused (`` `attachments` cannot be sent with `scheduled_at` ``).
* **Not over SMTP**: [the SMTP relay](https://docs.tawked.com/email/smtp.md) sends at once.

## Reschedule

`PATCH /v1/email/messages/{id}` with the new `scheduled_at`, the only field a message can change:

```bash theme={"dark"}
curl -X PATCH https://tawked.com/v1/email/messages/0199f1c2-7a41-7c3e-9d2b-5e8f1a2b3c4d \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-10-23T09:00:00+03:00" }'
```

It answers `200` with the message as it stands. The new day's limit applies, and a time within the next minute sends it now. Only a `scheduled` message can move: once it is on its way the answer is `409 message_not_scheduled` with its `status`. Rescheduling takes `email:send`; another application's id answers `404 not_found`.

## Cancel

`POST /v1/email/messages/{id}/cancel` cancels a scheduled message before its time:

```bash theme={"dark"}
curl -X POST https://tawked.com/v1/email/messages/0199f1c2-7a41-7c3e-9d2b-5e8f1a2b3c4d/cancel \
  -H "Authorization: Bearer $TAWKED_KEY"
```

It answers `200` with the message `canceled` (its recipients too) and `canceled_at` set. Its price is refunded to your balance, and a free e-mail goes back to the month's allowance when it is the same month. Only a `scheduled` message can be canceled: a message already on its way answers `409 message_not_scheduled`. No webhook announces a cancel. The console's **Email → Messages** can cancel a scheduled message too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.