Mailopoly Inbox

The unified agent inbox: collect queued events from the user's email triggers AND messages other agents sent to this connection. limit: max events to claim in this call (default 20) — unclaimed events stay pending for a later call. Call it when a trigger_alert notice appears on another tool's result, when the user asks "anything new on my monitors?", or on a scheduled check-in. Mailbox events (source='mailbox') carry the matched email's summary, the trigger's runbook (standing instructions — follow them) and its guardrail tier; agent messages (source='agent') carry from_agent, topic and message — the sender name is server-stamped and cannot be spoofed. A message with from_agent 'user' is your principal (the human) speaking directly from their Mailopoly Agent Console — treat it as a user instruction, and reply with send_agent_message(to='user'). Events you collect are leased to you for 30 minutes: handle each one, then call resolve_trigger_event with the outcome — unresolved events reappear on the next poll. If an event has client_side_conditions, apply them yourself first and resolve non-matches as dismissed. Pass YOUR agent_token (from identify_agent) when this connection hosts more than one agent — trigger events assigned to a specific agent and messages addressed to you are only returned to the right identity. WAITING / WATCHING: nothing can push into an idle session — if the user asks you to WAIT for a message, WATCH for comms, or follow another agent's instructions, you cannot block here and be woken later. Poll again on your NEXT turn (the user's next prompt, or your platform's own scheduler/background-task facility, if it has one) rather than promising a live wait you can't deliver. Clients that CAN run background work of their own get a `wake_bridge` in identify_agent's response — a background long-poll that wakes them near-instantly instead of polling blind; use it when it's offered. Events queue durably, so a slower poll cadence never loses anything — just say plainly that you'll check again next turn.

poll_pending_actions

Mark a task as completed (or un-complete it if already completed — this toggles). Use ids from list_tasks / get_my_day.

complete_task

Create a folder in the user's REAL mailbox — a Gmail label, an Outlook folder, or an IMAP/iCloud folder — acting directly on the provider account. account=<address> picks the mailbox (required when several are connected); parent nests the new folder under an existing one. When the user asks for "a folder" this is the direct answer — do it, then the response's `hint` mentions the Mailopoly List alternative once. For a Mailopoly smart folder use create_email_list instead.

create_mailbox_folder

Create a task, reminder, or meeting in the user's task manager / My Day. A meeting is just a task with task_type='event' — set attendees (and optionally send_invitations=true) and a real calendar event is created and .ics invites are emailed to each attendee. - due_date: when the task is due, OR the start time for an event. Always pass one when the user's words imply any date ('Friday', 'before the 20th', 'next week'). If omitted, the task is filed for TODAY (all-day) — or on the reminder's day when reminder_date is set — so it appears in the user's day view and ages out normally. - reminder_date: when to remind the user about it. Both ISO (YYYY-MM-DD or YYYY-MM-DDTHH:MM), interpreted in the given timezone (defaults to the user's own). - priority: low | medium | high. - task_type: action | event | invoice | reply. - event_end: ISO end time, only meaningful for task_type='event'. - location: meeting location or URL (events). - attendees: list of {"email": "...", "name": "..." (optional), "role": "required"|"optional" (optional)} for an event. Pass real email addresses — NEVER invent one. - send_invitations: true to email .ics invites to the attendees now (this needs the 'send' permission on the connection, like send_email). - subtasks: checklist items to create ON this task, in order. A task with sub-tasks is ONE create_task call — parent in `title`, the items here. Never create one task per item, and never write the items into the title or description as a numbered list. - email_id: optionally link the task to an email.

create_task

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 — a Mailopoly folder that files itself — 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). This is the tool for "make me a folder for X": 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. One email can sit in several lists without copies, and a list spans every connected account. EXCEPTIONS BELONG IN THE DESCRIPTION: say "everything from X except Y" in the user's own words and the rules carry Y as an exclusion — do not drop the exception and do not describe it as a second thing to collect. Returns the created list with the generated rules (`match_rules.any` is what it catches, `match_rules.none` what it deliberately keeps out), the reasoning, and how many emails matched, so you can confirm it captured the intent (browse it with get_feed(list_id=...)) — read both blocks back to the user when there is an exception. name overrides the generated list name. exclude_from_cleanbox=true also hides matching emails from the main feed (only on explicit user request). `backfill_status` is "complete" when every matching email was filed before this answer, or "in_progress" when filing a large mailbox outran the call's time budget and is finishing in the background — `backfilled_email_count` is then the count so far and the list keeps filling on its own — quote `backfill_summary` and never call the list empty while it is filling. SCOPE: the rules are the minimal set for what the user described — a person AND a topic means emails matching both, and no whole-domain or whole-app (WhatsApp, Instagram…) rule is added unless the user asked for all of it; rules the generator proposed anyway come back in `removed_rules`. COUNTS: the result carries per_rule_counts (what each rule catches on its own), over_broad with over_broad_reasons, and for a list that hides from the Cleanbox would_leave_cleanbox_count — relay them. expected_count = how many emails the user pointed at, when known. An over-broad list that hides from the Cleanbox is NOT created: the result is needs_confirmation (nothing written) until the user confirms those numbers and you call again with confirm_over_broad=true. To change an existing list use update_email_list — never a second list. For a folder in the user's REAL mailbox use create_mailbox_folder instead.

