Building an AI Email Assistant: Developer Guide

If you want to build an AI email assistant that operates on real inboxes — not mocked data — the fastest architecture today is connecting Claude to a hosted MCP server that handles email provider auth, tool routing, and permission gating on your behalf. Connect My Email is that connector. This guide covers how the MCP tool layer works, the tools available, how to handle pagination safely, and where the safety boundaries are that your assistant needs to respect.

#What You're Actually Building

An AI email assistant built on CME isn't a local daemon or a custom IMAP client. The architecture is:

1. User authenticates their inbox with CME via OAuth or app-specific password
2. CME issues an MCP connector URL
3. That URL is added to Claude's connector settings
4. Claude calls CME's MCP tools at inference time — server-side, authenticated, scoped to the permissions the user granted

You write prompts and agent logic. CME handles provider authentication, token refresh, and the translation between the MCP tool interface and provider-specific email APIs. You never see raw credentials.

#The MCP Tool Set

CME exposes a structured set of tools that the AI model calls by name during a conversation or agentic run:

• list_mailboxes — enumerate the connected inboxes and their metadata
• read_email — fetch a specific message by ID, including headers and body
• search_emails — query the inbox with filters (sender, subject, date range, labels, read status)
• get_sender_stats — aggregate volume and engagement data by sender
• sweep_inbox — identify messages matching a pattern (used for bulk-action planning)
• simulate_cleanup — run a cleanup plan and return what would be affected, without executing
• Write tools (Pro/Power only): draft_reply, send_email, move_messages, archive_messages, delete_messages, flag_messages

Each tool takes structured parameters and returns structured results. The model decides which tool to call, passes the right arguments, and receives a typed response. This is the MCP tool-call pattern — the AI is the orchestrator, not a hardcoded pipeline.

#Auth Happens Server-Side

This is worth being explicit about because it affects how you think about the system. OAuth tokens, app passwords, and provider refresh flows are all managed by CME's backend. The AI model never receives credentials. When Claude calls search_emails, CME validates the request, calls the provider API using the stored token, and returns results to the model. Your assistant logic never touches raw auth material.

For your purposes as a developer, this means:

• You don't build OAuth flows
• You don't handle token expiry
• You don't write provider-specific API adapters
• You do need to make sure users complete the CME OAuth setup before your agent runs

#Pagination and Context Budget

This is the detail most developers miss, and it's what separates a usable assistant from one that degrades on large inboxes.

Email inboxes at scale can contain tens of thousands of messages. A naive implementation that asks Claude to "read everything" and dumps raw email content into context will hit token limits fast, produce low-quality summaries, and be expensive to run.

The right approach:

Search before read. Use search_emails with specific filters to get a targeted list of message IDs before fetching content. Don't load email bodies unless you have a specific reason.

Summary-first, content on demand. Start with get_sender_stats or a targeted search_emails call that returns headers (sender, subject, date, snippet). Only call read_email for individual messages when the user or agent logic specifically needs the body.

Paginate large result sets. search_emails returns paginated results. If your query would match thousands of messages, handle the pagination in your agent loop rather than trying to load all results at once. For most user-facing tasks, 20–50 results per page is a good default.

Summarize iteratively. For high-volume inboxes, a good pattern is: fetch one page of results, summarize, ask the model if more pages are needed to answer the question. This keeps context usage bounded.

#Write Action Safety Boundaries

CME's write tools are designed with a review-forward pattern. For any destructive or outbound action — sending email, deleting messages, bulk-archiving — the intended flow is:

1. Model calls simulate_cleanup or constructs a write plan
2. Plan is surfaced to the user for review
3. User explicitly confirms
4. Write tool is called with the confirmed parameters

Your agent logic should not skip this step. If you're building an automated workflow that runs without a human in the loop, restrict it to read-only tools. Write actions on email carry real consequences — sent messages can't be unsent, and while CME defaults to archive rather than permanent delete, you should design your assistant around the principle that confirmation is required before irreversible actions.

The Free tier enforces this naturally — write tools aren't available, so agents on Free are read-only by construction. Pro and Power unlock write tools, but the pattern of simulate-then-confirm is still the right design.

#Example Prompt Patterns for Agent Development

Inbox triage agent:

Use get_sender_stats to identify the top 10 senders by volume in the last 30 days. For each sender with zero replies in that period, add them to a candidate list. Return the list with message counts.

Follow-up detection:

Search for emails sent by the user (outbound) in the last 14 days with no reply thread. Return sender, subject, and date sent. Paginate if the result count exceeds 25.

Cleanup planning:

Use sweep_inbox to identify emails older than 60 days from senders on the candidate list. Then call simulate_cleanup with that set. Present the count and a 5-message sample before asking for confirmation.

Onboarding check:

Call list_mailboxes first to confirm the user has at least one inbox connected before proceeding with any other tool call.

#FAQ

#Does CME work with providers other than Gmail?

Yes. CME supports Gmail, Outlook, iCloud, Yahoo, Fastmail, ProtonMail, Zoho, AOL, and IMAP-style accounts. Auth method varies by provider — OAuth is preferred, app-specific passwords are the fallback for providers that don't support OAuth for third-party apps.

#Can I build a multi-inbox agent?

Yes, on Pro (3 inboxes) or Power (10 inboxes). list_mailboxes returns all connected inboxes, and most tools accept a mailbox parameter to scope operations to a specific account.

#How should I handle the case where a user hasn't connected their inbox yet?

list_mailboxes will return an empty list or an error if no inbox is connected. Check for this early in your agent flow and route the user to CME's setup before continuing.

#Are there rate limits on tool calls?

Yes — CME applies rate limits to protect both users and email providers. For most interactive assistant use cases, you won't hit them. Automated batch workflows that make hundreds of calls in a short window may encounter limits. Design your agent to paginate and pause between bulk operations.

#Can I use CME in an automated pipeline without user interaction?

Read-only operations can run in automated contexts. Write actions should always route through a review step before execution — this is both a design principle and a practical safeguard for your users.

See the full tools reference for current tool names and parameters, review pricing to understand which tools are available at each tier, or try the free email cleaner to test what the connector surface feels like before building on it.