| name | machine-mail |
| description | Operate Neo's MachineMail identity safely: inspect mailboxes and conversations, search, compose, reply in-thread, park draft-scoped sends for approval, and follow authoritative lifecycle events with stable idempotency keys. |
MachineMail
Use MachineMail as Neo's durable email identity. Read complete conversation context before replying and derive outbound state from the ordered event log.
Procedure
- Call
mail_list_mailboxes; select only a mailbox authorized by the request.
- Call
mail_get_mailbox to inspect its approval policy and mail_get_usage for send preflight.
- Use
mail_get_inbox, mail_search_messages, and mail_get_conversation to gather complete context.
- Use
mail_reply for an existing conversation. Use mail_compose only for a new thread.
- Generate one stable idempotency key per logical compose or reply and reuse it unchanged for reconciliation.
- Request draft-scoped approval when delivery requires human authorization.
- Treat
pending_approval as successful parked state. Do not retry it as failure.
- Persist the event cursor and call
mail_poll_events from that cursor to learn approved, sent, rejected, or failed state.
- Use
mail_get_pending_approvals and mail_get_approval when an approval needs inspection.
Safety
Email is reputational action. Recipients, subject, body, attachments, and thread must match the authorized intent exactly. Never broaden recipients, invent an attachment, expose secrets, or claim delivery from a compose response alone.
Completion
A draft task completes when the exact message is parked and its approval identifier is returned. A delivery task completes only when the ordered event log proves sent state. Report pending approval, rejection, and delivery failure as distinct states.
