---
title: "Retrieve a draft"
method: GET
path: "/v1/drafts/{id}"
tags: ["Drafts"]
---

# Retrieve a draft

`GET /v1/drafts/{id}`

## Request

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

**Requires scope:** `read` or `draft`.

## Path parameters

- `id` string, required

## Response `200`

The draft.

- Draft
  - `id` string, required: Draft id (`dft_…`).
  - `agent_id` string, required: Id (`agt_…`) of the agent the draft is sent from, chosen when it was created.
  - `to` string[]: The draft's recipients, always as a list, even when one address was given.
  - `cc` string[]: The draft's Cc addresses. Absent when `cc` was never given; `[]` when it was given empty or a PATCH emptied it.
  - `bcc` string[]: The draft's Bcc addresses, who receive it but appear in none of its headers. Absent when `bcc` was never given; `[]` when it was given empty or a PATCH emptied it.
  - `subject` string: The draft's subject. Absent when none was given; the draft is then sent with an empty subject.
  - `body_text` string: The draft's plain-text body. Absent when none was given.
  - `body_html` string: The draft's HTML body. Absent when none was given.
  - `reply_to` string, email: The address replies should go to, as given on create; absent when none was.
  - `in_reply_to_message_id` string: Id of the message this draft answers (`msg_…` or `rcv_…`), as given on create; absent when none was.
  - `thread_id` string: The thread the draft's message joined (`thrd_…`), written when the draft is sent: the thread of the message named by `sent_message_id`, also when the send could not be fully recorded after that message was stored (see `error_message`). Absent until it is sent, when a send could not be recorded far enough to store its message (no `sent_message_id`), once that thread is deleted, and on drafts sent before this field was filled in.
  - `tags` Tag[]: Name-value labels saved with the draft and copied onto the message when it is sent. Absent when none were given.
    - `name` string, required: The tag's name, as given on the send, reply or draft.
    - `value` string, required: The tag's value, as given; it may be an empty string.
  - `send_at` string, date-time: The time the draft is scheduled for (UTC); it stays after the draft is sent. Absent when it was never scheduled or was unscheduled with `send_at: null`.
  - `list_unsubscribe` boolean: Whether the draft is sent with RFC 8058 one-click unsubscribe headers (`list_unsubscribe` on create or update; off by default). One click suppresses the recipient for the whole workspace.
  - `status` 'draft' | 'scheduled' | 'sending' | 'sent' | 'failed' | 'canceled', required: `draft`: saved, not scheduled. `scheduled`: waiting for `send_at`. `sending`: being sent now. `sent`: see `sent_message_id`. `failed`: the send failed, see `error_message`. `canceled`: a scheduled reply whose conversation was deleted before it went out. Only `draft` and `scheduled` drafts can be edited or sent.
  - `sent_message_id` string: Id (`msg_…`) of the message the draft became when it was sent. Absent on a draft not yet sent; a sent draft whose send could not be fully recorded (see `error_message`) can lack it too.
  - `error_message` string: Why the draft is `failed` or `canceled`. On a `sent` draft it reports a send that went out but could not be fully recorded. Absent otherwise.
  - `created_at` string, date-time, required: When the draft was created (UTC).
  - `updated_at` string, date-time, required: When the draft last changed: an edit, a new schedule, or a status change as it is sent.

## Other responses

- `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`).
- `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)