---
title: "Save a new message draft"
method: POST
path: "/mailboxes/{id}/inbox/drafts"
tags: ["Mailboxes", "Messages"]
---

# Save a new message draft

`POST /mailboxes/{id}/inbox/drafts`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/mailboxes/{id}/inbox/drafts`
- 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`)

Save a new message (not a reply) to the mailbox's Drafts folder for a person to review, edit, and send from Shipmail or any mail client. Nothing is sent, and there is no endpoint to send it. The returned id is an inbox message ID, so the draft can be read or deleted with the inbox message endpoints. Recipients must be allowed by the API key's recipient limits. The response lists in removed_formatting any formatting the HTML sanitiser dropped. Supported HTML tags: p, br, strong/b, em/i, u, s, a (http, https, mailto, tel), ul, ol, li, blockquote, code, pre, h2, h3, span/mark with the composer's styles, and inline cid: images. h1 becomes h2. Tables and h4-h6 are not supported: their text stays as paragraphs and removed_formatting lists them ("table" for any table part, "h4", ...), as it lists other dropped elements such as script, style or iframe. Attributes and inline styles outside the composer set are dropped and not reported. Paragraphs are spaced like the Shipmail composer, so do not add <p><br></p> between them. When html is given without text, the text part is derived from it.

## Headers

- `X-Shipmail-Organization` string

## Request body

- union: A new message. Total recipients (to + cc + bcc) must not exceed 50. Threading fields such as in_reply_to are not accepted.
  - object
    - `to` Recipient[], required: To recipients (at least one).
      - 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[]: CC recipients.
      - 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[]: BCC recipients.
      - 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: Email subject. May be empty.
    - `text` string, required: Plain text body. At least one of html or text is required.
    - `html` string: HTML body. At least one of html or text is required. Supported HTML tags: p, br, strong/b, em/i, u, s, a (http, https, mailto, tel), ul, ol, li, blockquote, code, pre, h2, h3, span/mark with the composer's styles, and inline cid: images. h1 becomes h2. Tables and h4-h6 are not supported: their text stays as paragraphs and removed_formatting lists them ("table" for any table part, "h4", ...), as it lists other dropped elements such as script, style or iframe. Attributes and inline styles outside the composer set are dropped and not reported. Paragraphs are spaced like the Shipmail composer, so do not add <p><br></p> between them. When html is given without text, the text part is derived from it.
  - object
    - `to` Recipient[], required: To recipients (at least one).
      - 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[]: CC recipients.
      - 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[]: BCC recipients.
      - 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: Email subject. May be empty.
    - `text` string: Plain text body. At least one of html or text is required.
    - `html` string, required: HTML body. At least one of html or text is required. Supported HTML tags: p, br, strong/b, em/i, u, s, a (http, https, mailto, tel), ul, ol, li, blockquote, code, pre, h2, h3, span/mark with the composer's styles, and inline cid: images. h1 becomes h2. Tables and h4-h6 are not supported: their text stays as paragraphs and removed_formatting lists them ("table" for any table part, "h4", ...), as it lists other dropped elements such as script, style or iframe. Attributes and inline styles outside the composer set are dropped and not reported. Paragraphs are spaced like the Shipmail composer, so do not add <p><br></p> between them. When html is given without text, the text part is derived from it.

## Response `201`

Draft saved to the Drafts folder.

- InboxDraft
  - `object` 'inbox_draft', required
  - `id` string, required: Inbox message ID of the saved draft. Read it with GET /mailboxes/{id}/inbox/messages/{message_id}.
  - `mailbox_id` string, required
  - `from` InboxDraftRecipient, required
    - `address` string, email, required
    - `name` string, nullable, required
  - `to` InboxDraftRecipient[], required
    - `address` string, email, required
    - `name` string, nullable, required
  - `cc` InboxDraftRecipient[], required
    - `address` string, email, required
    - `name` string, nullable, required
  - `bcc` InboxDraftRecipient[], required
    - `address` string, email, required
    - `name` string, nullable, required
  - `subject` string, required
  - `removed_formatting` string[], required: Formatting the HTML sanitiser dropped: "table" for any table part, "h4" to "h6", and other dropped elements such as "script". Their text stays as paragraphs. Empty when nothing was dropped.
  - `created_at` string, date-time, required

## Other responses

- `401`: Authentication failed.
- `403`: Insufficient permissions.
- `404`: Resource not found.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[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)