Mailopoly Inbox

Create a rule that hides matching tasks from the user's task manager (the emails themselves stay in the inbox). Provide at least one of: sender_email (exact address), sender_domain (e.g. 'example.com'), or subject_contains (case-insensitive phrase). Optional task_type narrows the rule to one of: reply | invoice | event | action | shipment. Rules are reversible — see list_task_rules / delete_task_rule.

create_task_rule

Create a smart email list from a plain-language description of what belongs in it (e.g. a brand's emails, messages from a connected app, a topic, emails containing invoices). The rules are derived from the user's actual data — real sender domains, connected apps, categories — and existing matching emails are filed in immediately; future emails auto-file. Returns the created list with the generated rules, the reasoning, and how many emails matched, so you can confirm it captured the intent (browse it with get_feed(list_id=...)). name overrides the generated list name. exclude_from_cleanbox=true also hides matching emails from the main feed (only on explicit user request).

create_email_list

Set up a monitor that fires whenever a matching email arrives in the user's mailbox — "alert me when…". Fired events queue server-side; any later conversation sees a trigger_alert notice on read results, and poll_pending_actions collects the events (so schedule a recurring check-in for time-critical monitors). Conditions (AND-combined; at least one required): sender (address or name fragment), subject_contains, body_contains, folder ('cleanbox'|'other'), email_type ('received' default | 'sent'), has_attachments, threat (true = only emails Mailopoly's threat classifier flagged). semantic_condition is a natural-language test (e.g. "the sender is angry or threatens to cancel") — it is NOT matched server-side; it travels with each fired event for YOU to apply when collecting, so pair it with at least one structured condition to pre-filter. runbook: natural-language standing instructions for what to do when it fires (travels with every event). guardrail_tier: draft_only (default) | notify_hold | auto_with_undo. assigned_agent: optionally route this trigger's fired events to ONE registered agent (name from identify_agent) — only that agent's polls receive them, and if it registered a webhook each event is POSTed to it immediately; leave unset so any of the user's assistants can collect. The response includes how often this WOULD have fired in the last 48h with samples — relay that to the user and tighten over-broad triggers before confirming. Good monitors to suggest: payment/ direct-debit failures, invoices from a key supplier, mail from a named client or domain, security/sign-in alerts, anything Mailopoly flags as a threat.

create_email_trigger

Search the user's COMPLETE email history by querying their connected mail providers live — Gmail, Outlook AND IMAP accounts (iCloud, Yahoo and other IMAP mailboxes) — reaching years beyond Mailopoly's indexed window, and including sent mail. This is also how you reach mail a free trial hasn't imported yet: the trial fully processes only recent mail, but the rest still lives in the user's mailbox and this tool finds it. Use it when search_emails returns few or no results, or when the question concerns emails older than the indexed history (search_emails responses include indexed_history_start). TIME BUDGET: the live crawl is deliberately capped server-side (typically 5-45 seconds for Gmail/Outlook, up to ~90 seconds when an IMAP account like iCloud/Yahoo is being walked) so this call ALWAYS returns a usable response before your own tool-call timeout — never refuse to run it just because an account is iCloud/IMAP; just tell the user you're searching their full history and it may take a moment. If the crawl hits its budget the response says so in `note` and `provider_error`, and the results returned are what was found in time. PAGINATION is by date, not offset: re-run with end_date set to a truncated provider's oldest_returned_date (from truncated_providers) to page deeper into history, or narrow with a sender/start_date/end_date window. start_date/end_date (YYYY-MM-DD) may span multiple years; omit both to search ALL history. Returned email_id values (some of the form 'gmail:<id>:<id>' or 'imap:<id>:<uid>') work directly in get_email, which reads the full body AND extracts attachment text (PDFs, Office docs) live from the provider — use it to read a document attached to an old email. They ALSO work in the action tools — send_email / save_draft (reply_to_email_id), create_task, add_email_to_list, mark_email_read, hide_emails: acting on a provider-history email automatically imports that one email into Mailopoly first, so you can reply to, task or file ANY email in the user's history, not just recently imported mail.

deep_search_emails

Delete a task-suppression rule by id (from list_task_rules). The previously hidden tasks reappear in the task manager.

delete_task_rule

Delete one of the user's email lists (soft delete; id from list_email_lists). The emails themselves are NOT deleted — they return to the normal inbox views.

delete_email_list

Delete one of the user's email triggers (id from list_email_triggers). Its uncollected events are dropped too.

delete_email_trigger

Get the actionable links (pay now, log in, book, track package, manage subscription…) extracted from the given emails. Ids must come from this user's emails.

get_action_links

The user's My Data dashboard widgets (weather, news, stocks, custom) with their latest cached data. refresh=true re-fetches any widget whose rate limit allows it (e.g. weather every 10 min) before returning. include_catalog=true also lists the available widget types.

