Threads, drafts and labels

The mail commands, such as inbox, read, archive and label add, are written for people: they take several thread ids at once, format what they print and keep the label ids out of sight. Each of them runs commands from this page, which are the SDK methods for threads, drafts and labels, one command per method, so threads.listAttachments is openemail threads list-attachments.

Use these when you need what the mail commands leave out: a thread exactly as the API returns it, the files on a message, drafts, and making, renaming, recolouring or deleting labels.

• —openemail thread and openemail draft work as well as the plural names. openemail labels has no singular form: openemail label is the mail command that puts labels on threads.
• —The verbs take the usual aliases: ls for list, show and view for get, new and add for create, edit for update, and rm, del and remove for delete.
• —Every flag is in openemail <namespace> <verb> --help, such as openemail threads list --help.

Conversations in the mailbox. A thread id such as CAHk7pQ2x9LmZ4 comes from threads list, openemail inbox or openemail search.

• —--folder defaults to inbox and is matched as a label id, so sent, archive, spam, trash, draft, snoozed, starred and unread work, bin reads as trash, and a user label id such as USER_RECEIPTS works too. A folder that matches nothing returns an empty page, not an error.
• —--query takes the search syntax of the app, and in:anywhere searches every folder. --label-ids narrows further, since a thread must carry the folder and every id you pass. --date-from and --date-to read the newest message on each thread, and both ends are included.
• —threads get includes unsent draft replies among the messages, marked isDraft: true, and it opens a draft id too.
• —threads update needs --read, --no-read or a label to add or remove. Removals are applied before additions. A label id that names no label is refused with label_not_found and nothing on the thread changes, so create the label first. TRASH, SNOOZED and DRAFT are refused with label_not_directly_settable: use threads trash and threads snooze.
• —threads trash deletes nothing, and the thread stays readable with threads get, but no command takes a thread back out of the Bin. Trashing a snoozed thread also cancels its wake.
• —threads snooze sends <wake-at> as it is, so give it a future ISO 8601 instant with Z or an offset, since a time without one is read in the time zone of the server. A delay such as 3h is refused as invalid. openemail snooze --until 3h takes a delay. Threads wake at an hourly sweep, up to about an hour late, and always into the inbox.
• —threads list-attachments returns every file whole in one response. Take the message id from the messages of threads get. content is an empty string when the stored bytes cannot be found, so check its length before decoding.

Unsent messages saved in the mailbox. A draft id starts with draft-.

• —drafts list --query searches the subject, the sender and the start of the body, and never leaves drafts. older_than:30d and the other date operators read when the draft was last saved, and to:, cc: and bcc: match nothing on a draft.
• —A draft is stored as a thread labelled DRAFT, so threads get opens one and openemail inbox draft lists them. drafts get, update and delete refuse an ordinary thread id with a 404.
• —A bare openemail drafts create saves a blank draft. Only lengths are checked: a subject up to 998 characters, and --html and --text up to 1,000,000 each, with --html kept when both are set. There is no flag for attachments.
• —drafts update replaces each field you send. A list replaces the stored one whole, so --to with one address drops the others, and an update empties the draft’s attachment list.
• —--thread-id records the thread a draft replies to, but the draft is still stored as a thread of its own.
• —Running drafts create again saves a second draft, because it takes no idempotency key. A display name with a comma in it splits into two broken recipients, so leave the comma out.
• —openemail send --draft <id> --to <address> sends a draft. The body comes from the draft, and so does the subject unless you pass --subject, while the recipients are the ones you name. It cannot be combined with a body, --template or --translate.

The labels a thread can carry. A user label id is USER_ followed by the name it was created with, upper cased, with each run of whitespace turned into _, so Big Clients is USER_BIG_CLIENTS.

• —An id never changes, even after a rename, so store ids rather than names.
• —System labels such as INBOX, STARRED and UNREAD are not listed and cannot be changed or deleted, though threads update takes them. labels get on one is a 404.
• —A workspace holds up to 50 user labels. A name another label already has, compared without case, is refused with label_name_taken.
• —A colour is a hex value such as #3B82F6 or a gradient token such as gradient:sunset. --label-color takes the whole colour as JSON, and --label-color null clears it.
• —A label belongs to the workspace, so renaming, recolouring or deleting it changes it for everyone in it.
• —labels delete has no undo. Creating a label with the same name again gives the same id, but the threads do not get it back. Its threadCount in labels get says how many conversations will lose it.

