Mail Client

Start Google/Gmail OAuth — returns an authorisation URL to open in the browser. If an account is already connected, returns it without regenerating a URL.

Start Microsoft Outlook / Office 365 OAuth — returns an authorisation URL. For on-premise Exchange or non-OAuth Microsoft accounts use connect_imap instead.

Start Yahoo or AOL OAuth — returns an authorisation URL. For direct IMAP access to Yahoo/AOL use connect_imap instead.

Connect an email account via IMAP/SMTP credentials — iCloud, Zoho, Yandex, Mail.ru, webhostmost, any custom domain. Auto-detects server settings; tests connection before saving. Use this when OAuth is unavailable.

List all connected email accounts with their actual email addresses, provider (Google/Microsoft/Yahoo/IMAP), which is active, and unread count. Use when user asks 'what email addresses do I have', 'show my accounts'. Returns exact addresses like ignat@webhostmost.com, NOT generic types.

Change the active email account. All subsequent inbox, send, and manage operations will use this account until switched again.

Remove a connected email account and permanently delete its stored credentials and access tokens.

PRIMARY function to LIST recent emails (newest first). Use when the user wants to see/check their inbox or asks for recent/latest/new mail. Use folder= for non-inbox folders (sent/spam/trash/drafts/starred/archive). Returns a CAPPED PAGE of message previews (IDs, subjects, senders, dates, read state) — it is NOT the whole folder and carries no folder total; use has_more to page. ROUTING — do NOT answer these from this capped page: (a) COUNT questions ('how many / total / all') → call count_emails(); (b) emails for a specific DATE or period ('today / this week / since 1 June') → call search() with a Gmail date operator (today=newer_than:1d, week=newer_than:7d, month=newer_than:30d, range=after:2026/06/01 before:2026/06/07); (c) by sender or keyword → call search(). NEVER report the length of this list as a count or total — it is a capped page.

Open and read the full content of an email by message_id. Returns body (HTML + plain text), sender, all recipients, date, attachments. Also marks it as read. ALWAYS call this after inbox() or search() before replying, forwarding, archiving, or doing anything that requires knowing what the email says.

Read the actual TEXT CONTENT of one attachment on an email you already received (PDF/DOCX/XLSX/PPTX/image/txt/csv) — not just its filename/size. ALWAYS call read_email() FIRST to get the attachment's id from its attachments[] list, then pass that id here. Extraction runs in a shared engine and may take a few seconds for a first-time read; if status comes back 'processing', call again shortly. Large attachments are returned truncated (see truncated=true).

Find and DISPLAY emails — returns a capped preview page for reading. GMAIL QUERY RULES: (1) from: by BRAND NAME — 'from:reddit' not 'from:reddit.com'; 'from:linkedin' not 'from:linkedin.com'. Bare brand catches all subdomains. (2) Full address only when user gives one: from:noreply@company.com. (3) No bare keyword for sender — that's body search. (4) DATES: today=newer_than:1d, week=newer_than:7d, month=newer_than:30d, range=after:2026/06/01 before:2026/06/06. COUNTING: do NOT count rows here — call count_emails() for 'how many'. BULK ACTIONS: do NOT use search() + bulk_delete/archive loop — use archive(query=...) / delete(query=...) / apply_actions(query=...) directly. OLDEST EVER: oldest_first=true + max_results=1.

Fetch a page from a specific non-INBOX folder (sent, drafts, spam, trash, starred, archive). Functionally identical to inbox() with folder= — prefer inbox() unless explicit folder routing is needed.

Load a complete email conversation by thread_id — all messages in chronological order. Works on Google and Microsoft; IMAP returns a single-message fallback.