get_widgets

Hide one or more emails from the user's feed (does not delete them). Optional reason, e.g. 'spam', 'not_interested', 'never_show_this_sender'.

hide_emails

Given an email address or domain, return the best way to connect it and the exact steps. Prefers one-click OAuth (oauth_available / oauth_provider) when we run a connector for that host — no password needed. Otherwise returns imap_suggestion with the host/port, the provider's help_url, and the app-password steps (app_password_note / instructions). Use this to walk a user through getting connected — especially IMAP users who need an app-specific password. This returns GUIDANCE only; it never fetches or receives a password.

get_connect_instructions

List the user's calendar events extracted from their email (meetings, bookings, appointments). Dates are YYYY-MM-DD; defaults to upcoming.

list_events

List the user's connected email accounts with their connection health and onboarding state. Use this to diagnose "I can't connect" / "my email isn't showing up" problems. Each account has a `status`: active, onboarding, pending, not_syncing (connected but never activated), reauthorization_required (needs reconnecting), or inactive (paused). Also returns mailbox_verdict and last_check_error when present. Connected messaging apps (Slack etc.) appear with kind='app'.

list_email_accounts

List the user's email drafts (created in Mailopoly), newest first.

list_drafts

The user's custom email lists (smart folders): name, rules, unread and total counts. Browse a list's emails with get_feed(list_id=...); file/unfile specific emails with add_email_to_list / remove_email_from_list.

list_email_lists

List the user's email triggers ("alert me when…" monitors): their conditions, runbooks, guardrail tiers, firing stats and how many fired events are still waiting to be collected via poll_pending_actions.

list_email_triggers

List invoices, receipts, bills and payments extracted from the user's email. Backed by the SAME schema-aware finance query Poly uses, so results are COMPLETE across every vendor (not just the first one). - invoice_or_payment: the RECORD TYPE to filter by — e.g. "receipt", "invoice", "payment", "refund", "statement", "order". Matched fuzzily, so "receipt" also catches "payment receipt" / "order". Pass the TYPE here, NOT a vendor name. Omit for all types. - search: a VENDOR / payee / description / category substring (a shop or supplier name). Omit to list across all vendors. - time_range examples: this_month, last_month, this_year, last_year, or last_30_days; or pass start_date / end_date as YYYY-MM-DD. Returns the most recent `limit` records, the total matched, a per-vendor `vendor_breakdown` and grand/paid/outstanding totals — all computed over the FULL matching set, not just the returned page. To answer 'which vendors' or 'any receipts other than X', read `vendor_breakdown` instead of paging.

list_invoices

List the user's task-suppression rules (rules that hide tasks from the task manager by sender, domain or subject). Returns rule ids usable with delete_task_rule.

list_task_rules

List the user's tasks (aggregated from manual tasks, email actions, invoices, events, shipments and replies — the same data as the app's task manager / My Day). timeframe: relevant | today | tomorrow | this_week | this_month | overdue | last_7_days | next_30_days | all. task_type: all | action | event | invoice | shipment | reply.

list_tasks

Mark an email as read (or unread with read=false).

mark_email_read

Send a message to another of the user's agents through Mailopoly — the agents' switchboard: works across machines, codebases and clients, because every agent talks to the same Mailopoly account. to: a registered agent name, or 'all' to broadcast to every other agent. Delivery is durable: recipients get it on their next poll_pending_actions, see an ambient notice on any Mailopoly call, and if they registered a webhook it is POSTed to them immediately. Use topic to label threads of work (e.g. 'deploy-status'). Set ping_user=true ONLY when the user should be interrupted about it too. Pass YOUR agent_token from identify_agent — required when this connection hosts more than one agent; the sender name is stamped from it and cannot be spoofed. If you EXPECT A REPLY, don't wait passively: poll_pending_actions on an interval (background-timer loop, 1-5 min) until it arrives — see that tool's guidance.

send_agent_message

The user's My Day view: today's tasks, events and commitments.

get_my_day

Pause (turn off) a connected account: stop downloading new mail while KEEPING everything already brought in. `account` is the connected email address. Reversible with resume_email_account. Confirm with the user before pausing — it stops their email from updating.

pause_email_account

Send a short push notification to the user's phone — "ping me if anything goes wrong / when it's done". Use for things worth interrupting the user over; for agent-to-agent coordination use send_agent_message. Guardrails (server-enforced): the notification is visibly labeled with the sending agent's registered name, links are stripped from the body, and daily caps apply per agent and per user. Pass YOUR agent_token from identify_agent — required when this connection hosts more than one agent. If the user has no registered mobile device, this reports devices_notified=0 — fall back to send_email to their own address.

notify_user

