import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.messages.reschedule(
"msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"2026-06-25T14:00:00.000Z",
);
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.reschedule_message(
"msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"2026-06-25T14:00:00.000Z",
)
print(result)curl -X PATCH 'https://api.mails.ai/v1/messages/msg_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "scheduled_at": "2026-06-25T14:00:00.000Z" }'mails emails reschedule msg_01JABC \
--scheduled-at 2026-12-01T09:00:00Z{
"name": "mails_emails_reschedule",
"arguments": {
"message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"scheduled_at": "2026-06-25T14:00:00.000Z"
}
}{
"id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"scheduled_at": "2026-10-04T12:00:00.000Z",
"status": "scheduled"
}200 The updated schedule.
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.Reschedule a scheduled message
scheduled_at, and raises message.scheduled again with the new scheduled_at and the previous_scheduled_at it replaced.import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.messages.reschedule(
"msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"2026-06-25T14:00:00.000Z",
);
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.reschedule_message(
"msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"2026-06-25T14:00:00.000Z",
)
print(result)curl -X PATCH 'https://api.mails.ai/v1/messages/msg_01JZX8K3M9Q4P7VN2YB6RTDC0E' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "scheduled_at": "2026-06-25T14:00:00.000Z" }'mails emails reschedule msg_01JABC \
--scheduled-at 2026-12-01T09:00:00Z{
"name": "mails_emails_reschedule",
"arguments": {
"message_id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"scheduled_at": "2026-06-25T14:00:00.000Z"
}
}{
"id": "msg_01JZX8K3M9Q4P7VN2YB6RTDC0E",
"scheduled_at": "2026-10-04T12:00:00.000Z",
"status": "scheduled"
}200 The updated schedule.
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.Path Parameters
Sent message id with status scheduled, or rejected because its agent was paused or archived.
Body Parameters
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.
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.
Response
Id of the rescheduled message (msg_…): the id in the path.
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.
Always scheduled: only a scheduled message can be rescheduled.
Was this page helpful?