List threads

GET/threads

Lists conversations, most recent first, a page at a time. Narrow it to a mailbox, a view or a label, or search.

Needs the permissionthreads:list

Mail arrives as messages but is read as conversations, so the API is threaded. DMU Mail works out which messages belong together as they arrive, so you don’t have to.

A search (q) returns up to 50 of the best matches in one page, with nextCursor null: results ranked by relevance have no “older than this” to continue from. With q, view is ignored.

Query parameters

mailboxstringoptional: Only this mailbox’s conversations.
viewstringoptional: inbox (the default), important, assigned_to_me, assigned_to_others, sent, closed, spam, trash, drafts or all.
qstringoptional: Words to search for. label:name narrows it to a label: quote a name with spaces, as in label:"Waiting on client", or write a hyphen for each space. A q of labels alone pages like a view.
labelstringoptional: A label’s id: every conversation carrying it, open or closed. An unknown label gives an empty page.
limitnumberoptional: 1 to 200, or 50 if you leave it out. Anything else is refused rather than quietly capped.
cursorstringoptional: The nextCursor from the page before, unchanged. See Pagination.

Returns

A list of threads, with nextCursor next to it. Each thread has:

idstring: The thread.
subjectstring: Its subject.
statusstring: open, in_progress, closed, spam or trash.
isImportantboolean: Whether it’s marked important.
participantslist of strings: Every address in the conversation.
messageCountnumber: How many messages it has.
lastMessageAtstring: When the newest one was sent or arrived.
previewstring: A line of the newest message, as plain text, safe to show.
fromobject or null: Who it’s from, as address and name.
nextCursorstring or null: Next to data: pass it back as cursor for the next page. Null on the last page.

Errors

400unknown_view: view isn’t one of the list above, which the message repeats.
400bad_limit: limit isn’t a whole number from 1 to 200.
400bad_cursor: cursor isn’t a nextCursor this API gave you.
401invalid_key: The key is wrong, expired or revoked. With no Authorization header at all, the code is missing_credentials.
403missing_scope: The key doesn’t have threads:list. The X-Required-Scope header names what’s missing.
429rate_limited: More than 120 requests a minute from this key. Wait for Retry-After seconds.

{ "data": [ { "id": "a41c93f0", "subject": "Invoice INV-2026-0841", "status": "open", "isImportant": false, "participants": [ "maria@example.com", "accounts@aegeanfreight.gr" ], "messageCount": 1, "lastMessageAt": "2026-09-26T15:42:10.000Z", "preview": "Please find the September invoice attached.", "from": { "address": "maria@example.com", "name": "Maria Papadaki" } } ], "nextCursor": "2026-09-26T15:42:10.000Z|a41c93f0" }