Send a brand-new email. Requires to and body; subject is auto-generated from the first line of body if omitted. Pass is_html=true when body is HTML (e.g. content handed off from another extension's rich-text editor) so formatting renders instead of showing raw tags. Use reply() or forward() when responding to an existing message.

Reply to an email. REQUIRED chain: 1) inbox() or search() to find the email and get message_id, 2) read_email(message_id) to read its content, 3) reply(message_id, body=<your response>). NEVER skip read_email() — you must know what you are replying to. Only omit message_id if read_email() was already called in this same session. Use send() for new emails, not replies.

Forward an existing email to a new address. REQUIRED chain: 1) inbox() or search() to find the email and get message_id, 2) read_email(message_id) to load its content, 3) forward(message_id, to=<address>). NEVER skip read_email() — the original body must be loaded before forwarding. Requires message_id and to address.

Analyze what's in your inbox — who writes most, which domains send most. group_by='sender' (default): top individual senders ranked by count. group_by='domain': top sending domains — useful for newsletter/outreach analysis. Use when user asks: 'who emails me most?', 'top senders', 'which domains spam me'. Default: top 10 over last 90 days.

Archive emails — removes from INBOX, stays recoverable (Gmail: All Mail; Outlook: Archive folder; IMAP: moves to Archive). Single email: message_ids='<id>'. Multiple emails: message_ids='id1,id2,id3'. ALL matching a pattern: query='from:linkedin' — iterates until none remain. Provide message_ids OR query, not both.

Move emails to Trash — RECOVERABLE (Gmail: 30 days; Outlook: until emptied). Single: message_ids='<id>'. Multiple: message_ids='id1,id2'. ALL matching: query='from:newsletter' — iterates until none remain. Use purge() for permanent deletion. Provide message_ids OR query.

Mark emails as read (read=true, default) or unread (read=false). Single: message_ids='<id>'. Multiple: message_ids='id1,id2'. ALL matching: query='from:linkedin' — processes until none remain. Provide message_ids OR query.

Star (starred=true, default) or unstar (starred=false) emails. Single: message_ids='<id>'. Multiple: message_ids='id1,id2'. ALL matching: query='from:boss@company.com'. Provide message_ids OR query.

Move emails to a folder. to_folder is required. Single: message_ids='<id>'. Multiple: message_ids='id1,id2'. ALL matching: query='from:linkedin' — moves all until none remain. Examples: move to 'spam', 'INBOX', 'Archive', 'trash', or a custom label. Provide message_ids OR query.

Apply MULTIPLE operations to the SAME emails in one efficient call. Use when combining actions on same set: ['read','archive'], ['unsubscribe','archive','read']. Gmail: label ops combined into ONE batchModify. Allowed: 'archive', 'read', 'unread', 'star', 'unstar', 'delete', 'unsubscribe', 'move_to_label:LABEL_NAME'. 'move_to_label:LABEL_NAME': apply a Gmail label/folder by exact name, e.g. 'move_to_label:Work'. 'unsubscribe': reads List-Unsubscribe header from most recent matching email and calls it. ALL matching: query='from:neil patel'. Single: message_ids='<id>'. For single-operation use archive/delete/mark_read/star directly.

Bulk cleanup by category or sender — no need to know the exact query. categories: 'promotions', 'social', 'newsletters', 'outreach', 'updates', 'forums', 'spam'. Gmail maps to native category: labels; Outlook/IMAP use pattern matching. Use when user says 'clean up obvious outreach', 'archive all promotions', 'delete my newsletters', 'unsubscribe from this sender'. from_senders=['neil patel'] for specific senders. operation: 'archive' (default), 'delete', 'read', 'star', 'unsubscribe' (find List-Unsubscribe header and call it).

PERMANENTLY delete emails — cannot be recovered from Trash or anywhere. Single: message_ids='<id>'. Multiple: message_ids='id1,id2'. ALL matching: query='from:newsletter@X.com'. Use delete() first if unsure (moves to Trash, recoverable). Provide message_ids OR query.

List address book contacts, optionally filtered by name or email fragment. Results sorted by name.

Save a new contact to the address book manually. Email is required; display name is optional.

Import contacts from the connected email account — Google People API, Microsoft Graph, or sender/CC header harvest from recent messages.

