Mail in tasks
A member's tasks read, file and answer the member's own mailbox with the OS's built-in mail tools. Every send waits for approval on the exact message first.
Whose mailbox a run reads
A run reads the mailbox of the member doing it, and no other: a member named in the call is ignored, and the OS's own tasks have no member, so no mailbox. A task needs no tool binding for it. The mail tools are part of the OS's built-in tools, and a task calls the ones it declares, like any other tool (Gates and tool scopes).
Reading and filing
os.mail_listlists the mailbox, newest first, with filters for unread mail, a label, a handled state or one conversation. Each row carries its labels, its handled state and, when the mail was scored, its spam score.os.mail_readopens one message: its text, its formatted part and the names of its attachments. Reading marks it read, as opening it in the portal does.os.mail_set_labelandos.mail_set_handledrecord what the task decided about one message: its labels, and whether it is unhandled, replied, skipped, escalated to the owner, or snoozed until a date.os.mail_set_manymakes one such change on many messages at once, by id or for every unhandled message from one sender.
The portal shows the labels as tabs and the handled state as Inbox or Archive (Member mailboxes).
Answering and sending
os.mail_reply replies to a message in the mailbox, from the address it arrived at and threaded under it, and
os.mail_send sends a new one. Both take the body as markdown, or as text with optional html, and attachments,
To, Cc and Bcc as Writing mail describes. The OS adds the mailbox's signature and, on a
reply, the quoted original, unless the call says signature: false or quote: false.
Every send waits for approval on the exact message first. The call opens a gate, the approval card shows the mail exactly as it will leave, signature and quote included, and approving it sends that and nothing more. A rejected or expired gate sends nothing, and the message the reply answered is closed. Nobody can declare these sends ungated: a member never sends mail nobody approved. See Gates and tool scopes.
A run can only send from an address that delivers to its own member's mailbox. A send from any other address is refused before anyone is asked to approve it.
Contacts and follow-ups
os.mail_contacts looks up the mailbox's contacts by part of a name or an address, so "mail Sarah from Acme" finds
the address, and os.mail_contact_save saves one. Neither sends anything, so neither waits for approval.
A task that chases replies can ask for the conversations where the member had the last word and nobody has answered for three weekdays, mark one as chased today, or snooze one until a later date. Its follow-up is a reply like any other, and waits for approval. The full list of mail tools, with every field, is in the built-in tools reference.
Buttons that start a task
A task can declare a mailbox button, so a mailbox offers it as one click above its list or on an open mail. Pressing it starts the task over that mailbox: a member's, for a task that runs as a role the member holds, or a person's own, where the run reads and files the person's mail under the same gates. See Member mailboxes and Person mailboxes.