The user said "not now" to a poly_nudge (or asked the nudges to stop). With ref_id: quiets that item for a day and the whole nudge stream for a few hours (the quiet doubles with consecutive dismissals, 3h -> 6h -> 12h -> 24h); pass hours when the user said WHEN ("remind me in 2 hours" -> hours=2) to set the exact window instead. all_for_today=true is "dismiss them all / that's everything for today": quiets the whole stream until the end of the user's local day without penalising any item. mute_all=true switches the ambient nudge stream off entirely ("stop suggesting things"); unmute_all=true switches it back on. For "never show me THIS again" use resolve_priority(action='not_relevant') instead — that's permanent. This state is shared with the Mailopoly app — a dismissal here quiets the app's nudges too. After dismissing, do not re-raise that item yourself; Mailopoly will resurface it when the quiet window ends.

dismiss_nudge

Get a draft's full content (to, cc, bcc, subject, body).

get_draft

Read a single email in full: subject, sender, recipients, date, the complete message text, attachments (each with its extracted text content when available — read these for invoice/proposal/PDF details that aren't in the body), and (optionally) actionable links found in it (pay, log in, book, track…). Accepts ids from search_emails, get_feed AND deep_search_emails — provider-history ids (the 'gmail:<id>:<id>' form) are fetched live from the mail provider, INCLUDING their attachments' text, which is extracted on the fly (PDF / Word / Excel / CSV / iCal) — so a settlement statement or invoice attached to a years-old email is readable here, not just its filename. THREADS: for a threaded email the response carries a thread block (messages_local, may_be_incomplete). When may_be_incomplete is true the conversation starts before Mailopoly's imported window — fetch the earlier messages with deep_search_emails (or say plainly that you can only see part of the thread) BEFORE summarising it or drafting a reply.

get_email

Register (or update) an agent identity — a short name like 'deploy-watcher' or 'SESSION-A' for what this session is. Do it once at the start of a session, before send_agent_message / notify_user. The response includes an agent_token: KEEP IT and pass it on later agent calls — it IS your identity, letting many sessions share one Mailopoly connection while staying distinct and unforgeable (the sender name on everything you send is derived server-side from the token, and a name registered by another connection cannot be taken). Re-registering a name you created from the same connection without its token re-claims it and ROTATES the token (recovering after a lost session; the old token stops working). To rename yourself, pass your agent_token with the new name. webhook_url (https, publicly reachable): when set, events addressed to this agent are POSTed there immediately, signed with the returned webhook_secret (X-Mailopoly-Signature: sha256=HMAC(secret, body)) — true push for self-hosted runners; pass an empty string to clear it. The response also lists the user's other ACTIVE agents — who you can message. LIFECYCLE: abandoned agents clean themselves up. Inactivity (no MCP activity under this identity — webhook deliveries do NOT count as activity, only actually acting does) expires an agent automatically: default 30 days for plain sessions, 7 days for webhook agents. expires_after_hours overrides this per agent (1-8760) — set it short (e.g. 24) for throwaway sessions so they vanish on their own, long for durable runners. Expired/idle agents drop out of rosters and 'all' broadcasts first. When a session finishes its job for good, retire it immediately with retire_agent instead of waiting.

identify_agent

Remove an email from one of the user's email lists. Note: if the email matches the list's rules it may be re-added when the rules are re-evaluated — edit the list's rules in the app for a permanent exclusion.

remove_email_from_list

Apply the user's decision to a priorities item (a ref_id from get_priorities or a poly_nudge). action: 'mark_paid' (bill paid), 'mark_partial_paid' (needs paid_amount), 'snooze' (remind later — snooze_hours or snooze_days, default 14 days), 'complete' / 'handled' (done, e.g. a reply they say is dealt with), 'acknowledge', or 'not_relevant' ("never show me this again" — permanently suppresses the item from nudges, briefings and future reports; reversible only by un-hiding the task in the Mailopoly app, so confirm intent before using it). Pass the item's `source` object back VERBATIM and its headline as title. The change lands in the same task/invoice rows the app uses, so My Day, Tasks and future briefings all reflect it immediately. Item options that are views rather than dispositions map to other tools ('open_reply' is NOT a valid action here and will be rejected): 'view_email' -> get_email(source.email_id), 'open_reply' -> send_email with reply_to_email_id (offer the item's suggested_reply first), 'set_reminder' -> create_task with a reminder_date.

resolve_priority

Close out a collected trigger event (id from poll_pending_actions) with a short outcome — what was done, or 'dismissed: <reason>'. This is the audit trail; every collected event should end here.

resolve_trigger_event

Resume a previously paused account so it starts syncing again. `account` is the connected email address. After resuming you may need start_email_account_sync if it still shows as not syncing.

resume_email_account

Remove a registered agent by name — use when a session's job is done, or to clean up stale entries the user points out. Any of the user's connections may retire any of their agents (re-registering the name revives it fresh). The agent's queued events are expired. Idle agents also fade out automatically, so this is for immediate cleanup, not a required sign-off.

retire_agent

Create an email draft (or update an existing one by draft_id). The draft appears in the user's Mailopoly drafts and can later be sent with send_email (requires the 'send' scope). to/cc/bcc are email addresses, comma-separated for multiple recipients. For a reply, pass reply_to_email_id (the original's email_id) — to is then optional and the reply is routed automatically when sent, including replies to connected-app messages (Slack etc.), which have no email address. body is plain text or HTML.

save_draft

Search the user's emails by free text (subjects, senders, bodies, attachment text). Natural language works, and so do Boolean OR-lists, quoted "exact phrases" and Gmail-style operators (from:, to:, subject:, newer_than:3d, older_than:, has:attachment) — pass the query however it reads most naturally. Optional filters: sender (name or address fragment), start_date/end_date (YYYY-MM-DD), last_x_days, email_type ('received' or 'sent'), and folder — 'cleanbox' (genuine personal correspondence), 'other' (promotional/newsletters/ads), or 'all'. BY DEFAULT search covers EVERYTHING unfiltered; only pass folder to restrict it. personal_or_ad is a deprecated alias for folder ('personal'=cleanbox, 'advertising'=other). account narrows the search to ONE connected mailbox (the address as shown in get_account_overview / list_email_accounts) — e.g. search only the user's work inbox for "invoice from Bill". Works for every connected address, including @mly.life. sort_order: omit for relevance-and-recency ranking (default); pass 'oldest' when the user wants their earliest/oldest/ first emails (chronological, oldest first) or 'newest' for strict newest-first. Returns matching emails with ids for use in get_email / get_action_links. PAGINATION: results are a page — total_count is how many matches exist in all; to get more, re-call with offset=<results so far> (limit caps at 50 per page). COVERAGE: this searches Mailopoly's indexed history only, and every response says exactly what that is — indexed_history_start (the oldest indexed date) plus a coverage_note with the mailbox's true size at the provider. When the user's question could reach mail older than indexed_history_start, escalate to deep_search_emails rather than concluding the mail doesn't exist.

search_emails

Send an email as the user through their connected account (Gmail, Outlook, @mly.life or IMAP), or reply to any message by passing reply_to_email_id (an email_id from search/feed/get_email). Replies: with reply_to_email_id set, to/subject are optional — the recipient and threading come from the original. If the original is a message from a connected app (source != 'email', e.g. Slack), the reply is delivered back through that app as the user (same thread/DM) — do NOT pass an email address for app messages; their senders have none. If draft_id is given, the draft's content fills any field not explicitly provided. from_account selects which connected address to send from (defaults to the account the original arrived on for replies, else the primary). body: plain text or HTML — plain text is formatted into clean paragraphs automatically (blank line = new paragraph), so just write naturally; pass HTML yourself only when you want rich formatting (links, bold, lists). Do NOT pass markdown — it is not rendered. content_type: 'HTML' (default) or 'TEXT' (send as-is, no formatting). Subscription limits apply.

send_email

Set the user's preferred language for the emails, reports and app content Mailopoly sends them — a BCP-47 code like 'es', 'fr', 'de', 'pt', 'ja', 'ar', 'zh', 'ru'. Call this ONCE, early, as soon as you can tell from the conversation which language the user actually speaks/writes (e.g. they message you in German → call set_language('de'); their first request is in Arabic → set_language('ar')). This does NOT change how you reply in this chat — it makes their Mailopoly emails and website render natively, which they otherwise can't tell you because they never see English here. If the user clearly uses English, just skip it (English is the default). Takes effect immediately and never overrides a language the user picked themselves in Mailopoly's settings.

set_language

Update the user's timezone. `timezone` must be an IANA name like 'America/New_York', 'Europe/London' or 'Asia/Kolkata' — NOT an abbreviation (EST) or a UTC offset. Call this whenever the user says they've moved or are travelling, gives their location/timezone, or tells you the times you're showing are off by a fixed number of hours: the server localizes every timestamp it returns to this zone, so fixing it here corrects all of them. The change takes effect immediately.

set_timezone

The user asked "what else / show me the next one" on a nudge: rest the skipped item briefly (it can return later today) and surface the next eligible priority. This is a user-initiated pull, so it bypasses the stream's quiet window and daily cap — only call it when the user explicitly asks to see the next item. Returns the next nudge (with a pre-written suggested_reply when it's a reply), or none_eligible when the queue is empty.

next_nudge

Snooze a task. Either pass snooze_until (ISO datetime, in the given timezone — defaults to the user's own timezone) or a relative duration (duration_value + duration_unit, e.g. 3 + 'days', 2 + 'hours', 1 + 'weeks').

snooze_task