---
title: "Reschedule a scheduled message"
method: PATCH
path: "/v1/messages/{id}"
tags: ["Messages"]
---

# Reschedule a scheduled message

`PATCH /v1/messages/{id}`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/messages/{id}`
- Auth: HTTP bearer

**Requires scope:** `manage`. Moves a scheduled send to a new future `scheduled_at`, and raises `message.scheduled` again with the new `scheduled_at` and the `previous_scheduled_at` it replaced. It needs the `send` scope as well as `manage`, and a live key for a live message (403 `live_mode_required`); the key that scheduled the send keeps answering for it. A send that failed only because its agent was paused or archived when it came due (`status: rejected`, `metadata.rejected_reason` starting `agent_paused:` or `agent_archived:`) is scheduled again by the same call once a paused agent is resumed: that needs a `scheduled_at`, and answers 422 `agent_paused` while the agent is still paused. Archiving cannot be undone, so one whose agent was archived answers 404 `agent_archived`. A message that changed while it was being rescheduled (it started sending, or was canceled or scheduled again) answers 409 `duplicate_resource`.

## Path parameters

- `id` string, required

## Request body

- RescheduleMessageRequest
  - `scheduled_at` string, date-time: The new send time: an ISO 8601 UTC time ending in `Z`, which must be in the future (400 `invalid_field` otherwise). Left out, the schedule stays as it is.

## Response `200`

The updated schedule.

- object
  - `id` string, required: Id of the rescheduled message (`msg_…`): the id in the path.
  - `scheduled_at` string, date-time: When the message will go out, as `GET /v1/messages/{id}` returns it: the new time in UTC with milliseconds, however the request wrote it, or the current one when the request left `scheduled_at` out.
  - `status` 'scheduled', required: Always `scheduled`: only a scheduled message can be rescheduled.

## Other responses

- `400`: Invalid request — malformed JSON or a field failed validation. Also `feature_not_enabled` when this server has a feature switched off (custom domains before they are available).
- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `404`: Resource not found in this workspace, or the agent a send names is archived (`agent_archived`).
- `409`: Conflict — duplicate resource, an in-progress idempotent request, a draft or scheduled message that started sending while it was being changed, or a thread deleted for good while one of its messages is being sent (`duplicate_resource`); or an agent name more than one agent has (`agent_name_conflict`: use the agent's id); or a status change on an archived agent, since archiving cannot be undone (`agent_archived`).
- `422`: Unprocessable — agent paused, recipient suppressed, a recipient at test.mails.ai other than reply@test.mails.ai (`unknown_test_address`), or abuse guard.
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)