owlpost

Delete a message by moving it to the account's Trash folder. The Trash folder is discovered via SPECIAL-USE (e.g. "Deleted Messages" on iCloud, "[Gmail]/Trash" on Gmail). The message is not permanently expunged from Trash, so it can still be recovered from the mail client. Args: account: Account name from list_accounts. folder: Folder the message is currently in. uid: Message UID in that folder.

Flag (star) or unflag a message by setting or clearing its \Flagged flag. Args: account: Account name from list_accounts. folder: Folder containing the message. uid: Message UID. flagged: True to flag (default), false to remove the flag.

Forward a message to new recipients and send it immediately; confirm with the user first. The subject gets a "Fwd:" prefix, the original headers and plain-text body are included below your note, and the original attachments are re-attached unless include_attachments is false. Args: account: Account name from list_accounts. folder: Folder containing the message to forward. uid: UID of the message to forward. to: Recipient email addresses. body: Optional note placed above the forwarded content. cc: Cc recipient addresses. bcc: Bcc recipient addresses. attachments: Extra local file paths to attach. include_attachments: Re-attach the original message's attachments (default true).

Return every message in the same conversation as a given message, oldest first. On Gmail this uses the X-GM-THRID thread id across All Mail. Elsewhere it follows the Message-ID / In-Reply-To / References graph across the inbox, sent, archive, all-mail and drafts folders, so your own replies are included. Returns envelopes (no bodies); use read_email for content. Identify the seed message with either `message_id`, or `folder` + `uid`. Args: account: Account name from list_accounts. message_id: Message-ID header of any message in the thread, including angle brackets. folder: Folder of the seed message (used with uid). uid: UID of the seed message (used with folder).

List the mail accounts configured in owlpost's accounts.toml. Returns one entry per account with its `name` (the value to pass as `account` to every other tool), email address, provider (icloud, gmail or generic), IMAP/SMTP hostnames and whether sent mail is auto-saved. Passwords and password sources are never included. Takes no arguments and does not contact any mail server.

List every IMAP folder (mailbox) in an account. Each entry has the folder `name` to use in other tools, its raw IMAP flags, the hierarchy delimiter, and a detected `role` (inbox, sent, trash, drafts, junk, archive, all, flagged, important) based on RFC 6154 SPECIAL-USE flags, or null for ordinary folders. Args: account: Account name from list_accounts.

Mark a message as read or unread by setting or clearing its \Seen flag. Args: account: Account name from list_accounts. folder: Folder containing the message. uid: Message UID. read: True to mark read (default), false to mark unread.

Move a message from one folder to another. Uses IMAP MOVE when the server supports it, otherwise COPY followed by flagging the original \Deleted and EXPUNGE. The message gets a new UID in the destination folder, so the old uid is no longer valid afterwards. Args: account: Account name from list_accounts. folder: Folder the message is currently in. uid: Message UID in that folder. dest_folder: Destination folder name (see list_folders).

Read one message: decoded headers, body and attachment list, without marking it read. By default only the plain-text body is returned, truncated at 50,000 characters to fit MCP result limits; the untruncated sizes are always reported as text_full_length and html_full_length. Attachments are listed with a 1-based `part` index for save_attachment. Threading headers (message_id, in_reply_to, references) are included. Args: account: Account name from list_accounts. folder: Folder containing the message. uid: Message UID from search_messages. include_html: Also return the HTML body (default false). HTML mail can be very large. include_text: Return the plain-text body (default true). body_max_chars: Truncate each body to this many characters (default 50000).

Reply to a message and send the reply immediately; confirm with the user first. Addresses the reply to the original sender (plus the original To/Cc, minus your own address, when reply_all is true), prefixes the subject with "Re:" if needed, sets In-Reply-To and References so clients thread it correctly, and quotes the original plain-text body below yours. Args: account: Account name from list_accounts. folder: Folder containing the message being answered. uid: UID of the message being answered. body: Your reply text; the quoted original is appended after it. reply_all: Also reply to the original To and Cc recipients. html: Optional HTML alternative for the reply. attachments: Local file paths to attach.

Resolve a special-use role to the provider-specific folder name. For example "sent" becomes "Sent Messages" on iCloud and "[Gmail]/Sent Mail" on Gmail. Uses SPECIAL-USE flags first and falls back to common folder names. Returns null if no matching folder exists. Args: account: Account name from list_accounts. role: One of inbox, sent, trash, drafts, junk, archive, all, flagged or important (case-insensitive).

Download one attachment from a message and write it to the local filesystem. The mailbox is not modified. Returns the written path, size, MIME type and original filename. An existing file at the target path is overwritten. Args: account: Account name from list_accounts. folder: Folder containing the message. uid: Message UID. part: 1-based part index from read_email's `attachments` list. save_to: Destination. A directory (trailing slash, existing directory, or a path without an extension) keeps the original filename; anything else is used as the full file path. `~` is expanded and missing directories are created.

Compose an email and save it to the account's Drafts folder without sending it. The message is appended to the special-use Drafts folder with the \Draft flag, so the user can review, edit and send it from their own mail client. Use this instead of send_email whenever the user wants to check a message first. Each call creates a new draft. Args: account: Account name from list_accounts. to: Recipient email addresses. subject: Subject line. body: Plain-text body. cc: Cc recipient addresses. bcc: Bcc recipient addresses. html: Optional HTML alternative to the plain-text body. attachments: Local file paths to attach. in_reply_to: Message-ID this draft replies to, for threading. references: Message-IDs of earlier messages in the thread.

Search one folder with structured filters and return message envelopes, newest first. All filters are combined with AND. String filters use IMAP case-insensitive substring matching; multi-word values are quoted for you. Each result has uid, folder, message_id, subject, from/to/cc, date, flags, size, seen and flagged; pass folder + uid to read_email for the body. The folder is opened read-only, so searching never marks mail read. Args: account: Account name from list_accounts. folder: Folder to search (default "INBOX"); use list_folders or resolve_folder for others. from_: Substring of the From header (name or address). to: Substring of the To header. cc: Substring of the Cc header. subject: Substring of the Subject. body: Substring of the message body. text: Substring of headers or body. since: Only messages on or after this date (YYYY-MM-DD). before: Only messages before this date (YYYY-MM-DD). unseen: Only unread messages. seen: Only read messages. flagged: Only flagged/starred messages. has_attachment: Best-effort filter for messages with attachments (multipart/mixed or an attachment disposition header). raw: A raw IMAP SEARCH string, e.g. 'OR FROM "alice" FROM "bob"'. When set, every other filter is ignored. limit: Maximum number of results (default 50).

Send a new email over SMTP immediately; this cannot be undone, so confirm with the user first. When the account has auto_save_sent enabled (needed for iCloud, whose SMTP does not keep a copy) the message is also appended to the Sent folder. Returns the generated Message-ID, recipients and the folder the copy was saved to (null if none). To answer an existing message prefer reply_email, which fills in recipients and threading for you. Args: account: Account name from list_accounts; mail is sent from its address. to: Recipient email addresses. subject: Subject line. body: Plain-text body. cc: Cc recipient addresses. bcc: Bcc recipient addresses (delivered but never written to headers). html: Optional HTML alternative to the plain-text body. attachments: Local file paths to attach. in_reply_to: Message-ID this message replies to, for threading. references: Message-IDs of earlier messages in the thread.