Returns the available accounts (your mailbox plus shared ones), folders with message counts (unread) and the addresses you can send from. Call it first when you do not know which folders or accounts exist. Changes nothing.

Searches mail (full text, sender, recipient, subject, folder, date, unread, attachments) or lists a whole thread. Returns message ids (for mail_get_email), thread, sender, date and a preview. Newest first, paging through limit/offset. Without a filter it returns the latest messages from all folders (trash included) — for “what is new” use mailbox="inbox", unread=true.

Returns a whole message by id (from mail_search_emails): headers, body text (HTML is converted to text) and the list of attachments. mail_get_attachment reads an attachment's content (PDF, image, text). To reply use mail_send_email with in_reply_to_id. Changes nothing (does not mark the message as read).

Downloads an attachment of a received message, saves it to disk and returns its content: text for text files, the text of every page for PDFs, the picture for images. Scans (PDF pages without a text layer) and photos of documents are read through OCR, tables included; pages that came from OCR are marked “(OCR)” — treat numbers from them with some caution and ask for a preview when a figure matters. Other types (docx, xlsx, zip…) only return the path of the saved file. Pick the attachment by name or by its number from the list in mail_get_email; a message with a single attachment needs neither. The message itself is not changed.

Sends an e-mail from the mailbox — a new one, or a reply (in_reply_to_id). A copy is stored in Sent. It sends IMMEDIATELY and cannot be undone. Send only when the user explicitly said the message should go out; otherwise create a draft (mail_create_draft). Verify the recipient before sending — never guess an unknown address, look it up with mail_search_contacts.

Saves a message as a draft in the Drafts folder (does not send). The user can then review it in webmail or on the phone and send it themselves, or mail_send_draft sends it by id. Same parameters as mail_send_email (including replying via in_reply_to_id and attachments).

Sends an existing draft by id (from mail_create_draft or from a search in the drafts folder). Sends immediately — only on the user's explicit instruction.

Permanently deletes a draft by id. Works only on messages flagged as drafts — it never deletes sent or received mail.

Finds an e-mail address or phone number: searches the address books (your own and shared ones) and also the mail history (who wrote to you and whom you wrote to, matching the query). Use it whenever you need a person's or company's address before sending anything. Without a query it lists the whole address book.

Creates a contact in an address book. Default is the signed-in mailbox's own address book; pass the account of a shared mailbox to store it in the shared one (everyone with access sees it, on phones too through CardDAV). Check mail_search_contacts first so you do not create a duplicate.