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

# Schedule email

> Send email later, change its delivery time, or cancel it

Set `scheduled_at` to create an email now and release it for delivery at a future time.

## Schedule a message

For a new send, `scheduled_at` accepts an ISO 8601 timestamp or a relative value such as `in 5 min`:

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/emails \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: appointment-reminder-42" \
  --data '{
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "We will see you tomorrow at 10:00.",
    "scheduled_at": "2026-08-12T09:00:00Z"
  }'
```

Relative scheduling is also supported:

```json theme={null}
{
  "scheduled_at": "in 30 min"
}
```

Supported relative units include seconds, minutes, hours, and days. For deterministic production workflows, prefer an explicit UTC ISO 8601 timestamp.

## Reschedule an email

Use `PATCH /emails/{message_id}` while the email is still a pending scheduled message. Rescheduling requires an ISO 8601 timestamp.

```bash theme={null}
curl --request PATCH \
  --url https://api.dugble.com/emails/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794 \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: appointment-reminder-42-reschedule" \
  --data '{
    "scheduled_at": "2026-08-12T11:00:00Z"
  }'
```

A successful update returns the message ID:

```json theme={null}
{
  "success": true,
  "data": {
    "object": "email",
    "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
  }
}
```

## Cancel a scheduled email

```bash theme={null}
curl --request POST \
  --url https://api.dugble.com/emails/49a3999c-0ce1-4ea6-ab68-afcd6dc2e794/cancel \
  --header "Authorization: Bearer $DUGBLE_API_KEY" \
  --header "Idempotency-Key: appointment-reminder-42-cancel"
```

Only pending scheduled emails can be rescheduled or canceled. Once a message has started processing, the mutation is rejected with a conflict response.

## Scheduling rules

* `scheduled_at` must resolve to a time in the future.
* New send requests may use an ISO 8601 timestamp or supported relative value.
* Rescheduling requires a future ISO 8601 timestamp.
* Only pending scheduled emails can be changed or canceled.
* Use a distinct `Idempotency-Key` for each distinct scheduling mutation.

<Warning>
  Do not wait until the intended delivery time to reschedule or cancel a message. Queue processing can begin as soon as the scheduled time is reached.
</Warning>