# Overview

> Virtual Mail - API Documentation — programmatic access to your virtual mail via the MCP server and the Public API.

Web page: https://reference.earthclassmail.com/

Virtual Mail gives you programmatic access to
your virtual mail — inboxes, mail items, scans, shipments, check deposits, and
more. Two interfaces are available depending on how you want to integrate.

> **About the name**
>
> **Virtual Mail** is the current name for the service formerly known as
> **Earth Class Mail** (ECM). If you see "Earth Class Mail" or "ECM" in URLs,
> email addresses, or API field names (e.g. `ecm_number`), they refer to the same
> product. The `ecm_number` field is the same as the PMB (Private Mail Box)
> number.

## MCP server — for AI assistants

The **MCP server** (Model Context Protocol) lets AI assistants like Claude,
ChatGPT, and Cursor connect directly to your virtual mailbox. Your assistant can
find, read, organize, scan, and shred mail on your behalf, and track shipments
and check deposits — all within your own account and permissions.

- **Protocol**: MCP over stateless streamable HTTP — a single endpoint, no
  WebSocket upgrade, no session state.
- **Auth**: OAuth (recommended) or a personal API key.
- **Capabilities**: read inboxes, account overview, mail items, folders,
  recipients, and tags. Act on mail: mark read or unread, move, archive, or
  trash, tag, transfer to another recipient, and request or cancel scans and
  shredding. Create and delete tags. Shipment and check deposit status is
  read-only — the MCP server cannot ship mail or deposit checks.

➜ [Public MCP Documentation](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md) — authentication, capabilities, and how to connect.
➜ [Tools Reference](https://reference.earthclassmail.com/_llms_txt/v2/mcp/tools.md) — every tool exposed to agents.

## Public API — for application integrations

The **Public API** provides direct HTTP access to virtual-mail resources for
custom application integrations, automation scripts, and third-party platforms.

- **Protocol**: REST over HTTPS — standard JSON request/response.
- **Auth**: Static API key (generated in Settings → Integrations).
- **Capabilities**: read inboxes, mail items, scans, media, check deposits,
  shipping addresses, shipments, users, accounts, and recipients. Act on mail:
  archive and unarchive, request or cancel shredding, email a scan, get
  shipping rates, create shipments, and request or cancel check deposits.
  Create, update, and delete tags, and add or remove them on mail items.

➜ [Public API Documentation](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md) — authentication, rate limits, paging, and
key concepts.
➜ [Quickstart](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/quickstart.md) — your first request, with ready-to-run example scripts.
➜ [Playbooks](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/playbooks.md) — step-by-step workflows for common
tasks.
➜ [API Spec](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec.md) — full OpenAPI 3.1 endpoint reference.

## Which one should I use?

| | MCP server | Public API |
|---|---|---|
| **Best for** | AI assistants and agentic flows | Custom apps, scripts, and system integrations |
| **Protocol** | MCP (streamable HTTP) | REST (HTTPS + JSON) |
| **Auth** | OAuth or API key | Static API key |
| **Interface** | Tools with structured input/output | HTTP endpoints |
| **Spec** | [Tools Reference](https://reference.earthclassmail.com/_llms_txt/v2/mcp/tools.md) | [OpenAPI 3.1 Spec](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec.md) |

Both interfaces access the same underlying data and enforce the same
per-user authorization. Choose MCP if you're connecting an AI assistant;
choose the Public API if you're building a traditional integration.