mail_list
Gate: ungated · no kind, zero authority · read
The way in to a mailbox: the newest messages of a folder, most recent first, with the UID mail_read needs. Ungated, because reading your own mail is context and never reach — the same argument that leaves memory_read and knowledge_search open. Newest-first is not a preference: a mailbox has no upper bound, and a listing that began at the start would spend the whole context on mail from years ago.
Input
| Field | Type | Required | Notes |
|---|---|---|---|
folder | string | no | Folder to list; defaults to INBOX. |
limit | integer | no | How many messages — default 10, capped at 50. |
Output
A JSON object {"messages": [...]}, each with uid, from, subject, date (RFC 3339) and unread. Any known vault secret a message echoes back is redacted before the text reaches the model.
From JavaScript
const inbox = nocturn.call("mail_list", { folder: "INBOX", limit: 10 });Notes
The four mail tools share one connection per workspace rather than logging in per call: a conversation is usually a listing followed by two or three reads, and a handshake and login for each of them is time the household pays for one question. It is dropped after five minutes unused, and a server that hangs up in the meantime costs one silent reconnect rather than an error. Every operation is bounded at a minute when the caller sets no deadline of its own. The fetch peeks: listing and reading never set the \Seen flag, so an agent skimming the inbox at six in the morning does not empty your unread list before you wake up. The tools exist only in a workspace that has a mail.json — no mailbox configured means no mail tools at all, rather than tools that fail on every call.