List all configured email accounts. Call this first to discover available account names for use with other tools.

List all mailbox folders for an account with unread counts and special-use flags. Use list_accounts first to get the account name.

List emails in a mailbox with optional filters. Returns paginated results with metadata (read/unread 🔵, flagged ⭐, replied ↩️, attachments 📎, labels 🏷️). List or machine-generated mail is marked 📰 newsletter / 🤖 automated from its RFC headers, with the unsubscribe URI when the sender offers one — personal mail carries no marker. Use get_email to fetch full body content. ProtonMail note: labels are represented as IMAP folders — use list_labels to discover them, then list_emails with mailbox="Labels/X" to find labeled emails.

Get the full content of a specific email by ID. Does NOT mark the email as seen (uses IMAP BODY.PEEK — non-destructive). format: text (default) = HTML converted to readable text with markdown; stripped = text minus quoted replies and signatures; full = raw body part (HTML mail returns raw HTML). Body is capped at 10000 chars by default — pass maxLength (0 = unlimited) to change. Set markRead=true only when you want to explicitly mark the email as read. A Bulk: line appears for list or machine-generated mail (📰 newsletter / 🤖 automated), derived from RFC headers, with the unsubscribe URI when the sender offers one.

Fetch the full content of multiple emails in a single call (max 20). More efficient than calling get_email repeatedly when triaging or summarising several emails. Does NOT mark emails as seen. Defaults to format="text" (HTML stripped) for compact, AI-friendly output. Each message carries the same 📰 newsletter / 🤖 automated marker as get_email.

Get the current read/flag/label state of an email without fetching its body. Much cheaper than get_email when you only need to check whether an email is unread, flagged, or which labels it has. Also useful to confirm the result of a mark_email call. Does NOT mark the email as seen.

Search emails by keyword across subject, sender, and body — and, where the local mirror is enabled, attachment filenames (searching "report" finds an email carrying Q3-report.pdf). Omit query (or pass an empty string) to use it as a pure filter — e.g. find all emails from a specific sender without a keyword. Supports additional filters for sender, recipient, date range (since/before — INTERNALDATE; sent_since/sent_before — Date: header), attachments, size, and reply status. At least one of query/from/to/since/before/sent_since/sent_before/has_attachment/larger_than/smaller_than/answered must be set; otherwise the call errors (use list_emails to browse without filters). Results carry the same 📰 newsletter / 🤖 automated markers as list_emails.

Download an email attachment by filename or part id. First use get_email to see available attachments with their filenames and partIds (partId is unambiguous — use it for duplicate filenames and inline cid images). Returns base64-encoded content for files ≤5MB. saveToDownloadDir is unavailable — no attachment download directory is configured on this server.

Extract unique contacts from recent email headers. Returns contacts sorted by frequency (most frequent first). Useful for finding frequent correspondents or building an address book.

Reconstruct a full email conversation thread by following References and In-Reply-To headers. Returns all related messages. Does NOT mark emails as seen. format: text (default) = HTML converted to readable text with markdown; stripped = text minus quoted replies; full = raw body part. Each body is capped at 5000 chars by default — pass maxLength (0 = unlimited) to change. Use newestFirst=true to show the most recent message in full and older messages as header-only summaries. Use get_email first to obtain the message_id. Each message carries a Bulk line when it is list or machine-generated mail.

List all available email templates. Templates are TOML files in ~/.config/email-mcp/templates/ with {{variable}} placeholders for subject and body.

Extract calendar events (ICS/iCalendar) from an email. Returns structured event data including time, location, attendees, and status.

Add an email event to the local calendar (macOS Calendar.app / Linux via xdg-open). Automatically extracts event data from the email: ICS attachments, meeting URL (Zoom/Teams/Meet), conference dial-in / ID / passcode, attendees, and email body excerpt. All relevant email attachments (PDFs, docs, etc.) are saved locally and linked in the event notes. A native confirmation dialog is shown on macOS before the event is written. Returns one of: added | cancelled | timed_out | no_display.

Check whether the local calendar is accessible. On macOS, verifies Calendar.app access (requires Privacy & Security → Calendars permission). Returns granted status and step-by-step setup instructions if access is denied.

List all available local calendars (macOS Calendar.app / Linux default). Use the returned calendar names with add_to_calendar to target a specific calendar.

List local calendar events with optional filters. Search by title, date range, or calendar name. Use to check for existing events before creating new ones, or to verify a recently added event. Returns event id, title, start/end time, location, and calendar name.

List reminders from macOS Reminders.app with optional filters. Search by title or list name. By default only shows incomplete reminders. Use to check for existing reminders before creating new ones, or to verify a recently added reminder. Returns reminder id, title, due date, completion status, priority, and list name.

Create a reminder in macOS Reminders.app from an email. Shows a native confirmation dialog before adding. The reminder notes include a message: deep link that reopens the source email in Mail.app. Use for action items, deadlines, and follow-up tasks extracted from emails. Use analyze_email_for_scheduling first to let the AI decide if a reminder is appropriate.