Remove a contact from the address book by their exact email address.

Panel compose form submit — sends from the UI compose panel (mode: new/reply/forward). From LLM chat use send(), reply(), or forward() instead.

Panel UI action dispatcher — called by inbox row buttons, not LLM chat. From chat use archive(), delete(), mark_read(), star() etc. individually.

Get current unread message count for all 7 folders simultaneously — INBOX, sent, drafts, spam, trash, starred, archive.

Return the EXACT NUMBER of emails — use for ANY 'how many' question. CRITICAL: never answer a count by counting the items returned by inbox()/search()/folder() — those are capped display pages, not totals. Pass folder= for a folder/state count: 'all' (whole-mailbox total), 'unread', 'spam', 'archive', 'inbox', 'today', 'sent', 'trash'. OR pass query= for a date/sender count in Gmail syntax: 'newer_than:1d' (today), 'after:2026/06/05 before:2026/06/06' (one specific day), 'from:reddit'. Counts ALL connected accounts unless account= is given. Returns a per-account breakdown plus a 'total' key.

Panel add-account wizard helper — returns OAuth URL for Google or Microsoft. From LLM chat use connect() or connect_microsoft() instead.

Panel add-account wizard helper — connects an IMAP account from the UI form. From LLM chat use connect_imap() instead.

Create a smart mailbox (virtual folder). Can filter by domain (from_contains='linkedin.com'), by exact emails (from_emails=['alice@x.com','bob@y.com']), by subject keyword, or any combination. After creating, use apply_filter to see matching emails.

List all saved smart mailbox filters (virtual folders). Shows criteria for each. Use filter_id with apply_filter() to view matching emails.

Apply a smart filter and return matching emails. Pass filter_id OR filter name — both work. Optionally increase max_results (default 20, max 200) for deeper full-mailbox search.

Update a smart filter — rename it or change its search criteria. Pass filter_id OR filter name — both work.

Delete a smart filter. Pass filter_id OR filter name — both work. The emails are NOT deleted, only the filter definition.

Set which mail folders are shown in the inbox view. WARNING: this REPLACES the entire visible set — it does NOT add to it. When the user asks to ADD a folder (e.g. 'add starred'), you MUST first call get_folder_prefs to read the current visible folders, then pass the existing list PLUS the new one. Always include 'INBOX' unless the user explicitly asks to hide it. Pass an ordered list like ['INBOX','starred','sent']. Pass an empty list to reset to showing ALL folders. TRIGGERS (this is about PANEL VISIBILITY, NOT listing emails — do NOT call inbox()/folder() for these): 'show/display these folders in the panel', 'add starred to my folders/panel', 'hide trash from the panel'.

Show current folder visibility settings — which folders are visible and which are hidden in your inbox view.

List all available mail folders and custom labels, showing which are visible or hidden in the panel. Gmail shows 'All Mail' instead of 'Archive' (Gmail has no system Archive folder). Custom folders created via create_mail_folder() also appear here. Use when user asks 'what folders do I have'.

Create a new folder or label in the connected mail account and add it to the panel sidebar. Gmail: creates a Gmail label (labels = Gmail's folder system). Outlook: creates a real mailFolder. IMAP: creates a server-side folder. GMAIL ARCHIVE NOTE: Gmail has NO built-in system Archive folder — archiving in Gmail = removing INBOX label (email stays in All Mail, not a separate folder). If the user wants a physical folder to browse in Gmail, create it with this function first (e.g. 'Archive', 'Work', 'Receipts'), then use move() or bulk_move() to put emails there. After creation the folder appears in the sidebar.

Delete a custom folder or label and remove it from the sidebar. Gmail: deletes the Gmail label — emails inside are NOT deleted, they stay in All Mail. Outlook: deletes the mailFolder — emails are moved to Deleted Items. Cannot delete system folders (INBOX, Sent, Trash, Spam, Drafts, Starred).