Mail Client

What you get

• connectread

  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.

• connect_microsoftread

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

• connect_yahooread

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

• connect_imapwrite

  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.

• statusread

  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.

• switch_accountwrite

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

• disconnectdestructive

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

• inboxread

  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.

• read_emailread

  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.

• searchread

  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.

• folderread

  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.

• get_threadread

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

• sendwrite

  Send a brand-new email. Requires to and body; subject is auto-generated from the first line of body if omitted. Use reply() or forward() when responding to an existing message.

• replywrite

  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.

• forwardwrite

  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.

• inbox_analyticsread

  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.

• archivewrite

  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.

• deletewrite

  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_readwrite

  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.

• starwrite

  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.

• movewrite

  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_actionswrite

  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'. '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.

• inbox_cleanupwrite

  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).

• purgedestructive

  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.

• contactsread

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

• add_contactwrite

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

• sync_contactswrite

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

• delete_contactdestructive

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

• compose_sendwrite

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

• mail_actionwrite

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

• folder_countsread

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

• count_emailsread

  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.

• get_oauth_urlread

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

• add_imapwrite

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

• create_filterwrite

  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_filtersread

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

• apply_filterread

  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_filterwrite

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

• delete_filterdestructive

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

• set_folder_prefswrite

  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', 'покажи/отображай папки X и Y в панели', 'добавь starred в мои ящики/в панель', 'hide trash from the panel'.

• get_folder_prefsread

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

• list_mail_foldersread

  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_mail_folderwrite

  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_mail_folderdestructive

  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).