--- title: "nextmail drafts" description: "Every command in this namespace, with its arguments, flags and examples." url: "https://nextmail.sh/docs/cli/reference/drafts" area: "CLI" category: "Reference" --- # nextmail drafts Every command in this namespace, with its arguments, flags and examples. ## Commands ### `nextmail drafts list` List one page of drafts ```bash nextmail drafts list [flags] ``` Returns one page of saved drafts, most recently saved first. A row is only `object` and `id`, so call `get` for recipients, subject and body. A draft is stored as a thread labelled `DRAFT`, so this reads the same index as `threads.list({ folder: 'draft' })`. `query` takes the same search syntax as `threads.list`. Plain words must all appear and match loosely, ignoring case, accents and separators, against the draft's subject, its sender and the first 4,000 characters of its body with markup stripped, while a quoted phrase is matched as written apart from case and accents, so `"ben jamin"` does not find "Ben-Jamin". Filler words such as `the` or `emails` are dropped when something else is left to search for. Recipients are stored as one list without roles and are not written for a draft, so `to:`, `cc:` and `bcc:` match nothing here. `subject:`, `body:` and `from:` narrow the search, and `after:`, `before:`, `newer_than:` and `older_than:` read the time the draft was last saved, in UTC, with `after:` including the day it names and `before:` excluding it. A draft saved with no subject is stored as `(no subject)`, so `subject:"no subject"` finds it. The drafts folder always applies, so `in:` and folder `is:` operators such as `is:sent` cannot widen the search beyond drafts, `in:anywhere` included. The API pages with an opaque `pageToken`, which the SDK hands back as `nextCursor` and accepts as `--cursor`. A page holds 25 drafts unless `--limit` says otherwise. Add `--all` to walk every page: a table on a terminal, one JSON object per line when piped or with `--ndjson`, and one `{ items, hasMore, nextCursor }` document with `--json`. `--max ` stops after that many items. - Scopes: `drafts:read`. - Needs a sign-in. - Aliases: `ls`. **Flags** - `--query `: Mailbox search over the subject, sender and body preview. Plain words must all appear and match loosely, a quoted phrase has to appear as written, filler words are dropped when something else is left to search for, and operators such as `subject:` and `older_than:30d` narrow it. `to:`, `cc:` and `bcc:` match nothing on a draft, and the search cannot leave drafts. - `--limit `: Drafts per page, a whole number from 1 to 100. Defaults to 25. - `--cursor `: The `nextCursor` of the previous page, passed back unchanged. - `--all`: Fetch every page and stream the items as they arrive. - `--max `: Stop after this many items. Implies `--all`. - `--ndjson`: Print every item as one JSON object per line. Implies `--all` **Examples** ```bash nextmail drafts list ``` With optional flags ```bash nextmail drafts list --query subject:proposal --limit 20 ``` Walk every page and stop after 100 items ```bash nextmail drafts list --all --max 100 ``` One JSON object per line when piped ```bash nextmail drafts list --all > drafts.ndjson ``` Also available in: API [`GET /drafts`](https://nextmail.sh/docs/api/reference/drafts#get-drafts); TypeScript [`nextmail.drafts.list()`](https://nextmail.sh/docs/sdk/reference/drafts#list); Python [`drafts.list()`](https://nextmail.sh/docs/python/reference/drafts#list); Ruby [`drafts.list`](https://nextmail.sh/docs/ruby/reference/drafts#list); PHP [`drafts->list`](https://nextmail.sh/docs/php/reference/drafts#list); Go [`Drafts.List`](https://nextmail.sh/docs/go/reference/drafts#list); Java [`drafts().list`](https://nextmail.sh/docs/java/reference/drafts#list); C# [`Drafts.ListAsync`](https://nextmail.sh/docs/csharp/reference/drafts#list). ### `nextmail drafts get` Read a draft's recipients, subject and body ```bash nextmail drafts get [flags] ``` Returns the fields a draft was saved with: `to`, `cc`, `bcc`, `subject`, the body as `html`, the `from` address, the `threadId` it replies to and its attachment list. The id must belong to a thread labelled `DRAFT`, so an ordinary thread id is a 404 here even though `threads.get` opens it. Values come back normalised rather than as sent. Recipients are bare addresses with display names dropped, an empty subject reads as `(no subject)`, and `from` is the address the draft was saved with. It is reported only while the workspace can still send as the stored sender, so a draft saved from an address that has since gone reads `from: null`, as does a draft saved without a sender. A draft saved with `text` and no `html` returns that text in `html`, unconverted. `threadId` is null for a draft that does not reply to anything. `forwardOf` is the message in `threadId` the draft forwards, or null. `attachments` carries only `filename`, `contentType` and `size`, because draft attachments are stored as names and types without content: a forwarding draft attaches the forwarded message's files when it is sent, and any other file goes on the send itself. - Scopes: `drafts:read`. - Needs a sign-in. - Aliases: `show`, `view`. **Arguments** - `` (required): Draft id, which starts with `draft-`. **Examples** ```bash nextmail drafts get draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 ``` Print the raw JSON ```bash nextmail drafts get draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --json ``` Also available in: API [`GET /drafts/{id}`](https://nextmail.sh/docs/api/reference/drafts#get-drafts-id); TypeScript [`nextmail.drafts.get()`](https://nextmail.sh/docs/sdk/reference/drafts#get); Python [`drafts.get()`](https://nextmail.sh/docs/python/reference/drafts#get); Ruby [`drafts.get`](https://nextmail.sh/docs/ruby/reference/drafts#get); PHP [`drafts->get`](https://nextmail.sh/docs/php/reference/drafts#get); Go [`Drafts.Get`](https://nextmail.sh/docs/go/reference/drafts#get); Java [`drafts().get`](https://nextmail.sh/docs/java/reference/drafts#get); C# [`Drafts.GetAsync`](https://nextmail.sh/docs/csharp/reference/drafts#get). ### `nextmail drafts create` Save a new draft ```bash nextmail drafts create [flags] ``` Saves an unsent message to the mailbox and returns its id. Every field is optional, so an empty object saves a blank draft. The body is strict: any key outside the fields below is a 422 `invalid_parameter`, and there is no field for attachments, which a send carries itself. To forward an email, pass `--thread-id` and `--forward-of`, the id of a message in that thread from `threads.get`. The draft takes the names of that message's files and, unless you give a `subject`, its subject with `Fwd:` in front. `emails.send({ draftId })` then quotes the message below the body, attaches its files and threads it the way forwarding in the app does. `--forward-of` without `--thread-id`, or naming no message of that thread, is a 422 `invalid_parameter`. Nothing is validated beyond length. Addresses in `to`, `cc` and `bcc` may carry a display name, as in `Ada Lovelace `, and `from` is stored as given. A draft saved without `from` has no sender, and `get` reads `from` back as null. `subject` is capped at 998 characters, and `html` and `text` at 1,000,000 each. When both bodies are sent only `html` is kept. `--thread-id` records the conversation the draft replies to, but the draft is stored as a thread of its own under its new id. It shows up in `threads.list({ folder: 'draft' })`, not inside the original thread. - Scopes: `drafts:write`. - Needs a sign-in. - Aliases: `new`, `add`. **Flags** - `--to ` (repeatable, default `[]`): Recipient addresses, bare or with a display name. - `--cc ` (repeatable, default `[]`): Copy recipients, bare or with a display name. - `--bcc ` (repeatable, default `[]`): Blind copy recipients, bare or with a display name. - `--subject ` (default `""`): At most 998 characters. Empty is stored as `(no subject)`. - `--html `: Body markup, at most 1,000,000 characters. Kept over `text` when both are set. - `--text `: Body used only when `html` is absent, at most 1,000,000 characters. Stored as is and read back in `html`. - `--from `: Sender address, optionally with a display name. Left out, the draft is saved with no sender. - `--thread-id `: Id of the thread this draft replies to, or the thread holding the message `--forward-of` names. - `--forward-of `: Id of the message in `--thread-id` to forward. Sending the draft quotes it below the body and attaches its files. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** ```bash nextmail drafts create ``` With optional flags ```bash nextmail drafts create --to grace@example.com --subject 'Engine notes for Thursday' --html '