• —A mail command takes several thread ids and reports on each one, and with --json it prints { results, succeeded, failed }. A command on this page takes one id and prints what the API returns.
• —openemail inbox reads every thread it lists to show who wrote last and the subject. threads list makes one request per page and prints only ids, which is all a pipeline needs.
• —openemail read turns an HTML message into text and marks the thread read. threads get prints the thread as the API returns it and changes nothing.

Mark a thread read, archive it and label it in one request, where mark read, archive and label add would make three:

openemail threads update CAHk7pQ2x9LmZ4 --read --add-label-ids ARCHIVE,USER_RECEIPTS --remove-label-ids INBOX --json

Make a label and file every matching thread under it. Piped, --all prints one JSON object per line:

openemail labels create --name Receipts --color-background-color gradient:meadowopenemail threads list --query "in:anywhere subject:receipt newer_than:1y" --all | jq -r .id | xargs openemail label add --label USER_RECEIPTS

Save one file from a message. The message ids are on the messages of threads get:

openemail threads get CAHk7pQ2x9LmZ4 --json | jq -r ".messages[].id"openemail threads list-attachments CAHk7pQ2x9LmZ4 message_4c1b257a --json | jq -r '.[] | select(.filename == "invoice.pdf") | .content' | base64 --decode > invoice.pdf

Write a draft, change it, read it back, then send it:

DRAFT=$(openemail drafts create --to [email protected] --subject "Engine notes for Thursday" --html "<p>Agenda below.</p>" --json | jq -r .id)openemail drafts update "$DRAFT" --to [email protected],[email protected]openemail drafts get "$DRAFT"openemail send --draft "$DRAFT" --from [email protected] --to [email protected],[email protected]

Clear out drafts nobody has saved for 30 days. The dry run prints each DELETE without sending it, and --yes answers the confirmation:

openemail drafts list --query older_than:30d --all | jq -r .id > stale.txtxargs -n 1 openemail drafts delete --dry-run < stale.txtxargs -n 1 openemail drafts delete --yes < stale.txt

Pick a gradient from the palette, preview the change, make it, and later take the colour off again:

openemail labels list-colors --json | jq -r '.[] | select(.kind == "gradient") | .value'openemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:aurora --dry-runopenemail labels update USER_RECEIPTS --name "Receipts 2026" --color-background-color gradient:auroraopenemail labels update USER_RECEIPTS --label-color null

A missing scope stops with exit code 4. None of these commands asks for a verification code, with a browser sign-in or with an API key.

A sign-in or key limited to some addresses sees only the threads delivered to them, and any other thread is a 404, as if it did not exist. Labels belong to the workspace, so it still sees every label, but threadCount counts only the conversations it can see.

• —threads list, drafts list and labels list read one page, 25 unless --limit says otherwise, up to 100. --cursor carries on from the cursor a page printed. A thread cursor keeps the order it was handed out in, so send the same filters with it.
• —--all reads every page and --max <n> stops after that many. Piped or with --ndjson it prints one JSON object per line, and with --json one { items, hasMore, nextCursor } document.
• —hasMore can be true on what turns out to be the last page, and the next call then returns no items. A thread that gets new mail while you page moves ahead of the cursor and is not returned by later pages, and so does a draft saved while you page.
• —threads trash, drafts delete and labels delete ask you to confirm. Unattended, with --json, --no-input or no terminal, they stop with exit code 2 and change nothing unless you pass --yes.
• —--dry-run prints the request a command would send, with the credential redacted, and exits with code 0 without sending it or asking to confirm. With --json it prints { dryRun, request }.

--data takes the whole body as JSON, inline, from a file with @path, or from stdin with -, and a flag you pass as well overrides its key.

An empty flag value is a usage error, so a field that an empty value clears goes through --data instead. --label-color null clears a label’s colour.

openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"from":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"threadId":""}'openemail drafts update draft-5f0c2a9e-8b1d-4e7a-a3c6-2d9f41b7e0c8 --data '{"to":[]}'openemail drafts create --data @draft.json --subject "Overrides the file"

The first saves the draft with no sender, the second detaches it from the thread it replied to, and the third clears its recipients.

openemail threads --helpopenemail threads list --helpopenemail drafts create --help --json

openemail <namespace> <verb> --help shows each argument and flag with its type, the scopes the call needs, its method and path, what it returns and the notes from the API reference. Add --json for the same help as data.