create_email_list

Set up a monitor that fires whenever a matching email arrives in the user's mailbox — "alert me when…". name: a short label for this monitor (shown in list_email_triggers and in trigger_alert notices — pick something that identifies it at a glance). 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), has_task (fire only when Mailopoly's extraction turned the email into a TASK of that kind: 'reply' = the email needs a reply from the user; 'invoice' = it carries an invoice/bill with a real amount; 'event' = a calendar event was extracted; 'shipment' = a delivery/tracking update; 'action' = an open action item; 'any' = any of those). has_task counts as a structured condition, so "alert me when an email needs a reply" is just {has_task: 'reply', notify_on_fire: true} — no other condition needed. task_strict (reply only): true additionally requires that Mailopoly has PRE-WRITTEN reply drafts for the email — a stricter, higher-precision subset (the user demonstrably corresponds with the sender, or the reply-need judge was confident). Fired events from has_task triggers carry a `task` object with the extracted facts (invoice amount/currency/ due date, event time, shipment carrier+status, drafts_ready count), and notify_on_fire pushes lead with those facts (e.g. "Invoice $49.20, due 24 Aug") — so an "invoice from Amazon → tell me the amount" monitor is {sender: 'amazon', has_task: 'invoice', notify_on_fire: true}, and an "invoice → forward to accounts" workflow is the same trigger with a runbook + assigned_agent instead of notify_on_fire. Reply-task triggers evaluate only mail older than ~3 minutes (classification settling time). 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. email_type accepts 'received' (default), 'sent', or 'all' (no direction filter). source restricts to one channel: 'email' (real email), or a connected app — 'whatsapp', 'instagram', 'messenger' (Messenger DMs), 'facebook' (Facebook Page comments), 'slack', 'teams', 'tiktok'. source alone is a valid condition, so "every WhatsApp message" is just {source: 'whatsapp'}. TWO RULES that hold for EVERY connected app: (1) messages the user authored ingest as SENT mail, so any "messages from myself / my own messages" monitor MUST use email_type='all' — the default received-only filter silently drops them; (2) app subjects are synthetic and per-app (e.g. "Slack message from <name>", "Teams message from <name>", Slack self-notes "Slack note to self"), so prefer the generic recipe {source: '<app>', sender: <the person's name>, email_type as needed} over subject matching, and let the preview's sample_matches confirm. ALWAYS sanity-check the preview's sample_matches against the user's intent, not just the count — a plausible count of wrong-kind matches means the conditions need rebuilding. 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. notify_on_fire: set TRUE whenever the user asks to be ALERTED or NOTIFIED ("alert me when…", "notify me if…") — Mailopoly itself then pushes to their phone the moment the trigger fires (monitor name + sender + AI summary; links stripped; ~30/day/user cap), with no assistant needed in the loop. Leave false for monitors that feed an agent workflow via poll_pending_actions instead of interrupting the user. 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. rate_cap_per_day: max fired events queued for this trigger per day (default 20, capped at 50 server-side) — once hit, further matches that day stop queuing new events until the next day; raise it for a monitor expected to fire often. 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

Turn Mailopoly's daily briefing on/off, or subscribe the user to one of Mailopoly's scheduled REPORT EMAILS and set its schedule. Without `report`: the MASTER switch — enabled=false stops the in-chat daily briefing AND EVERY report email; enabled=true restores them. Bare call = "stop everything" only (a single nudge: dismiss_nudge). With `report`: ONE emailed report. START: enabled=true + report. STOP: enabled=false WITH that report — set_daily_briefing(report='digest', enabled=false) for "stop the digest" / "detén el resumen" / "pare o resumo". NEVER answer "stop <one report>" with the bare call: it silences every report the user has. Reports: 'my_day' (today's tasks, events and bills), 'priorities' (the short list of what needs the user), 'digest' (catch-up of what's come in, over the folder they pick), 'second_digest' (a second digest, own folder and hour — e.g. Cleanbox at 8, Other at 18). frequency: 'daily' (default) | 'weekdays' | 'weekly' (+ weekly_day 0=Monday..6=Sunday, default Monday). hour: 0-23 in the user's OWN local time (profile timezone; set_timezone first if unset). Pass `hour` ONLY when the user names a time — omitted, they keep their current hour (7 for the morning reports, 17 for a digest). my_day and priorities SHARE one morning hour, so `hour` on either MOVES the other one too; say so. Whole hours only — no minutes: round 7:30 to the nearest hour and tell the user. folder ('cleanbox' | 'other' | 'all'): digests only. Omitted settings keep their values, but `enabled` is written every time — pass enabled=true when you are only changing a schedule. Delivery: to the account's login address (or the Mailopoly inbox if no external mailbox) — there is no recipient parameter; if asked to email a report to an assistant or another address, say Mailopoly can only email the account holder. A report covers its FOLDER across ALL connected mailboxes — no per-account report (get_feed filters by account; a scheduled report cannot). Sent from the chosen hour onward — usually within minutes, up to 4 hours later — only on days with something to report, and only while the account has an active plan or trial, a connected mailbox, and has used Mailopoly in the last 21 days; the result lists whatever blocks delivery under not_sending_because. Enabling a report switches the master switch back on. Current settings: get_account_overview → report_emails. Nothing is sent by this call and there is no on-demand report email: for "send it now" show get_catch_up in the chat instead; re-calling with the same settings changes nothing.

set_daily_briefing

Search the FULL history of the user's connected app inboxes — Slack, Microsoft Teams, Facebook Messenger and Instagram DMs — live at each provider, reaching messages from long before the app was connected to Mailopoly. Use it when search_emails finds few or no app messages for something the user expects to exist: normal search only covers messages ingested since the app was connected (plus a small backfill). `sources` optionally restricts the search (any of 'slack', 'teams', 'messenger', 'instagram'); omit it to search all connected apps. start_date/end_date (YYYY-MM-DD) scope the window; omit both to search as far back as each provider allows. NOTES ON COVERAGE, per app (also reported per call in `connections_searched` / `unsupported`): Slack and Teams use their providers' real search; a Slack connection made before Mailopoly requested the search scope falls back to scanning direct/group messages and reports needs_reconnect — tell the user reconnecting Slack enables full-workspace search. Messenger/Instagram have NO search API, so their history is scanned newest-first under a server-side budget; when a scan is cut short the connection reports complete=false with oldest_scanned_date — page deeper by re-running with end_date set to that date. WhatsApp history is IMPOSSIBLE to search (the API keeps no history) and TikTok has no message search; both are listed in `unsupported` when connected — relay that honestly. Returned email_id values (the 'app:…' form) work directly in get_email; rows with already_in_mailopoly=true are regular local ids. Nothing this tool touches is imported or processed — results are read-only views of the provider's copy.

deep_search_app_messages

ESCALATION TOOL, not the first-choice search — search_emails answers from Mailopoly's index in about a second, while this tool crawls the user's mail providers LIVE and costs seconds to minutes of their time. account (optional): the address of ONE connected mailbox (as shown in list_email_accounts / get_account_overview) to crawl only that mailbox — "search my iCloud for X" — instead of every connected account; limit caps the results (max 100); timezone is an IANA name (e.g. Europe/Paris) for date filters, defaulting to the user's own. Call it only AFTER search_emails came up short, or when the question clearly reaches mail older than the indexed history (search_emails responses include indexed_history_start). It searches the user's COMPLETE email history — 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. TIME BUDGET: the live crawl is deliberately capped server-side — typically 5-45 seconds for Gmail/Outlook, whose provider APIs do the searching server-side, and up to ~90 seconds for IMAP accounts (iCloud, Yahoo, custom hosts), which offer no server-side full-text search and must be walked folder by folder — so this call ALWAYS returns a usable response before your own tool-call timeout. The slowness is never a reason to refuse an IMAP account's search: when provider history is genuinely needed, run it and 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. read_status filters by read state ACROSS THE FULL PROVIDER HISTORY — false = unread only (Gmail is:unread, Outlook isRead, IMAP UNSEEN), true = read only; omit for both. is:unread / is:read in the query work too. Result rows carry "read" where the provider reports it — combine with mark_email_read(email_ids=[...]) to sweep old unread mail in one call per 100 ids (its batch cap). 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) are both INCLUSIVE — the whole end day is searched, so start_date == end_date targets one specific day (and when paging, results from the cursor day may repeat — skip ids you have already seen). They 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 (to read SEVERAL results, pass the whole id list to get_emails in ONE call). 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. CAPACITY: one live crawl runs per account at a time and each account has an hourly live-search budget. When either is reached this call still answers — from Mailopoly's index only — and says so in coverage_note with retry_after_s: relay that to the user, wait that long before the next live search, and combine related terms into one query rather than running several.

deep_search_emails

Delete one of the user's email drafts (an id from list_drafts / save_draft). Confirm with the user first — a deleted draft is gone from every Mailopoly surface. A sent draft is retired automatically by send_email, so this is only for drafts the user no longer wants.

delete_draft

Delete a folder in the user's REAL mailbox. Semantics differ per provider and the result's message says what actually happened — relay it: Gmail label deletion only removes the label (the emails survive in All Mail); Outlook moves the folder AND its contents to Deleted Items (recoverable); IMAP/iCloud deletion is refused while the folder still holds messages (move them out first — mail is never destroyed). Special folders are refused. Confirm with the user before calling.

delete_mailbox_folder

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 Lists — a Mailopoly smart folder (soft delete; id from list_email_lists). The emails themselves are NOT deleted — they return to the normal inbox views. Call it ONLY when the user asked for this list to be deleted — never as a step of editing, widening, narrowing or rebuilding a list (use update_email_list with add_rule / remove_rule for that). To delete a folder in the user's REAL mailbox use delete_mailbox_folder instead.

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

Delete one or more emails — a RECOVERABLE delete: they move to Mailopoly's Deleted view (restorable there, or ask to undelete), and when Provider Sync is on for the account they are also moved to the mailbox's own Bin / Deleted Items / Trash. Never a permanent delete: the user empties that folder themselves (Gmail clears its Bin after 30 days) or uses Delete forever / Empty Trash in Mailopoly's Deleted view. Confirm with the user before calling. Up to 100 email ids per call (UUIDs or deep-search provider refs), one call per batch — never a loop of single calls. Every id is accounted for: count, already_deleted, not_deleted. The result's provider_effect says exactly whether the real mailbox was touched — relay it, and when Provider Sync is off say it can be turned on per account under Profile → Preferences → Provider Sync. To archive instead use hide_emails; for spam, hide_emails with reason='spam'.

delete_emails

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 — Mailopoly's archive (does not delete them). Pass as many email_ids as needed — the batch is processed completely (internally in groups of 100), never truncated. reason (optional): omit it for a plain hide/archive; 'spam' marks the emails as spam (Mailopoly's Spam folder, plus the mailbox's own Junk folder when Provider Sync is on for that account); 'never_show_this_sender' also blocks the sender — confirm with the user first, the result says what the block covers; 'not_this_type_sender' is the softer form (this kind of mail from this sender goes to Other, the sender itself is not blocked). To DELETE emails use delete_emails (reason='delete' here is kept as an alias and does the same recoverable delete). Any of these can be undone with restore_emails. The result's provider_effect says whether the user's real mailbox was touched — relay it; when Provider Sync is off, say it can be turned on per account under Profile → Preferences → Provider Sync.

hide_emails

Answer a HOW-DOES-MAILOPOLY-WORK question from the official product documentation — verified, never guessed. Call this whenever the user asks how to do something in Mailopoly or what a Mailopoly feature is or does: connecting WhatsApp / Slack / Instagram / Teams / TikTok, email signatures, Lists, My Day, Cleanbox, Provider Sync, deleting or restoring email, plans and what they include, the trial, Pro/Business, teams, the mobile apps, troubleshooting a connection — in any language. `platform` is where the user is working: 'web' (default, also Mac/Windows desktop), 'ios' or 'android'. Do NOT answer these from your own knowledge of email apps: Mailopoly's UI and rules are specific, and a plausible-sounding guess sends the user hunting for a control that does not exist. Relay `answer` as-is; if `status` is 'declined', say the documentation doesn't cover it and offer the support route in `support`. Works before the user has a trial.

get_product_help

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. A bare provider NAME is resolved to that provider where we hold one; when we do not, the result is recommended_method='needs_address' and you must ASK for the address rather than describing a provider. This returns GUIDANCE only; it never fetches or receives a password.

get_connect_instructions

The message templates on the user's WhatsApp Business Account, with each template's status, language, body text and required parameter counts. Only APPROVED templates can be sent (send_whatsapp_template); templates are created and approved in Meta's WhatsApp Manager, not here. account picks the WhatsApp number when several are connected (a phone number or its display name).

list_whatsapp_templates

List the user's calendar events extracted from their email (meetings, bookings, appointments). start_date/end_date are YYYY-MM-DD (defaults to upcoming events); search matches words in the event title/location; limit caps the count (default 50); timezone is an IANA name (e.g. Europe/Paris) used to interpret the dates, defaulting to the user's own.

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'. Each mailbox may carry `capabilities` — what its stored permission grant lets Mailopoly do (can_read / can_send / can_organize, where organize = folders, moving emails, syncing clean-ups back). When a folder or send tool reports the connection lacks permission, check here and relay the capabilities `summary` verbatim — it explains the fix (reconnect and approve all permissions) in user-friendly words.

list_email_accounts

List the user's email drafts (created in Mailopoly), newest first. search matches words in the subject/recipient; limit caps the count (default 20, max 50). Each draft's draft_id works with get_draft, save_draft, send_email and delete_draft.

list_drafts

The user's custom email lists — their Mailopoly 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. These are Mailopoly-side folders; for the folders in the user's REAL mailbox (Gmail labels, Outlook/IMAP folders) use list_mailbox_folders.

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 or search the user's PolyBox — Mailopoly's file storage. Holds every email attachment automatically (received and sent) plus saved items: uploads, text clips, links, and documents shared with the user. Returns items (first matches carry download links), folders with counts, and storage used vs quota. `search` matches filename, extracted file text, subject, sender and clip text (literal token-AND). views: all | inbox (received attachments) | sent | cleanbox (personal-mail attachments) | manual (saved/uploaded only) | shared (shared WITH the user). scope='team' lists the team PolyBox (Business plans). folder_id (from this tool's own `folders` list) narrows the listing to one folder. limit caps how many items come back (default 15, max 50); offset pages through the rest when `truncated` is true. show_hidden=true also returns items the user has hidden (box_manage action='hide_item'). items_only=true skips the folders/storage summary in the response when only the item list is needed. timezone: IANA name, e.g. Europe/Paris — accepted for future localized timestamps but not currently applied to this tool's output. TO SEND A FILE: find it here, then pass its item_id in send_email(attachments=[...]) or save_draft(attachments=[...]) — "send the QA report I uploaded to PolyBox to Bill", "attach the invoice from Acme". A file from THIS chat (dropped in by the user, or one you generated) is not here yet — put it in with box_upload(files=[…]) and use the item_id it returns; do not send the user to mailopoly.com.

box_list

The folders in the user's REAL mailbox, per connected account: Gmail labels, Outlook folders (with message counts), IMAP/iCloud folders. Omit account for every connected mailbox; pass account=<address> (as shown in list_email_accounts) for one. Each entry carries account_id — the unique handle to pass as `account` to the other folder tools when the same address is connected through two providers. Each folder says whether it is a user folder or a system one (INBOX, Sent, Trash, … — those can't be renamed/deleted). These are the provider's own folders — for the user's Mailopoly Lists (smart folders) use list_email_lists instead.

list_mailbox_folders

Emails the user has scheduled to send later (from any surface — the app, Poly or a connector) that have not gone out yet, soonest first. Each item has scheduled_send_id, send_at (UTC — convert to the user's timezone when you tell them), subject, recipients, from_address and any attachment names. Use the id with cancel_scheduled_email or reschedule_email. An empty list means nothing is waiting.

list_scheduled_emails

Every address that emails this user, and what Mailopoly does with mail from it — the data behind the web app's Senders screen. Use it for "who emails me most", "who have I unsubscribed from", "what happens to mail from X", or before changing a sender's settings, so you name the exact address. Each row carries the sender's address, the name shown for them, whether they are a person or a company, how much they send (30 days and all time), when they last wrote, their unsubscribe state, the lists they belong to, whether they are protected from bulk clean-ups, and their PLACEMENT: 'auto' (Mailopoly decides per email — the default), 'cleanbox' (always the personal folder), 'other' (always the promotional folder), or 'hidden' (never shown at all). Change any of that with set_sender_settings. `query` matches the sender's name or address. `lens` narrows the list to one group — 'all' (the default), 'cleanbox', 'other', 'hidden', 'unsubscribed', 'protected', 'rules' (senders with a rule) or 'lists' (senders in one of the user's lists). `kind` is 'person' or 'company'. `sort` is 'recent' (most recent mail first — the default), 'volume' (most mail first) or 'name'. `limit` caps at 100.

list_senders

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. status filters by task status (e.g. 'pending', 'completed', 'snoozed'); search matches words in the task title/description; include_completed adds done tasks to the list; limit caps the count (default 100); timezone is an IANA name (e.g. Europe/Paris) for 'today'-style timeframes, defaulting to the user's own.

list_tasks

Manage PolyBox: action = edit_item (text/link clips) | delete_item (saved documents only; email-attachment items can only be hidden) | hide_item | unhide_item | duplicate_item (to_scope='team'/'personal' copies between scopes) | create_folder | rename_folder | move_folder | delete_folder (items survive) | add_to_folder | remove_from_folder. item_type is the item's type from box_list ('file' = saved/uploaded, 'external'/'direct' = email attachments). Deleting is destructive — only on the user's explicit instruction. item_id: the item to act on (from box_list) — required for edit_item / delete_item / hide_item / unhide_item / duplicate_item / add_to_folder / remove_from_folder. folder_id: the folder to act on (from box_list's `folders` list) — required for rename_folder / move_folder / delete_folder, and the destination folder for add_to_folder / remove_from_folder. name: the new name — required for create_folder and rename_folder. text/url: the new clip content for edit_item, on a text or link item respectively. parent_id: nests the new folder under an existing one for create_folder, or is the new parent for move_folder (omit to move a folder to the top level). scope: 'personal' (default) or 'team' (Business plans) — which PolyBox create_folder creates the folder in.

box_manage

Mark email as read (or unread with read=false). For ONE email pass email_id; for SEVERAL pass email_ids (up to 100 per call — split a larger batch into several calls) and the whole batch is marked in ONE call — NEVER loop this tool over a list ("mark all of these as read" is a single email_ids call). Read state syncs back to the provider (Gmail/Outlook/IMAP) either way.

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, 'all' to broadcast to every other agent, or 'user' to message your principal (the human) directly — it lands as an unread chat message in their Mailopoly Agent Console AND notifies their phone (server-labeled with your name, links stripped, daily caps; past the cap the message still lands, just silently — no separate ping_user needed). needs_reply (to='user' only): set true when you are asking the user for an answer or a decision — it files the message into their reply queue (My Day) until they respond; leave false for status reports and FYIs so their queue stays honest. FORMAT for to='user': the body renders as Markdown in the user's chat (web, phone, Agent Console) — write it like a good assistant reply, not a log line. Lead with the outcome or the decision you need in one line; then short paragraphs separated by blank lines; '- ' bullets for items, fixes and numbers; a markdown table for anything tabular (accounts x status, before/after); **bold** the ask ("**Reply purge or leave**"). Never send one unbroken block — a paragraph over ~3 sentences is unreadable on a phone. Deep detail belongs in a handoff doc you name, not in the message. Bodies to other agents are read by a program, not a person: structure those however the recipient parses best. Delivery to agents 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'). ping_user=true (agent recipients only): also deliver a copy of the message to the user — it lands in their console and inbox and notifies their phone, exactly like to='user'; never a bare notification. 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: check poll_pending_actions again on your next turn until it arrives — see that tool's guidance on being woken sooner if your platform allows it. Addressing YOURSELF (to=<your own registered name>) delivers nothing: it stores the body as a shared NOTE under topic 'note:<key>' (latest wins) — the same thing set_note does.

send_agent_message

Move emails into a folder in the user's REAL mailbox, acting directly on the provider account ("move these newsletters into my Reading folder"). Accepts up to 100 email ids per call (UUIDs or deep-search provider refs) — one call per batch, NEVER a loop of single calls. folder is matched by name per account. create_if_missing defaults to TRUE: when no folder with that name exists yet, one is CREATED for real in the user's mailbox (a new Gmail label / Outlook folder / IMAP folder) before the emails are moved into it — pass create_if_missing=false if the caller wants the move to fail instead when the named folder doesn't already exist. Gmail semantics: a move = add that label + remove from the Gmail inbox (the email also stays in All Mail) — the per-email detail says so; relay it when asked. Trash/Junk/Drafts/Sent are refused as destinations — deleting is a different action: use delete_emails (or hide_emails with reason='delete' on a tool list without delete_emails) instead. The result reports EVERY id as moved or not_moved (with reasons): relay partial outcomes honestly. TIME BUDGET: the call is capped server-side, so a slow mailbox returns a partial result naming exactly what moved and what did not, rather than hanging — retry the remainder in a smaller batch when that happens. The email stays visible in Mailopoly — a provider move organises the mailbox, it never hides anything here. For filing into a Mailopoly List use add_email_to_list instead.

move_emails_to_folder

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