Public MCP Documentation

Connect your AI assistant to Virtual Mail and manage your virtual mailbox just by asking — find mail, organize your inbox, scan or shred items, and more — directly from Claude, Cursor, and other MCP-compatible apps.

If any difficulties arise, please email api@earthclassmail.com with your questions.

What it does

Virtual Mail’s MCP server connects your AI assistant directly to your virtual mailbox, so it can find, read, and act on your mail on your behalf — all within your own Virtual Mail account and permissions. Instead of logging in and clicking through the app, you just ask.

For example, you can ask your assistant to “find the letter from the IRS and tell me what it says,” and it will locate the item, pull its scanned text, and summarize it for you. You can also have it take real actions on your behalf: scan or shred a piece of mail, apply tags or move it to a different folder. And it can simply tell you what needs your attention this week, without changing anything.

What you can do

Find and read your mail — ask what arrived this week, search for a specific sender, or have the assistant read and summarize a scanned letter for you.

Check your inbox at a glance — get a quick overview of how many items are waiting, what’s unread, whether anything needs attention, and how your account is doing.

Organize your mailbox — mark items as read, move mail to folders or the archive, apply tags, or reassign a piece to a different recipient on a shared inbox.

Scan and shred — request that physical mail be opened and scanned so you can read it digitally, then optionally shred the original. Cancel a pending scan if you change your mind, or a pending shred within the 7-day grace period.

Track shipments and deposits — check whether a forwarded package has shipped, see its tracking info, or find out the status of a check deposit.

Look up references — ask what a status code or flag means (e.g. what “SCAN_THRESHOLD_EXCEEDED” means) without leaving your conversation.

Authentication

You can connect in one of two ways: sign in with OAuth (recommended, if your client supports it), or use an API key you generate yourself. Both reach every mailbox your user account is authorized for; they add no new access.

OAuth Dynamic Client Registration

If your AI client supports OAuth, you can connect by signing in to LegalZoom in your browser instead of managing an API key. The client obtains a short-lived access token and refreshes it for you, so there’s no long-lived key to store or leak. This is the more secure option; use it whenever your client supports OAuth. If it doesn’t, use an API key below.

You don’t register an application or manage a client ID or secret. The server publishes its OAuth configuration, and a compliant client discovers it and registers itself automatically (Dynamic Client Registration). You only add the server URL, without an API key, and approve the sign-in prompt.

How to connect:

1. Add the server to your client (see Other MCP clients), using the OAuth option and leaving out the API key.
2. The first time you use it, your client opens a LegalZoom sign-in page in your browser.
3. Sign in and approve the access your client is requesting.
4. That’s it. Your client is connected and refreshes your session on its own.

Token expiration: you’ll need to sign in again at least every 30 days, even if you use the MCP server daily, and whenever you revoke access or reset your client. API keys don’t expire this way.

API key

The MCP server can use an API key that you generate yourself. You only need one key: the same key works for the MCP server and the Public API.

Your API key is tied to your user account, so it can reach every mailbox you have access to. Keep it private, treat it like a password, and don’t commit it to source control. Regenerating the key invalidates the existing one.

Generate your API key in the Virtual Mail web application:

1. Sign in and go to Settings → Integrations.
2. Find the Custom API integration section.
3. In the API Key card, click Generate Key (invalidates any previously generated key).
4. Your key appears — click Copy.

You can also generate your API key in the Virtual Mail mobile app.

Capabilities and limitations

What the assistant can access

Scoped to your Virtual Mail account, the assistant can access and use available account information and tools to help manage mail, inbox, shipment, deposit, and related account activity. It can only reach mailboxes and data your own user account is authorized to access. The MCP server reuses Virtual Mail’s existing authorization, adding no new access.

Read and write tools

The toolset includes both read-only tools and write tools that take real action: marking mail read/unread, moving/archiving/trashing, tagging, transferring recipients, requesting scans, shredding (irreversible once carried out; a pending shred can be cancelled within the 7-day grace period). Every tool the server exposes carries a standard MCP annotation (readOnlyHint / destructiveHint) that your AI client reads to tell read-only tools apart from ones that change your mailbox.

Caution

The server does not add its own confirmation step; it executes any authorized request your AI client sends. Reviewing and approving an action (especially shred) is the responsibility of your MCP client/agent. Use a client that prompts before write actions, and review before approving.

What the assistant cannot do

• No shipping or deposits — it can track existing shipments and check deposits, but it cannot ship mail, get shipping rates, or request a check deposit. To ship mail or deposit checks programmatically, use the Public API, or use the Virtual Mail app.
• No entity management — it cannot create, modify, or delete shipping addresses, bank accounts, recipients, or folders. It can only reference ones that already exist (e.g. move mail to an existing folder, transfer it to an existing recipient).
• No billing or payment changes — it cannot edit payment methods or plans. (Account standing and usage counts are read-only, and usage summaries are limited to account admins.)
• No access beyond your permissions — it cannot reach mailboxes, accounts, or actions your user isn’t authorized for in Virtual Mail.

Authentication & key scope

If you connect with an API key, access uses a single personal key tied to your user account, so it can reach every mailbox you have access to. Treat it like a password. To revoke a key, regenerate it at any time from Settings → Integrations, which invalidates the old key. (This does not apply to OAuth connections, which use a browser sign-in instead of a key.)

Usage limits

Requests are rate-limited per client IP — 300 requests/minute (subject to change). Exceeding the limit results in throttled requests.