nextmail drafts

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 <n> stops after that many items.

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.

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 <[email protected]>, 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.

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.

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.