Agenda below, comments welcome.

' ``` Also available in: API [`POST /drafts`](https://nextmail.sh/docs/api/reference/drafts#post-drafts); TypeScript [`nextmail.drafts.create()`](https://nextmail.sh/docs/sdk/reference/drafts#create); Python [`drafts.create()`](https://nextmail.sh/docs/python/reference/drafts#create); Ruby [`drafts.create`](https://nextmail.sh/docs/ruby/reference/drafts#create); PHP [`drafts->create`](https://nextmail.sh/docs/php/reference/drafts#create); Go [`Drafts.Create`](https://nextmail.sh/docs/go/reference/drafts#create); Java [`drafts().create`](https://nextmail.sh/docs/java/reference/drafts#create); C# [`Drafts.CreateAsync`](https://nextmail.sh/docs/csharp/reference/drafts#create). ### `nextmail drafts update` Change fields on a saved draft ```bash nextmail drafts update [flags] ``` A partial update: each field you send replaces the stored value and each field you leave out keeps it. Arrays replace wholesale, so sending `to` with one address drops the rest. The limits and the strict body are the same as `create`. The draft must already exist. An unknown id, or the id of a thread that is not a draft, is a 404 rather than a new draft. The returned `id` is the one to keep using, and it is always the id you passed. Sending `text` without `html` replaces the stored body with that text. The draft keeps its attachment list, and a draft that forwards a message keeps forwarding it unless `--thread-id` moves it to another conversation. - Scopes: `drafts:write`. - Needs a sign-in. - Aliases: `edit`. **Arguments** - `` (required): Draft id, which starts with `draft-`. **Flags** - `--to ` (repeatable): Replacement recipients. An empty array clears them. - `--cc ` (repeatable): Replacement copy recipients. - `--bcc ` (repeatable): Replacement blind copy recipients. - `--subject `: Replacement subject, at most 998 characters. - `--html `: Replacement body markup, at most 1,000,000 characters. - `--text `: Replacement body used only when `html` is absent. - `--from `: Replacement sender. An empty string clears it, leaving the draft with no sender. - `--thread-id `: Thread the draft replies to. An empty string detaches it. - `--data `: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys. **Examples** With optional flags ```bash nextmail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --to grace@example.com,charles@example.com --subject 'Engine notes for Thursday, revised' ``` Print the raw JSON ```bash nextmail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --to grace@example.com,charles@example.com --subject 'Engine notes for Thursday, revised' --json ``` Also available in: API [`PATCH /drafts/{id}`](https://nextmail.sh/docs/api/reference/drafts#patch-drafts-id); TypeScript [`nextmail.drafts.update()`](https://nextmail.sh/docs/sdk/reference/drafts#update); Python [`drafts.update()`](https://nextmail.sh/docs/python/reference/drafts#update); Ruby [`drafts.update`](https://nextmail.sh/docs/ruby/reference/drafts#update); PHP [`drafts->update`](https://nextmail.sh/docs/php/reference/drafts#update); Go [`Drafts.Update`](https://nextmail.sh/docs/go/reference/drafts#update); Java [`drafts().update`](https://nextmail.sh/docs/java/reference/drafts#update); C# [`Drafts.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/drafts#update). ### `nextmail drafts delete` Delete a draft permanently ```bash nextmail drafts delete [flags] ``` Removes the draft, its stored body and its attachment entries from the mailbox. It does not go to the Bin and there is no undo. The id must belong to a thread carrying the `DRAFT` label, so an ordinary thread id is a 404. Use `threads.trash` to remove real mail. - Scopes: `drafts:write`. - Needs a sign-in. - Asks you to confirm. - Aliases: `rm`, `del`, `remove`. **Arguments** - `` (required): Draft id, which starts with `draft-`. **Examples** ```bash nextmail drafts delete draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 ``` Skip the confirmation, for scripts ```bash nextmail drafts delete draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --yes ``` Also available in: API [`DELETE /drafts/{id}`](https://nextmail.sh/docs/api/reference/drafts#delete-drafts-id); TypeScript [`nextmail.drafts.delete()`](https://nextmail.sh/docs/sdk/reference/drafts#delete); Python [`drafts.delete()`](https://nextmail.sh/docs/python/reference/drafts#delete); Ruby [`drafts.delete`](https://nextmail.sh/docs/ruby/reference/drafts#delete); PHP [`drafts->delete`](https://nextmail.sh/docs/php/reference/drafts#delete); Go [`Drafts.Delete`](https://nextmail.sh/docs/go/reference/drafts#delete); Java [`drafts().delete`](https://nextmail.sh/docs/java/reference/drafts#delete); C# [`Drafts.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/drafts#delete).