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

# Update a scheduled message

`PATCH /scheduled-messages/{id}`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/scheduled-messages/{id}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Replace recipients, content, staged attachments, and delivery time before dispatch begins. Omitting both html and text moves the send in time and keeps the stored body, so a rich HTML send does not have to be resent to be rescheduled.

## Headers

- `Idempotency-Key` string
- `X-Shipmail-Organization` string

## Request body

- UpdateScheduledMessageRequest
  - `to` Recipient[], required
    - union: Email recipient. Either an object with address and optional name, or a string.
      - object
        - `address` string, email, required: Email address.
        - `name` string, nullable: Display name (optional).
      - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
  - `cc` Recipient[]
    - union: Email recipient. Either an object with address and optional name, or a string.
      - object
        - `address` string, email, required: Email address.
        - `name` string, nullable: Display name (optional).
      - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
  - `bcc` Recipient[]
    - union: Email recipient. Either an object with address and optional name, or a string.
      - object
        - `address` string, email, required: Email address.
        - `name` string, nullable: Display name (optional).
      - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
  - `subject` string, required
  - `html` string: HTML body. Omit both html and text to keep the scheduled draft's stored body; sending either one replaces the body as a unit.
  - `text` string: Plain text body. Omit both html and text to keep the scheduled draft's stored body; sending either one replaces the body as a unit.
  - `in_reply_to` string: Replaces the In-Reply-To header. The scheduled message keeps the conversation it was stored in.
  - `references` string[]: Replaces the References header. It never decides or merges conversations.
  - `staged_attachment_ids` string[]
  - `scheduled_at` string, date-time, required

## Response `200`

Updated scheduled message.

- ScheduledMessage
  - `object` 'scheduled_message', required
  - `id` string, required: Tracked message ID used by scheduled-message endpoints.
  - `scheduled_message_id` string, required: Internal scheduled lifecycle row ID.
  - `status` 'scheduled' | 'settling': `scheduled` while the message waits for its send time. `settling` when a send attempt may already have gone out and Shipmail is checking whether it did: the message cannot be updated or cancelled until that resolves, and it then leaves the scheduled list as sent, or returns as `scheduled`. Treat a value you do not recognize as not editable. Absent from responses of servers that predate the field; treat absence as `scheduled`.
  - `kind` 'scheduled' | 'undo', required
  - `mailbox_id` string, required
  - `mailbox_address` string, email, required
  - `from_address` string, email, required
  - `identity_id` string, required
  - `mode` 'live' | 'test', required: The API-key data plane that owns this resource. Test resources are isolated from live delivery, quota, suppression, and reputation.
  - `subject` string, required
  - `to` Recipient[], required
    - union: Email recipient. Either an object with address and optional name, or a string.
      - object
        - `address` string, email, required: Email address.
        - `name` string, nullable: Display name (optional).
      - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
  - `cc` Recipient[], required
    - union: Email recipient. Either an object with address and optional name, or a string.
      - object
        - `address` string, email, required: Email address.
        - `name` string, nullable: Display name (optional).
      - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
  - `bcc` Recipient[], required
    - union: Email recipient. Either an object with address and optional name, or a string.
      - object
        - `address` string, email, required: Email address.
        - `name` string, nullable: Display name (optional).
      - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
  - `attachments` AttachmentMetadata[], required
    - `filename` string, required
    - `size` integer, required: Size in bytes.
    - `content_type` string, required
  - `scheduled_at` string, date-time, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `last_error` string, nullable, required
  - `draft_email_id` string
  - `from_name` string
  - `text` string
  - `html` string
  - `in_reply_to` string, nullable
  - `references` string[]
  - `uploaded_attachments` object[]
    - `blob_id` string, required
    - `filename` string, required
    - `content_type` string, required
    - `size` integer, required

## Other responses

- `403`: Insufficient permissions.
- `404`: Resource not found.
- `409`: Resource conflict.
- `422`: Validation failed.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)