Analyze an email to detect calendar events and/or reminder-worthy content. Returns structured analysis so the AI can decide whether to call add_to_calendar, create_reminder, both, or neither. Use this as the first step before creating any scheduling resource.

Get email statistics and analytics for a mailbox. Shows volume, top senders, daily trends, and read/flagged counts.

Check connection health, quota, and capabilities for email accounts, plus local cache size, coverage and hit ratio. Useful for diagnosing issues.

Find a real mailbox folder an email belongs to. Required before move_email or delete_email when the email was found in a virtual folder (e.g., "All Mail", "Starred"). Returns the first real folder path found, to use as sourceMailbox; on a label-based server a message may also sit in other folders.

Get the status of IMAP IDLE watcher connections and recent activity.

List all available AI triage presets with their descriptions and suggested labels.

Get the current AI hooks configuration including preset, rules, and custom instructions.

Diagnose desktop notification support on this platform. Checks if required OS tools are available and provides setup instructions to enable notification permissions (macOS, Linux, Windows).

Send a test desktop notification to verify that OS permissions are correctly configured. Use check_notification_setup first to diagnose any issues.

Update alert/notification settings at runtime. Changes take effect immediately. Use save=true to persist changes to the config file. Omit any field to leave it unchanged.

Find the newest verification code (OTP/2FA) or sign-in magic link in recent mail, using false-positive-resistant scoring (EN/DE). Use wait_seconds (max 45) to wait for a mail still in flight; if nothing arrives, simply call again. Works without the watcher via polling — with [settings.watcher] enabled, hits land within ~1 second. Set copy_to_clipboard=true to also place the value on the clipboard (concealed from clipboard managers, auto-cleared). The code/link is returned in the result by design.

Diagnose the clipboard integration used for caught verification codes: platform tools, concealed-write support, current [settings.verification] values, and the watcher prerequisite. With test_write=true it performs a harmless clipboard round-trip (writes a test string, reads it back, clears it).

Update [settings.verification] at runtime — changes take effect immediately, including starting/stopping the ambient catcher via enabled. Use save=true to persist to config.toml (previous file is backed up). Omit every field to see the current configuration. Registered in read-only mode too: this writes config, never the mailbox.

Send a new email. Supports plain text or HTML body, CC, and BCC.

Reply to an email with proper threading (In-Reply-To & References headers). Use get_email first to read the original. The original message is quoted below the reply by default (Thunderbird/Outlook style) — set quoteOriginal=false for the bare body only.

Forward an email to new recipients with optional additional message. The original is converted to readable text and "> "-quoted below your note; its attachments are re-attached unless includeAttachments is false. Set html=true to also send an HTML part carrying the original HTML in a blockquote.

Move an email to a different mailbox folder. The sourceMailbox must be a real folder, not a virtual one like "All Mail". Use find_email_folder first if the email was discovered in a virtual folder.

Delete an email. By default moves to Trash. Set permanent=true for permanent deletion (⚠️ irreversible). The mailbox must be a real folder. Use find_email_folder first if the email was found in a virtual folder.

Change email flags — mark as read/unread, flag/unflag. Idempotent: marking an already-read email as read is a no-op.

List available labels for an email account. Auto-detects the label system: ProtonMail folder-labels, Gmail X-GM-LABELS, or IMAP keywords. ProtonMail note: labels are represented as IMAP folders under the Labels/ prefix. Use list_emails with mailbox="Labels/" to find emails tagged with a ProtonMail label.

Add a label to an email. For ProtonMail, this copies the email into the corresponding Labels/ folder. For Gmail and standard IMAP, this sets a keyword flag on the message.

Remove a label from an email. For ProtonMail, this removes the email from the label folder. For Gmail and standard IMAP, this removes a keyword flag.

Create a new label. For ProtonMail, creates a folder under Labels/. For standard IMAP keywords, labels are auto-created on first use — this is a no-op.

Delete a label. For ProtonMail, deletes the label folder. For standard IMAP keywords, labels cannot be deleted server-wide — use remove_label on individual emails.

Batch operation on multiple emails by UID list. Supports mark_read, mark_unread, flag, unflag, move, and delete. Max 100 IDs per call. Returns success/failure counts.

Save an email draft to the Drafts folder. Compose over time, then use send_draft to send it. Use list_emails with the Drafts mailbox to see saved drafts.

Send an existing draft email and remove it from Drafts. The draft is fetched, sent via SMTP, then deleted. Use list_emails with the Drafts mailbox to find draft IDs.

Create a new mailbox (folder). Use '/' as separator for nested folders (e.g., 'Work/Projects'). Use list_mailboxes to see existing folders.

Rename an existing mailbox (folder). Use list_mailboxes to see current folder paths.

⚠️ DESTRUCTIVE: Permanently delete a mailbox and ALL its contents. This cannot be undone. Use list_mailboxes to verify the folder path.

Apply an email template with variable substitution. Use action "preview" to see the result, "draft" to save as draft, or "send" to send immediately.

Schedule an email to be sent at a specific time in the future. The email is queued locally and sent automatically when the time arrives.

List scheduled emails. Shows pending, sent, or all scheduled emails.

Cancel a scheduled email. Removes it from the queue and deletes the associated draft.