# 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. # Public MCP Documentation > Connect your AI assistant to Virtual Mail via MCP — authentication, capabilities, and limitations. Web page: https://reference.earthclassmail.com/v2/mcp/ 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](mailto: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](https://reference.earthclassmail.com/_llms_txt/v2/mcp/connect.md)), 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](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md), 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. # ChatGPT > Install the Virtual Mail app in ChatGPT from the ChatGPT app directory. Web page: https://reference.earthclassmail.com/v2/mcp/chatgpt/ Virtual Mail is available as an app in **ChatGPT**. Install it from the ChatGPT app directory to manage your virtual mailbox directly in a conversation. You don't need to configure a server URL or generate an API key. [Open Virtual Mail in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a706dc692d08191a3a1aa5e52a34c12) ## Install the app 1. Open the [Virtual Mail app listing](https://chatgpt.com/plugins/plugin_asdk_app_6a706dc692d08191a3a1aa5e52a34c12) in ChatGPT, or search for **Virtual Mail** in the ChatGPT app directory. 2. Click **Connect**. 3. Sign in to LegalZoom when prompted and approve the access ChatGPT requests. 4. Start a new conversation and ask about your mail, for example: _"What arrived in my mailbox this week?"_ The app uses the same OAuth sign-in described in [Authentication](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#authentication). It can only reach the mailboxes your LegalZoom account already has access to. > **Staying connected** > > ChatGPT asks you to sign in to LegalZoom again at least every 30 days, even if > you use Virtual Mail daily. See > [token expiration](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#oauth-dynamic-client-registration). ## What you can do The ChatGPT app gives you the same capabilities as any other MCP client. You can find and read mail, organize your inbox, request scans and shreds, and track shipments and deposits. See [What you can do](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#what-you-can-do) and the [Tools Reference](https://reference.earthclassmail.com/_llms_txt/v2/mcp/tools.md) for details. > **Caution** > > Some actions, such as shredding, can't be undone once carried out. A pending > shred can be cancelled within the 7-day grace period. Review what ChatGPT is about > to do before you approve an action that changes your mailbox. ## Disconnect To remove access, disconnect Virtual Mail from your app settings in ChatGPT. # Claude > Install the Virtual Mail connector in Claude from the Claude connectors directory. Web page: https://reference.earthclassmail.com/v2/mcp/claude/ Virtual Mail is available as a connector in **Claude**. Install it from the Claude connectors directory to manage your virtual mailbox directly in a conversation. You don't need to configure a server URL or generate an API key. Once connected, it works everywhere you use Claude: on the web, desktop, and mobile. [Open Virtual Mail in Claude](https://claude.ai/directory/lz-virtual-mail) ## Install the connector 1. Open the [Virtual Mail connector listing](https://claude.ai/directory/lz-virtual-mail) in Claude, or search for **Virtual Mail** in the Claude connectors directory. 2. Click **Connect**. 3. Sign in to LegalZoom when prompted and approve the access Claude requests. 4. Start a new conversation and ask about your mail, for example: _"What arrived in my mailbox this week?"_ The connector uses the same OAuth sign-in described in [Authentication](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#authentication). It can only reach the mailboxes your LegalZoom account already has access to. > **Staying connected** > > Claude asks you to sign in to LegalZoom again at least every 30 days, even if > you use Virtual Mail daily. See > [token expiration](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#oauth-dynamic-client-registration). ## What you can do The Claude connector gives you the same capabilities as any other MCP client. You can find and read mail, organize your inbox, request scans and shreds, and track shipments and deposits. See [What you can do](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#what-you-can-do) and the [Tools Reference](https://reference.earthclassmail.com/_llms_txt/v2/mcp/tools.md) for details. > **Caution** > > Some actions, such as shredding, can't be undone once carried out. A pending > shred can be cancelled within the 7-day grace period. Review what Claude is about > to do before you approve an action that changes your mailbox. ## Disconnect To remove access, disconnect Virtual Mail from your connector settings in Claude. # Other MCP clients > Connect your AI client to the Virtual Mail MCP server — setup snippets for Claude Code, Codex, Cursor, and VS Code. Web page: https://reference.earthclassmail.com/v2/mcp/connect/ > **Tip** > > Using the ChatGPT or Claude app? Install Virtual Mail from their directory > instead — see > [ChatGPT](https://reference.earthclassmail.com/_llms_txt/v2/mcp/chatgpt.md) or [Claude](https://reference.earthclassmail.com/_llms_txt/v2/mcp/claude.md). Add the server to your AI client using the snippet for your app below. Each app has two options — pick one: - **OAuth** (recommended): leave the API key out. On first use your client opens a LegalZoom sign-in page in your browser (see [Authentication](https://reference.earthclassmail.com/_llms_txt/v2/mcp.md#authentication)). Use this if your client supports OAuth. - **API key**: paste the key you generated wherever you see `[YOUR_API_KEY]`. Use this if your client doesn't support OAuth, or for unattended agents. ## Available servers | Server | URL | |---|---| | All tools | `https://api.earthclassmail.com/v2/mcp` | | Read-only tools | `https://api.earthclassmail.com/v2/mcp/readonly` | ## Tool catalog Machine-readable descriptions of every tool the server exposes, useful for agents and automated discovery: | Format | URL | |---|---| | Plain text | [`mcp_catalog.txt`](https://api.earthclassmail.com/v2/mcp_catalog.txt) | | JSON | [`mcp_catalog.json`](https://api.earthclassmail.com/v2/mcp_catalog.json) | ## Read-only access Read-only access limits your connection to tools that can view mail — finding, listing, and reading message text. Tools that take action (scanning, shredding, moving, tagging, transferring) are not available. You can enable read-only access in either of two ways: - **Use the read-only URL** — connect to `.../v2/mcp/readonly`. Works if your client only lets you configure a URL, or if you want a connection that can never be switched to full access. - **Use the read-only header** — keep the standard URL and add the header `X-MCP-ReadOnly: true`. Works if your client supports custom headers and you prefer a single URL. ## Client setup ### Claude Code #### With OAuth **All tools:** ```sh claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp ``` **Read-only (via URL):** ```sh claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp/readonly ``` **Read-only (via header):** ```sh claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp --header "X-MCP-ReadOnly: true" ``` #### With an API key **All tools:** ```sh claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp --header "Authorization: Bearer [YOUR_API_KEY]" ``` **Read-only (via URL):** ```sh claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp/readonly --header "Authorization: Bearer [YOUR_API_KEY]" ``` **Read-only (via header):** ```sh claude mcp add --transport http virtual-mail https://api.earthclassmail.com/v2/mcp --header "Authorization: Bearer [YOUR_API_KEY]" --header "X-MCP-ReadOnly: true" ``` ### Codex #### With OAuth **All tools:** ```sh codex mcp add virtual-mail --url https://api.earthclassmail.com/v2/mcp ``` **Read-only (via URL):** ```sh codex mcp add virtual-mail --url https://api.earthclassmail.com/v2/mcp/readonly ``` **Read-only (via header)** — add to `~/.codex/config.toml`: ```toml [mcp_servers.virtual-mail] enabled = true transport = "streamable_http" url = "https://api.earthclassmail.com/v2/mcp" http_headers = { "X-MCP-ReadOnly" = "true" } ``` Then authenticate: ```sh codex mcp login virtual-mail ``` #### With an API key **All tools:** ```sh export VIRTUAL_MAIL_API_KEY="[YOUR_API_KEY]" codex mcp add virtual-mail \ --url https://api.earthclassmail.com/v2/mcp \ --bearer-token-env-var VIRTUAL_MAIL_API_KEY ``` **Read-only (via URL):** ```sh export VIRTUAL_MAIL_API_KEY="[YOUR_API_KEY]" codex mcp add virtual-mail \ --url https://api.earthclassmail.com/v2/mcp/readonly \ --bearer-token-env-var VIRTUAL_MAIL_API_KEY ``` **Read-only (via header)** — add to `~/.codex/config.toml`: ```toml [mcp_servers.virtual-mail] enabled = true transport = "streamable_http" url = "https://api.earthclassmail.com/v2/mcp" bearer_token_env_var = "VIRTUAL_MAIL_API_KEY" http_headers = { "X-MCP-ReadOnly" = "true" } ``` Then set the environment variable: ```sh export VIRTUAL_MAIL_API_KEY="[YOUR_API_KEY]" ``` ### Cursor Add to `~/.cursor/mcp.json`. #### With OAuth **All tools:** ```json { "mcpServers": { "virtual-mail": { "url": "https://api.earthclassmail.com/v2/mcp" } } } ``` **Read-only (via URL):** ```json { "mcpServers": { "virtual-mail": { "url": "https://api.earthclassmail.com/v2/mcp/readonly" } } } ``` **Read-only (via header):** ```json { "mcpServers": { "virtual-mail": { "url": "https://api.earthclassmail.com/v2/mcp", "headers": { "X-MCP-ReadOnly": "true" } } } } ``` #### With an API key **All tools:** ```json { "mcpServers": { "virtual-mail": { "url": "https://api.earthclassmail.com/v2/mcp", "headers": { "Authorization": "Bearer [YOUR_API_KEY]" } } } } ``` **Read-only (via URL):** ```json { "mcpServers": { "virtual-mail": { "url": "https://api.earthclassmail.com/v2/mcp/readonly", "headers": { "Authorization": "Bearer [YOUR_API_KEY]" } } } } ``` **Read-only (via header):** ```json { "mcpServers": { "virtual-mail": { "url": "https://api.earthclassmail.com/v2/mcp", "headers": { "Authorization": "Bearer [YOUR_API_KEY]", "X-MCP-ReadOnly": "true" } } } } ``` ### VS Code Add to `.vscode/mcp.json`. #### With OAuth **All tools:** ```json { "servers": { "virtual-mail": { "type": "http", "url": "https://api.earthclassmail.com/v2/mcp" } } } ``` **Read-only (via URL):** ```json { "servers": { "virtual-mail": { "type": "http", "url": "https://api.earthclassmail.com/v2/mcp/readonly" } } } ``` **Read-only (via header):** ```json { "servers": { "virtual-mail": { "type": "http", "url": "https://api.earthclassmail.com/v2/mcp", "headers": { "X-MCP-ReadOnly": "true" } } } } ``` #### With an API key **All tools:** ```json { "servers": { "virtual-mail": { "type": "http", "url": "https://api.earthclassmail.com/v2/mcp", "headers": { "Authorization": "Bearer [YOUR_API_KEY]" } } } } ``` **Read-only (via URL):** ```json { "servers": { "virtual-mail": { "type": "http", "url": "https://api.earthclassmail.com/v2/mcp/readonly", "headers": { "Authorization": "Bearer [YOUR_API_KEY]" } } } } ``` **Read-only (via header):** ```json { "servers": { "virtual-mail": { "type": "http", "url": "https://api.earthclassmail.com/v2/mcp", "headers": { "Authorization": "Bearer [YOUR_API_KEY]", "X-MCP-ReadOnly": "true" } } } } ``` # Tools Reference > Every tool exposed by the MCP server. Web page: https://reference.earthclassmail.com/v2/mcp/tools/ Each tool follows the same structure: - **Tool name:** The MCP action name the assistant can call. - **Description:** The AI-facing tool description exposed to the assistant as part of the MCP tool definition. - **Inputs:** The arguments the tool accepts. ## Health check ### ping - **Description:** Echo back the given message (prefixed with "pong: ") as a health check. Use only to verify MCP connectivity and the request/response round-trip. Returns no customer data and touches no account state. Read-only. - **Inputs:** - **message** (required): arbitrary text to echo back; used only to confirm the round-trip - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## Mailbox & account context ### get_current_user - **Description:** Get the profile of the currently authenticated user (the caller): user ID, first and last name, email, username, daytime phone, and account creation date. Use to identify who you are acting for or to answer questions about the caller's own account. This is the person calling, not an inbox owner — the account behind an inbox is available from list_inboxes. Read-only. - **Inputs:** - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### list_inboxes - **Description:** List the virtual mail inboxes accessible to the authenticated user. Each result includes the PMB (Private Mail Box number), account name, and unread and total mail counts. The PMB returned by this tool is the inbox identifier required by tools that operate on a specific inbox. This tool does not fetch mail items, recipients, or account details. Read-only. - **Inputs:** - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### get_inbox_overview - **Description:** Return a one-call summary of an inbox and its account: current mail counts, operations in progress, account standing, usage for the current billing period, and active alerts. Alerts may include account notices, an expiring or expired payment method, and USPS Form 1583 or address-authorization issues. Use for general inbox overview or account-health questions. Do not use it to retrieve the actual mail items (use list_mail_items); usage figures are counts, not dollar amounts. Requires pmb (from list_inboxes). Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox to summarize; obtain from list_inboxes - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## Finding mail ### list_mail_items - **Description:** Search and list mail items within one inbox, filtering by recipient, folder, status, tag and/or matching free text across sender, recipient, and scanned content. Use when the user wants to find, browse, or count mail and does not have a specific item ID ("the letter from the IRS," "what came in last week," "any checks?"). Do not use it when you already have a mail_item_id (use get_mail_item) or to read one item's full text (use get_mail_item_text). Requires pmb (from list_inboxes). Returns matching items with IDs, sender, dates, status, and a direct web_app_link to open the item in the Virtual Mail web application; for already-scanned items on AI-features accounts each item also includes the AI-derived document type (e.g. "Bank Statement") and a short summary. Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox to search; obtain from list_inboxes - **search_text** (optional): Free text to search across sender, recipient, and scanned content - **physical_status_in** (optional): Filter by physical status; allowed values: IN_STORAGE, STORAGE_FEE, SHRED_REQUESTED, SHRED_IN_PROGRESS, SHRED_COMPLETED, SHIP_REQUESTED, SHIP_IN_PROGRESS, SHIP_COMPLETED, VIRTUAL_MAIL - **digital_status_in** (optional): Filter by digital status; allowed values: NO_SCAN, SCAN_REQUESTED, SCAN_IN_PROGRESS, SCAN_COMPLETED, ACTIONS_BLOCKED_NO_REVERIFICATION, ACTIONS_BLOCKED_DOCUMENT_EXPIRED, SCAN_THRESHOLD_EXCEEDED - **check_status_in** (optional): Filter by check status; allowed values: NO_CHECK, CHECK_DETECTED, DEPOSIT_REQUESTED, DEPOSIT_COMPLETED, DEPOSIT_ERROR, DEPOSIT_PENDING, MULTIPLE_CHECKS_DETECTED, SEPARATE_CHECKS_REQUESTED, SEPARATE_CHECKS_PENDING, SEPARATE_CHECKS_COMPLETED - **flags** (optional): Filter by flags; allowed values: CHECK_DETECTED, MEDIA_DETECTED, OUTSTANDING_STORAGE_FEE, JUNK_MAIL_DETECTED - **viewed** (optional): Filter by viewed status; true = viewed only, false = unviewed only - **folder_id** (optional): Filter by folder: a system folder name (INBOX, ARCHIVE, TRASH, JUNKMAIL, or ALL for every folder) or a recipient folder ID from list_folders. Defaults to INBOX when omitted - **recipient_id** (optional): Filter by recipient ID; resolve names to IDs via list_recipients - **tag_ids** (optional): Filter by tag IDs; resolve tag names to IDs via list_tags - **sort_by** (required): Sort field; allowed values: RECEIVED_AT, RECIPIENT_NAME, SENDER_NAME - **sort_desc** (required): Sort direction: true = descending (RECEIVED_AT newest first, names Z to A), false = ascending (oldest first, names A to Z) - **first** (optional): Return at most this many items from the start of the result set; defaults to 20 when omitted, maximum 100 - **after** (optional): Cursor from page_info.end_cursor; return items after this cursor - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## Reading mail items ### get_mail_item - **Description:** Retrieve full details for one or more mail items by ID: metadata (sender, received date, mail type, physical/scan/check status, flags, storage info, current folder, pdf and envelope urls — links expire in ~60 min), a direct web_app_link to open the item in the Virtual Mail web application, and for already-scanned items on AI-features accounts, the AI-derived categorization (document type e.g. "Bank Statement" and a short summary). Use when you already have mail_item_ids (typically from list_mail_items) and need their complete state or a quick sense of what each piece is. Do not use it to search or list items (use list_mail_items), or to get the verbatim OCR text (use get_mail_item_text). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Categorization is returned only for scanned items on AI-features accounts; metadata and web_app_link are always returned. Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes. An item ID alone is not enough - **mail_item_ids** (required): One or more mail item IDs to retrieve; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### get_mail_item_text - **Description:** Retrieve the OCR-extracted text of one scanned mail item. Use when the user wants to read, summarize, search, or ask questions about the item's contents. Do not use it to obtain a downloadable file (use get_mail_item_pdf_url) or item metadata (use get_mail_item). Requires pmb (from list_inboxes) and a known mail_item_id (from list_mail_items), and the item must already be scanned. Returns up to 5 pages per call using start_page and page_count, plus total_pages for paging through longer items. Read-only. - **Inputs:** - **mail_item_id** (required): the numeric item ID; obtain from list_mail_items - **pmb** (required): Private Mail Box number of the owning inbox; obtain from list_inboxes - **start_page** (optional): 1-based first page to return; omit to start from page 1 - **page_count** (required): maximum pages to return starting at start_page (1 to 5); page through a longer item by raising start_page - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### get_mail_item_pdf_url - **Description:** Generate temporary, pre-signed links to scanned PDF files for one or more mail items when access to the actual scanned documents is needed, rather than only extracted text. Also use this to refresh pdf_url once a previously fetched link (e.g. from get_mail_item) has expired. For reading, summarizing, or searching document text, get_mail_item_text is usually the appropriate tool. Do not use it to view the envelope/exterior appearance of a piece of mail (use get_mail_item_envelope_image_url). A link is returned only for items whose scan is available; an item that has not been scanned yet, or whose scan is still in progress, has no PDF yet, and is returned without a link. Links are temporary and expire after approximately 60 minutes; each link's expiry, when available, is returned in expires_at. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more scanned mail item IDs to generate PDF links for; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### get_mail_item_envelope_image_url - **Description:** Generate temporary, pre-signed links to the envelope/exterior photos of one or more mail items when the user wants to see what an unopened piece of mail looks like from the outside, including before any scan exists. Also use this to refresh envelope_small_url/envelope_large_url once a previously fetched link (e.g. from get_mail_item) has expired. Do not use it to view the scanned document contents (use get_mail_item_pdf_url for the scanned PDF, or get_mail_item_text for extracted text). A link is returned only for the image sizes actually available for an item (envelope_small_url, envelope_large_url); an item with no envelope photo captured yet has both omitted. Links are temporary and expire after approximately 60 minutes; each link's expiry, when available, is returned alongside it. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs to generate envelope/exterior photo links for; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### get_mail_item_history - **Description:** Retrieve the chronological event timeline for one mail item: received, scanned, shipped, deposited, moved, tagged. Use when the user asks what has happened to an item, its current progress, or whether it is stuck. Do not use it to get item metadata or status fields (use get_mail_item), or to read item contents (use get_mail_item_text). Requires pmb (from list_inboxes) and a known mail_item_id (from list_mail_items). Returns paginated history entries ordered chronologically, plus total_count, page, and has_next_page for paging. Read-only. - **Inputs:** - **mail_item_id** (required): the numeric item ID whose history is wanted; obtain from list_mail_items - **pmb** (required): Private Mail Box number of the inbox that owns the item; obtain from list_inboxes - **page** (optional): 1-based page number; defaults to 1 when omitted - **page_size** (optional): number of history entries per page; defaults to 20 when omitted, maximum 100 - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## Organizing & filing ### list_recipients - **Description:** List the recipients - the named people or businesses that receive mail - configured on an inbox, each with its ID and name. Use to resolve a recipient name to its ID before filtering mail by recipient or transferring mail, or when the user asks who is set up on the inbox. Do not use it to list a recipient's mail (use list_mail_items with recipient_id) or to add, rename, or remove recipients (not supported). Requires pmb (from list_inboxes). Returns the recipients on the inbox with their IDs and names. Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox whose recipients to list; obtain from list_inboxes - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### list_tags - **Description:** List the tags available on an inbox (optionally filtered by a name fragment via match_phrase), returning tag IDs and labels. Use to resolve a tag name to its ID before filtering mail with list_mail_items or applying tags with apply_mail_items_tags. Requires pmb (from list_inboxes). Results are paginated (first/after), defaulting to 20 per page. Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox whose tags to list; obtain from list_inboxes - **match_phrase** (optional): Substring to filter tag labels by; omit to list all tags - **first** (optional): Return at most this many tags from the start of the result set; defaults to 20 when omitted, maximum 100 - **after** (optional): Cursor from page_info.end_cursor; return tags after this cursor - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### list_folders - **Description:** List all folders in an inbox — both the built-in system folders (Inbox, All Mail, Archive, Trash, Junk Mail) and the user-created custom folders — each with its id, name, type, and unread/total piece counts where available. Use to resolve a folder name to the id you pass as folder_id to list_mail_items or move tools. Requires pmb (from list_inboxes). Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox whose folders to list; obtain from list_inboxes - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### mark_mail_items_read - **Description:** Mark one or more mail items as read (viewed). Use when the user wants to clear unread status or says they have handled certain mail. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Side effect: marks the items read and lowers unread counts. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs to mark as read; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### mark_mail_items_unread - **Description:** Mark one or more mail items as unread (not viewed). Use when the user wants to restore unread status on mail they have not dealt with yet. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Side effect: marks the items unread and raises unread counts. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs to mark as unread; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### move_mail_items - **Description:** Move one or more mail items to a destination: the inbox, the archive, the trash, or a recipient folder. Use when the user wants to file, archive, or trash mail. Do not use it to permanently destroy physical mail (use request_mail_items_shred) or to reassign items to a different recipient (use transfer_mail_items_to_recipient). Requires pmb (from list_inboxes), mail_item_ids (from list_mail_items), and a destination_folder (INBOX, ARCHIVE, TRASH, or a numeric recipient-folder id from list_folders). Side effect: relocates the items, changing where they appear. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs to move; obtain from list_mail_items - **destination_folder** (required): Destination: one of INBOX, ARCHIVE, TRASH, or a numeric recipient-folder id (as a string) from list_folders - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### create_mail_item_tag - **Description:** Create a new tag (label) on an inbox so it can be applied to mail items. Use when the user wants a tag that does not yet exist. Do not use it to apply an existing tag (use apply_mail_items_tags), to filter by tag (use list_mail_items), to delete a tag (use delete_mail_item_tags), or to rename tags (not supported). Creating a label that already exists on the inbox fails. Requires pmb (from list_inboxes) and label. Returns the new tag's id and label. Side effect: creates a new tag on the inbox. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox to create the tag on; obtain from list_inboxes. Tags are inbox-scoped - **label** (required): The tag name to create; non-empty, at most 100 characters, must be unique on the inbox and not a reserved system label; existing labels are available from list_tags - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### delete_mail_item_tags - **Description:** Delete one or more tags from an inbox, which also removes them from any mail items that currently carry them. Use when the user wants to remove or clean up tags they no longer need. Do not use it to merely take a tag off specific items while keeping the tag (use apply_mail_items_tags with remove_tag_ids) or to create tags (use create_mail_item_tag). Requires pmb (from list_inboxes) and tag_ids (from list_tags). Every tag_id must currently exist on the inbox; if any is unknown the whole request fails and nothing is deleted. Side effect: permanently deletes the tags and detaches them from all items on the inbox. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the tags; obtain from list_inboxes - **tag_ids** (required): IDs of existing tags to delete from the inbox; resolve tag names to IDs via list_tags - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### apply_mail_items_tags - **Description:** Apply one or more existing tags to one or more mail items, and optionally remove tags in the same call. Use when the user wants to label or categorize mail with tags that already exist. Do not use it to create new tags (use create_mail_item_tag), delete tags (use delete_mail_item_tags), or to filter mail by tag (use list_mail_items). Requires pmb (from list_inboxes), mail_item_ids (from list_mail_items), and at least one of set_tag_ids or remove_tag_ids (from list_tags). Side effect: adds the given tags to those items and removes the specified ones. - **Inputs:** - **pmb** (required): Private Mail Box number that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs to tag; obtain from list_mail_items - **set_tag_ids** (optional): IDs of existing tags to add to every listed item; resolve tag names to IDs via list_tags. Provide at least one of set_tag_ids or remove_tag_ids - **remove_tag_ids** (optional): IDs of existing tags to remove from every listed item; resolve tag names to IDs via list_tags - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### transfer_mail_items_to_recipient - **Description:** Reassign one or more mail items to a different recipient on the inbox. Use on multi-recipient (business) inboxes when mail was attributed to the wrong recipient and needs to be moved to the correct one. Do not use it to move items between folders (use move_mail_items) or to change a recipient's own details (not supported). Requires pmb (from list_inboxes), mail_item_ids (from list_mail_items), and the target recipient_id (from list_recipients). Returns a confirmation of how many items were reassigned. Side effect: changes each item's recipient. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs to reassign; obtain from list_mail_items - **recipient_id** (required): ID of the recipient to reassign the items to; resolve names to IDs via list_recipients - **comment** (optional): Free-text note recorded with the transfer - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## Scanning & shredding ### request_mail_items_scan - **Description:** Request that the mailroom open and scan one or more physical mail items so their contents can be read; the physical originals are kept in storage afterward. Use when the user wants unscanned mail digitized ("open and scan this," "scan the letter from the IRS"). Do not use it if the item is already scanned (scan status is available from get_mail_item), to read existing text (use get_mail_item_text), or to scan and then destroy the original (use request_mail_items_scan_then_shred). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Each item is checked first: a scan is requested only for items where it is an available action, and any item that cannot be scanned (e.g. a scan is already in progress, the item is archived, or identity is not verified) is skipped and returned with a reason. Side effect: queues a staff-handled scan for the eligible items; the originals stay in storage and scanning is not instant. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more physical mail item IDs to scan; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### request_mail_items_scan_then_shred - **Description:** Request that the mailroom open and scan one or more physical mail items and then securely shred (permanently destroy) the physical originals once scanning is complete. Use when the user wants mail digitized and the paper destroyed in one step ("scan this then shred it," "scan and shred these"). Do not use it to scan and keep the original (use request_mail_items_scan), to shred without scanning first (use request_mail_items_shred), or to read existing text (use get_mail_item_text). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Each item is checked first: the operation is requested only for items where scanning is an available action, and any item that cannot be scanned (e.g. a scan is already in progress, the item is archived, or identity is not verified) is skipped and returned with a reason. Side effect: queues a staff-handled scan followed by irreversible physical destruction of the originals; scanning and shredding are not instant. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more physical mail item IDs to scan and then shred; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### cancel_mail_items_scan - **Description:** Cancel a pending scan request for one or more physical mail items before the mailroom acts on it. Use when the user wants to stop a scan that is still cancellable. Do not use it to request a scan (use request_mail_items_scan) or to read scanned contents (use get_mail_item_text). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Each item is checked first: cancellation occurs only where it is an available action, and items with no pending scan, a completed scan, or an archived state are skipped with a reason. Side effect: cancels the queued scan operation for eligible items. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more physical mail item IDs whose pending scan should be cancelled; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### request_mail_items_shred - **Description:** Request secure shredding (permanent physical destruction) of one or more physical mail items. Use when the user explicitly wants their physical mail destroyed ("shred these," "securely dispose of this"). Do not use it to merely hide or declutter items (use move_mail_items to TRASH, which is reversible); shredding is irreversible. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items), and optionally post_shred_action. Each item is checked first: a shred is requested only for items where it is an available action, and any item that cannot be shredded (e.g. a shred is already in progress, it has already been shredded, or it has been shipped) is skipped and returned with a reason. Side effect: queues an irreversible, staff-handled physical destruction for the eligible items. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more physical mail item IDs to shred; obtain from list_mail_items - **post_shred_action** (optional): What to do with the item after shredding; optional, allowed values: ARCHIVE, TRASH; when omitted the item is left in its current folder - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ### cancel_mail_items_shred - **Description:** Cancel a pending shred request for one or more physical mail items before the mailroom destroys them. Use when the user wants to stop a shred that is still cancellable. Do not use it to request a shred (use request_mail_items_shred) or to move items to TRASH (use move_mail_items). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Each item is checked first: cancellation occurs only where it is an available action, and items with no pending shred, an already completed shred, or a shipped state are skipped with a reason. Side effect: cancels the queued shred operation for eligible items. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more physical mail item IDs whose pending shred should be cancelled; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## Shipping & forwarding ### get_shipment_by_mail_item - **Description:** Retrieve the shipment(s) that carry one or more mail items: status, tracking number and link, carrier, rate, destination address, ship and delivery dates, and the mail items included in each shipment. Use when the user asks about the shipment or package for a piece of mail they can point to — "where's my package?", "did this letter get forwarded?", "track the shipment for this item." Do not use it to browse or search a mailbox's mail (use list_mail_items) or to fetch a mail item's own metadata (use get_mail_item); it returns shipping data, not the mail item. Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Returns the distinct shipments covering the requested items, deduplicated by shipment id, so several items sharing one shipment yield a single entry; a mail item that has never been shipped contributes no shipment. Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs (each a positive integer, as a string) to resolve shipments for; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## Checks & deposits ### get_check_deposit_by_mail_item - **Description:** Retrieve the check deposit(s) opened from one or more mail items: item and request statuses, check amounts, request timing and expedited handling, the destination bank account, shipment details for the physical checks, and the post-deposit operation. Use when the user asks whether the check on a specific piece of mail was deposited or about its deposit status — "was this check deposited?", "what's the deposit status for this letter?", "where did the check on this item go?" Do not use it to browse a mailbox's mail (use list_mail_items), to fetch a mail item's own metadata (use get_mail_item), or to list every deposit in an inbox (not supported). Requires pmb (from list_inboxes) and mail_item_ids (from list_mail_items). Returns one entry per requested item that has a deposit; a mail item with no deposit contributes nothing. Read-only. - **Inputs:** - **pmb** (required): Private Mail Box number of the inbox that owns the items; obtain from list_inboxes - **mail_item_ids** (required): One or more mail item IDs (each a positive integer, as a string) whose check deposits to fetch; obtain from list_mail_items - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results ## References ### get_field_reference - **Description:** Look up the authoritative meaning of a status, flag, enum, or concept returned by this MCP server, such as a mail item's digital_status or check_status. Do not use it to fetch customer data or the underlying result (use the relevant data tool, e.g. get_mail_item). The optional topic identifies a reference entry such as mail_item.digital_status. When topic is omitted, the tool returns an index of available topics; when topic is provided, it returns the raw values, short labels, and explanations for that topic. Read-only. - **Inputs:** - **topic** (optional): reference topic to retrieve, e.g. mail_item.digital_status; omit to list every available topic. Obtain valid topics from the index returned when this field is omitted - **user_intent** (optional): Briefly state only the generic requested action and purpose (max 200 characters). Never include, copy, or infer names of people, businesses, accounts, inbox owners, senders, or recipients; street, mailing, email, or IP addresses; PMBs, IDs, phone numbers, exact search text, document contents, secrets, private reasoning, or values from tool results # Public API Documentation > Authentication, rate limits, paging, and key concepts for the Virtual Mail Public API. Web page: https://reference.earthclassmail.com/v1/rest-api/ The Virtual Mail Public API provides direct HTTP access to virtual-mail resources — inboxes, mail items (pieces), scans, media, shipments, and more. If any difficulties arise, please email [api@earthclassmail.com](mailto:api@earthclassmail.com) with your questions. ## OpenAPI Spec The OpenAPI 3.1 specification is available as a YAML file for import into tools like Postman, Swagger UI, or code generators: | Format | Link | |---|---| | YAML | [`rest-api-v1.yaml`](https://reference.earthclassmail.com/rest-api-v1.yaml) | Response schemas and examples describe the documented fields. Responses may include additional fields; clients should ignore fields they don't recognize. ## Base URL All endpoints are relative to: ``` https://api.earthclassmail.com/v1 ``` For example, the reference page for `GET /pieces/{piece_id}` means `GET https://api.earthclassmail.com/v1/pieces/{piece_id}`. ## Authentication All requests require a **Static API Key**, passed in an `x-api-key` header. You only need one key: the same key works for the Public API and the MCP server. 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. To check that your key works, fetch the user it belongs to: ```sh curl https://api.earthclassmail.com/v1/user \ -H "x-api-key: $VIRTUAL_MAIL_API_KEY" ``` A valid key returns `200` with the user: ```json { "id": 5001, "admin_account_ids": [100, 200], "created_at": "2024-01-10T08:00:00Z", "email": "jane.doe@example.com", "first_name": "Jane", "is_admin": true, "last_name": "Doe", "phone": "15551234567", "updated_at": "2024-06-01T12:00:00Z", "username": "jane.doe@example.com" } ``` A missing or invalid key returns `401`. See [Get Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md) for the full response schema. ## Errors Failed requests return a `4xx` or `5xx` status code with a JSON body in this shape: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` - **code** — Usually the HTTP status code repeated in the body, but not always: a request to an unknown path returns HTTP `400` with `code` `500`. Use the HTTP status. - **message** — A human-readable description. For validation errors it lists each problem as `field: message`. Don't parse it; the wording can change. - **type** — The kind of error: `REST` or `Authorization`. - **fields** — Only present on `422`. It may give more details about what failed validation, as lists of messages keyed by the name of the input. | Status | Meaning | Retry? | | --- | --- | --- | | `400` | The request can't be processed as sent. | No — fix the request. | | `401` | The `x-api-key` header is missing or invalid, or you don't have access to an ID in the request. | No — fix the key or the ID. | | `403` | Actions on a piece in the request are blocked. The piece's `attributes` include `actions-blocked-no-reverification` or `actions-blocked-document-expired`. | No. | | `404` | The resource exists and you can access it, but the thing you asked for doesn't — for example, a piece with no pending shred request. | No. | | `409` | The request conflicts with the resource's current state, for example an operation already in progress. | Only after checking the resource's state. | | `422` | The request failed validation; see `fields`. | No — fix the request. | | `429` | Rate limit exceeded; see [Rate limiting](#rate-limiting). | Yes, after the 5-minute block ends. | | `5xx` | Unexpected server error. | Yes for `GET`, with backoff. For other methods, check whether the action took effect first. | An ID that doesn't exist and an ID that belongs to another account return the same response, so a mistyped or stale ID returns this `401`: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` The API doesn't support idempotency keys. Before retrying a request that changes something, such as creating a shipment or shredding, fetch the resource and confirm the first attempt didn't succeed. Emailing a scan can't be checked this way, so retrying it sends the email again. ## Rate limiting To maintain a high quality of service, request rate limiting is enforced. The maximum number of requests per minute from a single IP is **300**. If you exceed this limit, the API will respond with `429 Too Many Requests` status codes for **5 minutes** from the time the limit was exceeded. This rate limit applies to **all endpoints combined**. > **Note** > > It's good practice to code your application to handle rate limiting, even if you > don't expect to hit the limit. ## Paging Most "list" endpoints support paging through the following query string parameters: - **page** — The desired page from the result set. Integer. Defaults to `1`. - **per_page** — The number of items per page. Integer. Defaults to `100`. Listing an inbox's pieces is the exception: it defaults to `95` and returns at most `95` items per page. ## Key Concepts - **Inbox** — A mailbox that receives mail on behalf of a user or organization. - **Piece** — An individual item of mail received at a facility and assigned to an Inbox. - **Scan** — A request to digitize a Piece. Produces Media items once completed. - **Media** — A digital image or PDF associated with a Piece (e.g., envelope photo, content scan). Includes a short-lived download URL. - **Shipment** — A request to physically forward one or more Pieces to a Shipping Address. - **Shipping Address** — A saved destination address that Pieces can be shipped to. - **Shipping Rate** — A real-time carrier quote for a Shipment, including carrier, service, and price. - **Check Deposit Request** — A request to deposit the checks found in a Piece to one of the Inbox's bank accounts. See [Depositing a Check](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/playbooks.md#depositing-a-check). # Quickstart > Make your first Virtual Mail Public API requests — fetch your user, your inboxes, and recent mail. Web page: https://reference.earthclassmail.com/v1/rest-api/quickstart/ Go from an API key to your first successful request in a few minutes: fetch your user, find your inbox, and list the mail received since a given date. ## 1. Get an API key In the Virtual Mail web application, go to **Settings → Integrations → Custom API integration** and generate a key. See [Authentication](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md#authentication) for details. Every request sends the key in the `x-api-key` header. In the examples below, replace `[YOUR_API_KEY]` with your key. The Node.js examples need Node.js 18 or later; the Python examples need the `requests` package (`pip install requests`). ## 2. Get your user Your user ID is needed by the other endpoints. ### curl ```bash curl "https://api.earthclassmail.com/v1/user" \ -H "x-api-key: [YOUR_API_KEY]" ``` ### Node.js ```js const res = await fetch("https://api.earthclassmail.com/v1/user", { headers: { "x-api-key": "[YOUR_API_KEY]" }, }); console.log(await res.json()); ``` ### Python ```python import requests res = requests.get( "https://api.earthclassmail.com/v1/user", headers={"x-api-key": "[YOUR_API_KEY]"}, ) print(res.json()) ``` Response: ```json { "id": 5001, "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe", "username": "jane.doe@example.com", "is_admin": true, "admin_account_ids": [100, 200], "phone": "15551234567", "created_at": "2024-01-10T08:00:00Z", "updated_at": "2024-06-01T12:00:00Z" } ``` ## 3. List your inboxes Use the `id` from the previous response (`5001`). ### curl ```bash curl "https://api.earthclassmail.com/v1/users/5001/inboxes" \ -H "x-api-key: [YOUR_API_KEY]" ``` ### Node.js ```js const res = await fetch("https://api.earthclassmail.com/v1/users/5001/inboxes", { headers: { "x-api-key": "[YOUR_API_KEY]" }, }); console.log(await res.json()); ``` ### Python ```python import requests res = requests.get( "https://api.earthclassmail.com/v1/users/5001/inboxes", headers={"x-api-key": "[YOUR_API_KEY]"}, ) print(res.json()) ``` Response: ```json { "current_page": 1, "data": [ { "id": 97599, "account": { "id": 54297, "name": "Bruce Wayne", "account_status": "Active", "ecm_numbers": ["44725"] }, "piece_counts": { "total_piece_count": 32, "scanned_piece_count": 2, "unscanned_piece_count": 30, "unread_piece_count": 0 }, "created_at": "2018-07-17T16:30:34Z", "updated_at": "2018-07-17T16:30:34Z" } ], "from": 1, "to": 1, "per_page": 100, "last_page": 1, "total": 1 } ``` ## 4. List recent mail Use an inbox `id` from the previous response (`97599`). This request returns the mail received after `2024-06-01T12:00:00Z`, newest first. ### curl ```bash curl "https://api.earthclassmail.com/v1/inboxes/97599/pieces?filters=received_after:2024-06-01T12:00:00Z&sort_by=received_at&sort_direction=1" \ -H "x-api-key: [YOUR_API_KEY]" ``` ### Node.js ```js const res = await fetch("https://api.earthclassmail.com/v1/inboxes/97599/pieces?filters=received_after:2024-06-01T12:00:00Z&sort_by=received_at&sort_direction=1", { headers: { "x-api-key": "[YOUR_API_KEY]" }, }); console.log(await res.json()); ``` ### Python ```python import requests res = requests.get( "https://api.earthclassmail.com/v1/inboxes/97599/pieces?filters=received_after:2024-06-01T12:00:00Z&sort_by=received_at&sort_direction=1", headers={"x-api-key": "[YOUR_API_KEY]"}, ) print(res.json()) ``` Response (trimmed to the main fields): ```json { "current_page": 1, "data": [ { "id": 14460061, "inbox_id": 97599, "piece_type": "mail", "piece_sub_type": "letter", "received_at": "2024-06-02T09:14:03Z", "sender": { "name": "Internal Revenue Service" }, "recipient": { "id": 122028, "inbox_id": 97599, "name": "Bruce Wayne" }, "attributes": ["unscanned", "inbox", "stored"] }, { "id": 14460059, "inbox_id": 97599, "piece_type": "mail", "piece_sub_type": "letter", "received_at": "2024-06-01T16:42:51Z", "sender": null, "recipient": { "id": 122028, "inbox_id": 97599, "name": "Bruce Wayne" }, "attributes": ["unscanned", "read", "inbox", "stored"] } ], "from": 1, "to": 2, "per_page": 95, "last_page": 1, "total": 2 } ``` A `401` response means the API key is missing or wrong. ## Next steps - Results are paged — see [Paging](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md#paging) to fetch more than the first page. - [Playbooks](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/playbooks.md) walk through common tasks such as downloading scans, shredding, and finding detected checks. - The [API Spec](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec.md) lists every endpoint, parameter, and response field. # Playbooks > Step-by-step workflows for common Virtual Mail Public API use cases. Web page: https://reference.earthclassmail.com/v1/rest-api/playbooks/ A collection of step-by-step workflows for common tasks using the Virtual Mail Public API. ## Retrieve Latest Pieces (with Images) Retrieve the most recent mail including envelope and content scan images. 1. **Retrieve Inboxes** (optional). If you already know the inbox IDs, skip this step. Otherwise, use the [Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md) endpoint to retrieve your user ID, then [List Inboxes](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxes.md) to get the inbox IDs your user has access to. 2. **Retrieve recent Pieces.** The [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) endpoint returns a paged list of Pieces for an Inbox. Sort on `received_at` and use the `received_after` filter to get the most recent items. 3. **Retrieve Piece Media.** Use the [Get Bulk Piece Media](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getbulkpiecemedia.md) endpoint with the Piece IDs. This returns envelope photos and content scans with short-lived download URLs. --- ## Requesting a Shipment Forward physical mail to a destination mailing address. 1. **Retrieve Inboxes** (optional). Use [Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md) and [List Inboxes](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxes.md) if you don't already have the inbox ID. 2. **Retrieve recent Pieces.** Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with `received_at` sorting and `received_after` filtering. 3. **Retrieve Shipping Addresses.** Use [Get Shipping Addresses](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listshippingaddresses.md) to list saved destination addresses for the inbox. 4. **Retrieve Shipping Rates.** Use [Get Shipping Rates](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getshippingrates.md) to get real-time carrier quotes for the selected pieces and address. 5. **Create Shipment.** Use [Create Shipment](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/createshipment.md) with the chosen rate to submit the shipment. 6. **Track Shipments** (optional). Use [Get Shipments](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listshipments.md) to check the status of pending shipments. --- ## Email Pieces Parse through inbox items and email scans to an external email address. 1. **Retrieve Inboxes** (optional). Use [Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md) and [List Inboxes](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxes.md) if needed. 2. **Retrieve recent Pieces.** Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with sorting and filtering. 3. **Identify scanned Pieces.** Each Piece has an `attributes` array. Items that have been scanned include the `"scanned"` attribute. Retrieve scan info with [Get Piece Scans](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpiecescans.md). 4. **Email the scan.** Use the [Share Scan via Email](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/emailscan.md) endpoint: ```json { "emails": ["recipient@example.com"] } ``` 5. **Archive** (optional). Use [Archive Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/archivepiece.md) to move the item out of the inbox after emailing. --- ## Shredding a Piece Request permanent destruction (shredding) of a physical mail item. 1. **Identify the Piece.** Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) to find the Piece ID, or use one you already have. 2. **Request shredding.** Use [Request Piece Shredding](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/requestpieceshredding.md). The shredding endpoints live under `/pieces/{piece_id}/disposal`. Optionally set `delete_scans` to `true` to also remove digital scans: ```json { "delete_scans": true } ``` 3. **Review the shredding request** (optional). Use [Get Piece Shredding Details](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpieceshredding.md) to retrieve the request details, including its estimated completion time. 4. **Cancel shredding** (optional). Use [Cancel Pending Piece Shredding](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/cancelpieceshredding.md) within the 7-day grace period. --- ## List Pieces with Detected Checks Find mail items where a check was detected during scanning. Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with the `attributes` parameter set to `payment-detected`, sorted newest first (`sort_direction=1` is descending): ``` GET /inboxes/{inbox_id}/pieces?attributes=payment-detected&sort_by=received_at&sort_direction=1 ``` Each returned Piece includes a `detected_checks_count` field indicating how many checks were found. Add the `received_after` key to `filters` (for example, `filters=received_after:2024-01-15T00:00:00Z`) to narrow results to recent items. > **Caution** > > Don't use `filters=contains:payment-detected`. The `contains` filter is a text search: it > matches sender names, recipient names, and scanned text that contain the value, and tag > names that start with it. It looks for the literal text "payment-detected", not for pieces > with detected checks. --- ## Depositing a Check Have the checks in a piece deposited to one of the inbox's bank accounts, and cancel the request if you change your mind. 1. **Find the Piece.** Use [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md) with `attributes=payment-detected`, as in [List Pieces with Detected Checks](#list-pieces-with-detected-checks), or use a Piece ID you already have. 2. **Pick a bank account.** Use [Get Check Deposit Bank Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositbankaccounts.md) to list the inbox's bank accounts, and note the `id` of the one to deposit to. 3. **Request the deposit.** Use [Request Check Deposit](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/requestcheckdeposit.md) with the bank account ID. Optionally set `expedited`, and use `post_operation_action` to shred the rest of the piece once the checks are out: ```json { "check_deposit_bank_account_id": 500, "expedited": false, "post_operation_action": { "type": "shred" } } ``` `expedited` ships the checks to the bank overnight, typically arriving the next business day, for a fee listed in [Virtual Mail detailed pricing](https://www.legalzoom.com/business/business-operations/lz-virtual-mail-detailed-pricing.html). Leave it off when the bank account's `financial_institution.expedited` is `true`: those banks get overnight delivery for free. The response is the new deposit request, with `status` set to `Opened`. A `409` means another operation is already in progress for the piece, or its checks were already requested. 4. **Track the deposit** (optional). Use [Get Requested Check Deposits for Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listpiececheckdepositrequests.md) to follow the request. `status` changes to `Shipped` once the checks are on their way, and `shipment` holds the tracking details. 5. **Cancel the deposit** (optional). Use [Cancel Check Deposit](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/cancelcheckdeposit.md) with the deposit request `id` from the previous step: ``` DELETE /pieces/{piece_id}/check-deposit-requests/{check_deposit_request_id} ``` This works only until the mailroom extracts the checks. After that it returns `400`. --- ## Retrieving Check Deposit Details Use [Get Requested Check Deposits](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositrequests.md) to retrieve deposit requests for an inbox. Each deposit request includes `status`, `bank_account`, `checks` found, `deposit_slips` with download URLs, and `requested_at` / `extracted_at` timestamps. Optional filters: `has_checks`, `date_from`, `date_to`, and sorting by `requested_at` or `extracted_at`. If you already know the Piece ID, use [Get Requested Check Deposits for Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listpiececheckdepositrequests.md) to retrieve deposit requests for that specific piece. # Specification > Base URL, authentication and every endpoint, grouped by tag. Web page: https://reference.earthclassmail.com/v1/rest-api/spec/ Endpoint reference for the Virtual Mail Public API. See [Overview](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md) for authentication, rate limits, and key concepts. ## Base URL - `https://api.earthclassmail.com/v1` ## Authorization Send your API key in the `x-api-key` header. ## Operations ### Scans - [Get Bulk Piece Media](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getbulkpiecemedia.md): `GET /media` - [Get Piece Media](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpiecemedia.md): `GET /pieces/{piece_id}/media` - [Get Piece Scans](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpiecescans.md): `GET /pieces/{piece_id}/scans` - [Share Scan via Email](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/emailscan.md): `POST /scans/{scan_id}/email` ### CheckDeposits - [Get Requested Check Deposits](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositrequests.md): `GET /inboxes/{inbox_id}/check-deposit-requests` - [Get Check Deposit Bank Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositbankaccounts.md): `GET /inboxes/{inbox_id}/check-deposit-bank-accounts` - [Get Requested Check Deposits for Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listpiececheckdepositrequests.md): `GET /pieces/{piece_id}/check-deposit-requests` - [Request Check Deposit](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/requestcheckdeposit.md): `POST /pieces/{piece_id}/check-deposit-requests` - [Cancel Check Deposit](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/cancelcheckdeposit.md): `DELETE /pieces/{piece_id}/check-deposit-requests/{check_deposit_request_id}` ### Inboxes - [List Inboxes](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxes.md): `GET /users/{user_id}/inboxes` ### Pieces - [List Inbox Pieces](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxpieces.md): `GET /inboxes/{inbox_id}/pieces` - [Get Piece Details](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpiece.md): `GET /pieces/{piece_id}` - [Archive Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/archivepiece.md): `POST /pieces/{piece_id}/archive` - [Unarchive Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/unarchivepiece.md): `DELETE /pieces/{piece_id}/archive` ### Shred - [Get Piece Shredding Details](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getpieceshredding.md): `GET /pieces/{piece_id}/disposal` - [Request Piece Shredding](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/requestpieceshredding.md): `POST /pieces/{piece_id}/disposal` - [Cancel Pending Piece Shredding](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/cancelpieceshredding.md): `DELETE /pieces/{piece_id}/disposal` ### Shipping - [Get Shipping Addresses](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listshippingaddresses.md): `GET /inboxes/{inbox_id}/shipping-addresses` - [Get Shipping Rates](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getshippingrates.md): `POST /shipping-addresses/{shipping_address_id}/rate` - [Get Shipments](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listshipments.md): `GET /inboxes/{inbox_id}/shipments` - [Create Shipment](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/createshipment.md): `POST /inboxes/{inbox_id}/shipments` ### Users - [Get User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getuser.md): `GET /users/{user_id}` - [Get Current User](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/getcurrentuser.md): `GET /user` - [List User Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listuseraccounts.md): `GET /users/{user_id}/accounts` - [List User Recipients](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listuserrecipients.md): `GET /users/{user_id}/recipients` ### Tags - [Add Tags to Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/setpiecetags.md): `PUT /pieces/{piece_id}/tags` - [Remove Tag from Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/removetagfrompiece.md): `DELETE /pieces/{piece_id}/tags/{tag_id}` - [Update Tag](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/updateinboxtag.md): `PUT /inboxes/{inbox_id}/tags/{tag_id}` - [Delete Tag](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/deleteinboxtag.md): `DELETE /inboxes/{inbox_id}/tags/{tag_id}` - [List Inbox Tags](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listinboxtags.md): `GET /inboxes/{inbox_id}/tags` - [Create Tag](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/createinboxtag.md): `POST /inboxes/{inbox_id}/tags` # Get Bulk Piece Media > `GET /media` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getbulkpiecemedia/ URL: `GET https://api.earthclassmail.com/v1/media` Returns media (envelope images, content scans) for multiple pieces in a single request. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | query | yes | string | Comma-separated list of piece IDs to retrieve media for. Required. String of comma-separated integers. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `PieceMedia`) Example: ```json { "current_page": 1, "data": [ { "content_type": "image/jpg", "id": "1_1_2_0_0", "tags": [ "color", "large", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 }, { "content_type": "image/jpg", "id": "1_1_2_0_3", "tags": [ "color", "medium", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 }, { "content_type": "image/jpg", "id": "1_1_2_0_5", "tags": [ "color", "small", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 }, { "content_type": "image/png", "id": "1_1_3_0_0", "tags": [ "bitonal", "large", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 } ], "from": 1, "last_page": 1, "per_page": 100, "to": 4, "total": 4 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) # Get Requested Check Deposits > `GET /inboxes/{inbox_id}/check-deposit-requests` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listcheckdepositrequests/ URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/check-deposit-requests` Returns check deposit requests for the given inbox. Includes details about checks found, bank account, deposit slips, and shipment tracking. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | | `has_checks` | query | no | integer | When set to 1, only returns deposit requests where checks were found. | | `sort_by` | query | no | string | Field to sort results by. Allowed values: requested_at, extracted_at. | | `sort_direction` | query | no | string | Sort order. Allowed values: asc, desc. | | `date_from` | query | no | string | Filter results to deposits created after this date. | | `date_to` | query | no | string | Filter results to deposits created before this date. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `PieceCheckDepositRequest`) Example: ```json { "current_page": 1, "data": [ { "id": 100001, "created_at": "2020-05-10T10:00:00Z", "updated_at": "2020-05-15T12:00:00Z", "operation_action": "check-deposit", "operation_status": "complete", "status": "Shipped", "check_deposit_bank_account_id": 500, "piece_id": 100002, "inbox_id": 100003, "expedited": false, "resubmittable": false, "requested_at": "2020-05-10T09:41:00Z", "extracted_at": "2020-05-10T10:05:33Z", "date_arrived_at": "2020-05-08T14:22:08Z", "check_processing_system_type": 0, "validate_only": false, "scan_page_number": 0, "post_operation_action": null, "bank_account": { "id": 500, "created_at": "2020-01-15T10:00:00Z", "updated_at": "2020-01-15T10:00:00Z", "inbox_id": 100003, "routing_number": "121000248", "account_number": "********4510", "account_display_name": "Business Checking", "account_type": "checking", "check_processing_system_type": 0, "financial_institution": { "name": "First National Bank" } }, "checks": [ { "amount_in_cents": 150000, "check_number": "008451", "piece_id": 100002, "media": [ { "content_type": "image/jpg", "tags": [ "front", "large" ], "url": "https://media.earthclassmail.com/..." } ] } ], "deposit_slips": [ { "content_type": "application/pdf", "tags": [ "deposit-slip" ], "url": "https://media.earthclassmail.com/..." } ], "shipment": { "id": 100004, "carrier": "USPS", "carrier_service": "Priority", "tracking_number": "9405500000000000000001", "external_id": null, "shipped_at": "2020-05-11T18:30:00Z", "expected_delivery_at": "2020-05-14T12:00:00Z", "delivered_at": "2020-05-13T11:45:00Z" }, "piece": null } ], "from": 1, "last_page": 1, "per_page": 100, "to": 1, "total": 1 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceCheckDepositRequest - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `operation_status` (string) - `tags` (array of string) - `check_deposit_bank_account_id` (integer or null) - `status` (string): `Opened` while the request is in progress, then `Shipped` once the checks are on their way to the bank. `Cancelled` and `Error` end a request without a deposit. - `expedited` (boolean): Whether overnight delivery to the bank was requested. See `expedited` in Request Check Deposit. - `bank_account` (`InboxCheckDepositBankAccount`) - `resubmittable` (boolean) - `checks` (array of `DepositCheck`) - `shipment` (`PieceCheckDepositShipment` or null) - `inbox_id` (integer or null) - `post_operation_action` (`PostDepositOperationAction` or null) - `piece_id` (integer) - `deposit_slips` (array of `Media`) - `requested_at` (string) - `extracted_at` (string) - `check_processing_system_type` (integer) - `validate_only` (boolean) - `scan_page_number` (integer) - `piece` (`Piece` or null) - `date_arrived_at` (string) - `deposit_slip_ids` (array of integer) ### DepositCheck - `id` (integer) - `amount_in_cents` (integer) - `check_number` (string) - `piece_id` (integer) - `media` (array of `Media`) ### InboxCheckDepositBankAccount - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer or null) - `routing_number` (string) - `check_processing_system_type` (integer) - `account_number` (string) - `account_display_name` (string) - `account_type` (string) - `financial_institution` (`BankingInstitution`) - `contact_name` (string) - `contact_business` (string) - `contact_address` (string) - `contact_phone` (string) - `rdc` (boolean) ### Media - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCheckDepositShipment - `id` (integer or null) - `carrier` (string) - `carrier_service` (string) - `tracking_number` (string) - `external_id` (string or null) - `shipped_at` (string) - `expected_delivery_at` (string) - `delivered_at` (string) ### PostDepositOperationAction - `type` (string, required): `store` keeps the piece, `shred` shreds it. One of: `store`, `shred`. ### BankingInstitution - `id` (integer) - `name` (string) - `routing_number` (string) - `has_shipping_address` (boolean) - `shipping_banking_institution_id` (integer or null) - `expedited` (boolean): When `true`, every deposit to this bank ships overnight at no extra cost, so there's no need to request `expedited`. - `shipping_addresses` (array of `ShippingAddress`) - `rdc` (boolean) - `rdcVerified` (boolean) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) # Get Check Deposit Bank Accounts > `GET /inboxes/{inbox_id}/check-deposit-bank-accounts` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listcheckdepositbankaccounts/ URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/check-deposit-bank-accounts` Returns the bank accounts checks from this inbox can be deposited to. Use an account's `id` as `check_deposit_bank_account_id` in [Request Check Deposit](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/requestcheckdeposit.md). Every member of the inbox sees the same accounts. Only inbox admins receive `routing_number` and the `contact_*` fields; other callers get the ID, display name, bank, account type and masked account number. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `InboxCheckDepositBankAccount`) Example: ```json { "current_page": 1, "data": [ { "id": 500, "created_at": "2020-04-01T09:00:00Z", "updated_at": "2020-04-01T09:00:00Z", "inbox_id": 100003, "check_processing_system_type": 0, "account_number": "********4510", "account_display_name": "Business Checking", "account_type": "checking", "financial_institution": { "id": 42, "name": "First National Bank", "expedited": true } } ], "from": 1, "last_page": 1, "per_page": 100, "to": 1, "total": 1 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### InboxCheckDepositBankAccount - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer or null) - `routing_number` (string) - `check_processing_system_type` (integer) - `account_number` (string) - `account_display_name` (string) - `account_type` (string) - `financial_institution` (`BankingInstitution`) - `contact_name` (string) - `contact_business` (string) - `contact_address` (string) - `contact_phone` (string) - `rdc` (boolean) ### BankingInstitution - `id` (integer) - `name` (string) - `routing_number` (string) - `has_shipping_address` (boolean) - `shipping_banking_institution_id` (integer or null) - `expedited` (boolean): When `true`, every deposit to this bank ships overnight at no extra cost, so there's no need to request `expedited`. - `shipping_addresses` (array of `ShippingAddress`) - `rdc` (boolean) - `rdcVerified` (boolean) ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) # List Inboxes > `GET /users/{user_id}/inboxes` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listinboxes/ URL: `GET https://api.earthclassmail.com/v1/users/{user_id}/inboxes` Lists the inboxes accessible to the given user. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `user_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | | `payload_type` | query | no | integer | Specifies the payload components to return. This is a flags parameter — values can be combined by addition. 0: All, 1: Piece data only, 2: Count only, 4: Media only. Defaults to 0. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `InboxSummary`) Example: ```json { "current_page": 1, "data": [ { "created_at": "2018-07-17T16:30:34Z", "id": 97599, "updated_at": "2018-07-17T16:30:34Z", "account": { "account_status": "Active", "ecm_numbers": [ "44725" ], "id": 54297, "name": "Bruce Wayne" }, "piece_counts": { "scanned_piece_count": 2, "total_piece_count": 32, "unread_piece_count": 0, "unscanned_piece_count": 30 } } ], "from": 1, "last_page": 1, "per_page": 100, "to": 1, "total": 1 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### InboxSummary - `id` (integer) - `created_at` (string) - `updated_at` (string) - `name` (string) - `description` (string) - `account` (`InboxSummaryAccount`) - `piece_counts` (`PieceCounts`) ### InboxSummaryAccount - `id` (integer or null) - `name` (string) - `ecm_numbers` (array of string) - `account_status` (string) - `is_account_verified` (boolean) - `is_eligible_for_reactivation` (boolean) - `is_free` (boolean) - `billing_portal_url` (string) - `mfa_optional` (boolean) ### PieceCounts - `total_piece_count` (integer or null) - `unread_piece_count` (integer or null) - `scanned_piece_count` (integer or null) - `unscanned_piece_count` (integer or null) - `mailroom_unread_piece_count` (integer or null) - `mailroom_unread_junk_mail_count` (integer or null) # List Inbox Pieces > `GET /inboxes/{inbox_id}/pieces` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listinboxpieces/ URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/pieces` Lists the pieces in an inbox. Supports sorting, filtering, and paging. ## Filters The `filters` query parameter accepts a comma-separated list of `key:value` pairs that narrow results. Allowed filter keys: `in`, `to`, `from`, `received_after`, `received_before`, `at`, `carrier`, `class`, `contains`. - **received_after** / **received_before** — Filter by received date. Value must be a valid UTC datetime. - **to** — Filter by recipient name (prefix match). - **from** — Filter by sender name (prefix match). - **in** — Filter by location. Use `all_items` to include all. - **carrier** / **class** — Filter by shipping carrier and service class. When `class` is provided, `carrier` must also be provided. - **contains** — Search within piece content. - **at** — Filter by facility location. Multiple filters can be combined in a single `filters` value. ### Examples Retrieve pieces received after a specific date: ``` ?filters=received_after:2024-01-15T00:00:00Z ``` Retrieve pieces addressed to a specific recipient: ``` ?filters=to:John Smith ``` ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 95, which is also the maximum. Larger values return 95 items per page. | | `sort_by` | query | no | string | The field to sort the result set by. Allowed values: id, received_at, sender.name, recipient.name. Defaults to id. | | `sort_direction` | query | no | integer | The direction to sort the result set by. 0 for ascending, 1 for descending. Defaults to ascending (0). | | `recipient_ids` | query | no | string | Only return pieces assigned to the given recipients. Comma-separated list of recipient IDs. | | `folder_id` | query | no | string | Only return pieces in the given folder. | | `attributes` | query | no | string | Only return pieces that have the given attributes. Allowed values: archived, trashed, payment-detected, pending, scanned, shipped, stored, unscanned. | | `filters` | query | no | string | Additional filter parameters as comma-separated key:value pairs. Allowed keys: in, to, from, received_after, received_before, at, carrier, class, contains. | | `payload_type` | query | no | integer | Specifies the payload components to return. This is a flags parameter — values can be combined by addition. 0: All, 1: Piece data only, 2: Count only, 4: Media only. Defaults to 0. | | `tag_id` | query | no | string | Limits results to items with the specified tags. Comma-separated list of tag IDs. Possible values are provided by the listInboxTags operation. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `Piece`) Example: ```json { "current_page": 1, "data": [ { "created_at": "2018-07-23T21:25:52Z", "id": 14460059, "updated_at": "2018-07-23T21:25:52Z", "attributes": [ "unscanned", "read", "inbox", "stored" ], "barcode": "0000000101 0016615290", "carrier": { "class": "Unknown", "name": "Unknown" }, "depth_in_inches": 0.1, "end_user_operation_status": null, "height_in_inches": 3.9, "inbox_id": 97599, "insights": [], "length_in_inches": 8.88, "license_plate": 433808312186, "mailbox_folder_id": 0, "media": [ { "content_type": "image/jpg", "id": "1_1_2_0_3", "tags": [ "color", "medium", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2018-09-12T20:46:01Z", "page_count": 1, "piece_id": 14460059 } ], "operation_action": null, "page_count_actual": null, "page_count_estimate": 2, "piece_sub_type": "letter", "piece_type": "mail", "received_at": "2018-07-23T21:25:52Z", "recipient": { "id": 122028, "inbox_id": 97599, "name": "Bruce Wayne" }, "sender": null, "tags": [ "unscanned", "read", "inbox", "stored" ], "user_defined_tags": [], "weight_in_ounces": 0.16 } ], "from": 1, "last_page": 15, "per_page": 1, "to": 1, "total": 15 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Get Piece Details > `GET /pieces/{piece_id}` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getpiece/ URL: `GET https://api.earthclassmail.com/v1/pieces/{piece_id}` Returns the details of a single piece, including its attributes, recipient, and sender information. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Responses ### 200 Success Content type: `application/json` Type: `Piece` Example: ```json { "created_at": "2018-07-23T21:25:52Z", "id": 14460059, "updated_at": "2018-07-23T21:25:52Z", "attributes": [ "unscanned", "read", "inbox", "stored" ], "barcode": "0000000101 0016615290", "carrier": { "class": "Unknown", "name": "Unknown" }, "depth_in_inches": 0.1, "end_user_operation_status": null, "height_in_inches": 3.9, "inbox_id": 97599, "insights": [], "length_in_inches": 8.88, "license_plate": 433808312186, "mailbox_folder_id": 0, "media": [ { "content_type": "image/jpg", "id": "1_1_2_0_3", "tags": [ "color", "medium", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2018-09-12T22:04:36Z", "page_count": 1, "piece_id": 14460059 } ], "ocr_data": "", "operation_action": null, "page_count_actual": null, "page_count_estimate": 2, "piece_sub_type": "letter", "piece_type": "mail", "received_at": "2018-07-23T21:25:52Z", "recipient": { "id": 122028, "inbox_id": 97599, "name": "Bruce Wayne" }, "sender": null, "tags": [ "unscanned", "read", "inbox", "stored" ], "user_defined_tags": [], "weight_in_ounces": 0.16 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Get Piece Media > `GET /pieces/{piece_id}/media` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getpiecemedia/ URL: `GET https://api.earthclassmail.com/v1/pieces/{piece_id}/media` Returns the media (envelope images, content scans) associated with a single piece, along with short-lived URLs for downloading the files. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `PieceMedia`) Example: ```json { "current_page": 1, "data": [ { "content_type": "image/jpg", "id": "1_1_2_0_0", "tags": [ "color", "large", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 }, { "content_type": "image/jpg", "id": "1_1_2_0_3", "tags": [ "color", "medium", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 }, { "content_type": "image/jpg", "id": "1_1_2_0_5", "tags": [ "color", "small", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 }, { "content_type": "image/png", "id": "1_1_3_0_0", "tags": [ "bitonal", "large", "enclosure", "front" ], "url": "https://media.earthclassmail.com/...", "url_valid_until": "2019-05-03T15:38:35Z", "page_count": 1, "piece_id": 14460059 } ], "from": 1, "last_page": 1, "per_page": 100, "to": 4, "total": 4 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) # Archive Piece > `POST /pieces/{piece_id}/archive` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/archivepiece/ URL: `POST https://api.earthclassmail.com/v1/pieces/{piece_id}/archive` Archives a piece. Archived pieces are hidden from the default inbox view but can still be retrieved using the `archived` attribute filter. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Responses ### 200 Success Content type: `application/json` Type: `Piece` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Unarchive Piece > `DELETE /pieces/{piece_id}/archive` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/unarchivepiece/ URL: `DELETE https://api.earthclassmail.com/v1/pieces/{piece_id}/archive` Removes the archived status from a piece, restoring it to the default inbox view. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Responses ### 200 Success Content type: `application/json` Type: `Piece` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Get Piece Shredding Details > `GET /pieces/{piece_id}/disposal` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getpieceshredding/ URL: `GET https://api.earthclassmail.com/v1/pieces/{piece_id}/disposal` Gets the details of the pending or completed shredding request for a piece. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Responses ### 200 Success Content type: `application/json` Type: `PieceDisposal` Example: ```json { "id": 100001, "piece_id": 100002, "created_at": "2020-05-10T10:00:00Z", "updated_at": "2020-05-10T10:00:00Z", "operation_action": "shred", "tags": [], "estimated_completed_at": "2020-05-12T10:00:00Z", "completed_at": null, "delete_scans": false, "piece": null } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 404 The piece has no pending shred request. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceDisposal - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `tags` (array of string) - `piece_id` (integer) - `estimated_completed_at` (string or null) - `completed_at` (string or null) - `delete_scans` (boolean or null) - `piece` (`Piece` or null) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Request Piece Shredding > `POST /pieces/{piece_id}/disposal` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/requestpieceshredding/ URL: `POST https://api.earthclassmail.com/v1/pieces/{piece_id}/disposal` Requests that a piece be shredded. Since shredding requires human action, the piece is not shredded immediately. The expected shredding time is included in the response payload. Physical pieces are always shredded. The request body must be a JSON object; an empty object (`{}`) is accepted. Returns `409` if the piece is no longer active or another operation is already in progress for it. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `PieceDisposalRequest` Example — Shred and delete scans: ```json { "delete_scans": true } ``` Example — Shred and keep scans: ```json { "delete_scans": false } ``` ## Responses ### 200 Success Content type: `application/json` Type: `PieceDisposal` Example: ```json { "id": 100001, "created_at": "2018-05-21T13:57:09Z", "updated_at": "2018-05-21T13:57:09Z", "operation_action": "shred", "tags": [], "piece_id": 293086, "estimated_completed_at": "2018-05-24T13:57:09Z", "completed_at": null, "delete_scans": true, "piece": null } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ### 404 The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ### 409 The request conflicts with the current state of the resource. Content type: `application/json` Type: `Error` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceDisposal - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `tags` (array of string) - `piece_id` (integer) - `estimated_completed_at` (string or null) - `completed_at` (string or null) - `delete_scans` (boolean or null) - `piece` (`Piece` or null) ### PieceDisposalRequest - `delete_scans` (boolean): When `true`, the piece's digital scans are deleted along with the physical piece. When `false`, they are kept. When omitted, existing scans are kept. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Cancel Pending Piece Shredding > `DELETE /pieces/{piece_id}/disposal` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/cancelpieceshredding/ URL: `DELETE https://api.earthclassmail.com/v1/pieces/{piece_id}/disposal` Cancels a pending shredding request for a piece. A pending shred can be cancelled within the 7-day grace period. Returns the piece in its current state after cancellation. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Responses ### 200 Success Content type: `application/json` Type: `Piece` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Get Requested Check Deposits for Piece > `GET /pieces/{piece_id}/check-deposit-requests` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listpiececheckdepositrequests/ URL: `GET https://api.earthclassmail.com/v1/pieces/{piece_id}/check-deposit-requests` Returns check deposit requests for the given piece. Use this instead of Get Requested Check Deposits when you already know the Piece ID. Each request has the same shape as in the inbox listing. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `PieceCheckDepositRequest`) Example: ```json { "current_page": 1, "data": [ { "id": 100001, "created_at": "2020-05-10T10:00:00Z", "updated_at": "2020-05-15T12:00:00Z", "operation_action": "check-deposit", "operation_status": "complete", "status": "Shipped", "check_deposit_bank_account_id": 500, "piece_id": 100002, "inbox_id": 100003, "expedited": false, "resubmittable": false, "requested_at": "2020-05-10T09:41:00Z", "extracted_at": "2020-05-10T10:05:33Z", "date_arrived_at": "2020-05-08T14:22:08Z", "check_processing_system_type": 0, "validate_only": false, "scan_page_number": 0, "post_operation_action": null, "checks": [ { "amount_in_cents": 150000, "check_number": "008451", "piece_id": 100002, "media": [ { "content_type": "image/jpg", "tags": [ "front", "large" ], "url": "https://media.earthclassmail.com/..." } ] } ], "deposit_slips": [ { "content_type": "application/pdf", "tags": [ "deposit-slip" ], "url": "https://media.earthclassmail.com/..." } ], "piece": null } ], "from": 1, "last_page": 1, "per_page": 100, "to": 1, "total": 1 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceCheckDepositRequest - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `operation_status` (string) - `tags` (array of string) - `check_deposit_bank_account_id` (integer or null) - `status` (string): `Opened` while the request is in progress, then `Shipped` once the checks are on their way to the bank. `Cancelled` and `Error` end a request without a deposit. - `expedited` (boolean): Whether overnight delivery to the bank was requested. See `expedited` in Request Check Deposit. - `bank_account` (`InboxCheckDepositBankAccount`) - `resubmittable` (boolean) - `checks` (array of `DepositCheck`) - `shipment` (`PieceCheckDepositShipment` or null) - `inbox_id` (integer or null) - `post_operation_action` (`PostDepositOperationAction` or null) - `piece_id` (integer) - `deposit_slips` (array of `Media`) - `requested_at` (string) - `extracted_at` (string) - `check_processing_system_type` (integer) - `validate_only` (boolean) - `scan_page_number` (integer) - `piece` (`Piece` or null) - `date_arrived_at` (string) - `deposit_slip_ids` (array of integer) ### DepositCheck - `id` (integer) - `amount_in_cents` (integer) - `check_number` (string) - `piece_id` (integer) - `media` (array of `Media`) ### InboxCheckDepositBankAccount - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer or null) - `routing_number` (string) - `check_processing_system_type` (integer) - `account_number` (string) - `account_display_name` (string) - `account_type` (string) - `financial_institution` (`BankingInstitution`) - `contact_name` (string) - `contact_business` (string) - `contact_address` (string) - `contact_phone` (string) - `rdc` (boolean) ### Media - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCheckDepositShipment - `id` (integer or null) - `carrier` (string) - `carrier_service` (string) - `tracking_number` (string) - `external_id` (string or null) - `shipped_at` (string) - `expected_delivery_at` (string) - `delivered_at` (string) ### PostDepositOperationAction - `type` (string, required): `store` keeps the piece, `shred` shreds it. One of: `store`, `shred`. ### BankingInstitution - `id` (integer) - `name` (string) - `routing_number` (string) - `has_shipping_address` (boolean) - `shipping_banking_institution_id` (integer or null) - `expedited` (boolean): When `true`, every deposit to this bank ships overnight at no extra cost, so there's no need to request `expedited`. - `shipping_addresses` (array of `ShippingAddress`) - `rdc` (boolean) - `rdcVerified` (boolean) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) # Request Check Deposit > `POST /pieces/{piece_id}/check-deposit-requests` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/requestcheckdeposit/ URL: `POST https://api.earthclassmail.com/v1/pieces/{piece_id}/check-deposit-requests` Requests a deposit of the checks in a piece to one of the inbox's bank accounts. A deposit needs human action, so the response describes the new request, not a completed deposit: the mailroom extracts the checks and ships them to the bank, and the request's `status` follows those steps. Get the bank account ID from [Get Check Deposit Bank Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositbankaccounts.md). Use `post_operation_action` to shred the rest of the piece once the checks are out. Without it, the piece is kept. Returns `409` if another operation is in progress for the piece or its checks have already been requested for deposit, and `400` if the account is not active. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `CreateCheckDepositRequest` Example — Deposit and keep the piece: ```json { "check_deposit_bank_account_id": 500 } ``` Example — Expedited deposit, then shred: ```json { "check_deposit_bank_account_id": 500, "expedited": true, "post_operation_action": { "type": "shred" } } ``` ## Responses ### 200 Success Content type: `application/json` Type: `PieceCheckDepositRequest` Example: ```json { "id": 100001, "created_at": "2020-05-10T09:41:00Z", "updated_at": "2020-05-10T09:41:00Z", "operation_action": "check-deposit", "operation_status": "pending", "status": "Opened", "check_deposit_bank_account_id": 500, "piece_id": 100002, "inbox_id": 100003, "expedited": true, "post_operation_action": { "type": "shred" }, "checks": [], "piece": { "id": 100002 } } ``` ### 400 The request could not be processed, for example an international shipment without customs information. Content type: `application/json` Type: `Error` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ### 409 The request conflicts with the current state of the resource. Content type: `application/json` Type: `Error` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### CreateCheckDepositRequest - `check_deposit_bank_account_id` (integer, required): The bank account to deposit to, from [Get Check Deposit Bank Accounts](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listcheckdepositbankaccounts.md). - `expedited` (boolean): Ship the checks to the bank overnight instead of by standard mail, for a fee; see [Virtual Mail detailed pricing](https://www.legalzoom.com/business/business-operations/lz-virtual-mail-detailed-pricing.html). Overnight deposits typically reach the bank in 1 business day; allow one more for requests made after 5 PM. Skip it when the bank account's `financial_institution.expedited` is `true`: those banks get overnight delivery for free on every deposit. When the bank has no street address a courier can deliver to, the checks go by the fastest postal service instead. Default: `false`. - `post_operation_action` (`PostDepositOperationAction` or null): What to do with the rest of the piece once the checks are out. Without it, the piece is kept. ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceCheckDepositRequest - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `operation_status` (string) - `tags` (array of string) - `check_deposit_bank_account_id` (integer or null) - `status` (string): `Opened` while the request is in progress, then `Shipped` once the checks are on their way to the bank. `Cancelled` and `Error` end a request without a deposit. - `expedited` (boolean): Whether overnight delivery to the bank was requested. See `expedited` in Request Check Deposit. - `bank_account` (`InboxCheckDepositBankAccount`) - `resubmittable` (boolean) - `checks` (array of `DepositCheck`) - `shipment` (`PieceCheckDepositShipment` or null) - `inbox_id` (integer or null) - `post_operation_action` (`PostDepositOperationAction` or null) - `piece_id` (integer) - `deposit_slips` (array of `Media`) - `requested_at` (string) - `extracted_at` (string) - `check_processing_system_type` (integer) - `validate_only` (boolean) - `scan_page_number` (integer) - `piece` (`Piece` or null) - `date_arrived_at` (string) - `deposit_slip_ids` (array of integer) ### DepositCheck - `id` (integer) - `amount_in_cents` (integer) - `check_number` (string) - `piece_id` (integer) - `media` (array of `Media`) ### InboxCheckDepositBankAccount - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer or null) - `routing_number` (string) - `check_processing_system_type` (integer) - `account_number` (string) - `account_display_name` (string) - `account_type` (string) - `financial_institution` (`BankingInstitution`) - `contact_name` (string) - `contact_business` (string) - `contact_address` (string) - `contact_phone` (string) - `rdc` (boolean) ### Media - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCheckDepositShipment - `id` (integer or null) - `carrier` (string) - `carrier_service` (string) - `tracking_number` (string) - `external_id` (string or null) - `shipped_at` (string) - `expected_delivery_at` (string) - `delivered_at` (string) ### PostDepositOperationAction - `type` (string, required): `store` keeps the piece, `shred` shreds it. One of: `store`, `shred`. ### BankingInstitution - `id` (integer) - `name` (string) - `routing_number` (string) - `has_shipping_address` (boolean) - `shipping_banking_institution_id` (integer or null) - `expedited` (boolean): When `true`, every deposit to this bank ships overnight at no extra cost, so there's no need to request `expedited`. - `shipping_addresses` (array of `ShippingAddress`) - `rdc` (boolean) - `rdcVerified` (boolean) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) # Cancel Check Deposit > `DELETE /pieces/{piece_id}/check-deposit-requests/{check_deposit_request_id}` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/cancelcheckdeposit/ URL: `DELETE https://api.earthclassmail.com/v1/pieces/{piece_id}/check-deposit-requests/{check_deposit_request_id}` Cancels a check deposit request that the mailroom hasn't acted on yet. Once the checks have been extracted from the piece, the deposit can't be cancelled. A pending scan for the piece is cancelled too. The piece goes back to the state it was in before the request. Returns the cancelled request, with `status` set to `Cancelled`, and `400` if the piece has no deposit request to cancel or the checks have already been extracted. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | | `check_deposit_request_id` | path | yes | string | The `id` of the deposit request, from [Get Requested Check Deposits for Piece](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec/operations/listpiececheckdepositrequests.md). | ## Responses ### 200 Success Content type: `application/json` Type: `PieceCheckDepositRequest` Example: ```json { "id": 100001, "created_at": "2020-05-10T09:41:00Z", "updated_at": "2020-05-10T10:02:00Z", "operation_action": "check-deposit", "operation_status": "problem", "status": "Cancelled", "check_deposit_bank_account_id": 500, "piece_id": 100002, "inbox_id": 100003, "expedited": false, "post_operation_action": null, "checks": [], "piece": { "id": 100002 } } ``` ### 400 The piece has no deposit request to cancel, or its checks have already been extracted. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 400, "message": "inbox_id: Unable to cancel Check Deposit for PieceID: 100002", "type": "REST" } } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### PieceCheckDepositRequest - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `operation_status` (string) - `tags` (array of string) - `check_deposit_bank_account_id` (integer or null) - `status` (string): `Opened` while the request is in progress, then `Shipped` once the checks are on their way to the bank. `Cancelled` and `Error` end a request without a deposit. - `expedited` (boolean): Whether overnight delivery to the bank was requested. See `expedited` in Request Check Deposit. - `bank_account` (`InboxCheckDepositBankAccount`) - `resubmittable` (boolean) - `checks` (array of `DepositCheck`) - `shipment` (`PieceCheckDepositShipment` or null) - `inbox_id` (integer or null) - `post_operation_action` (`PostDepositOperationAction` or null) - `piece_id` (integer) - `deposit_slips` (array of `Media`) - `requested_at` (string) - `extracted_at` (string) - `check_processing_system_type` (integer) - `validate_only` (boolean) - `scan_page_number` (integer) - `piece` (`Piece` or null) - `date_arrived_at` (string) - `deposit_slip_ids` (array of integer) ### DepositCheck - `id` (integer) - `amount_in_cents` (integer) - `check_number` (string) - `piece_id` (integer) - `media` (array of `Media`) ### InboxCheckDepositBankAccount - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer or null) - `routing_number` (string) - `check_processing_system_type` (integer) - `account_number` (string) - `account_display_name` (string) - `account_type` (string) - `financial_institution` (`BankingInstitution`) - `contact_name` (string) - `contact_business` (string) - `contact_address` (string) - `contact_phone` (string) - `rdc` (boolean) ### Media - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCheckDepositShipment - `id` (integer or null) - `carrier` (string) - `carrier_service` (string) - `tracking_number` (string) - `external_id` (string or null) - `shipped_at` (string) - `expected_delivery_at` (string) - `delivered_at` (string) ### PostDepositOperationAction - `type` (string, required): `store` keeps the piece, `shred` shreds it. One of: `store`, `shred`. ### BankingInstitution - `id` (integer) - `name` (string) - `routing_number` (string) - `has_shipping_address` (boolean) - `shipping_banking_institution_id` (integer or null) - `expedited` (boolean): When `true`, every deposit to this bank ships overnight at no extra cost, so there's no need to request `expedited`. - `shipping_addresses` (array of `ShippingAddress`) - `rdc` (boolean) - `rdcVerified` (boolean) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) # Get Piece Scans > `GET /pieces/{piece_id}/scans` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getpiecescans/ URL: `GET https://api.earthclassmail.com/v1/pieces/{piece_id}/scans` Retrieves all scans associated with a given piece. Returns a paged list of scan operations, including status, page counts, and completion timestamps. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `Scan`) Example: ```json { "total": 1, "per_page": 100, "current_page": 1, "last_page": 1, "from": 1, "to": 1, "data": [ { "id": 8042156, "piece_id": 15998793, "scan_type": "color", "page_count_estimate": 4, "page_count_actual": 3, "status": "complete", "operation_action": "scan", "operation_status": "complete", "post_operation_action": "store", "comments": null, "completed_at": "2026-05-20T14:32:10Z", "estimated_completed_at": "2026-05-20T15:00:00Z", "tags": [], "created_at": "2026-05-20T13:45:00Z", "updated_at": "2026-05-20T14:32:10Z" } ] } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Scan - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `operation_status` (string) - `tags` (array of string) - `piece_id` (integer) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `completed_at` (string or null) - `estimated_completed_at` (string or null) - `post_operation_action` (string or null) - `scan_type` (string) - `comments` (string or null) - `status` (string) - `piece` (`Piece` or null) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Share Scan via Email > `POST /scans/{scan_id}/email` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/emailscan/ URL: `POST https://api.earthclassmail.com/v1/scans/{scan_id}/email` Emails a scan's content (PDF) to one or more email addresses. The scan_id can be obtained from the getPieceScans operation. Sending is asynchronous: a `200 OK` with an empty body means the emails were queued, not that they were delivered. One email is sent to each address. Delivery failures are not reported back through the API. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `scan_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `ShareItemViaEmailRequest` Example: ```json { "emails": [ "recipient@example.com", "accounting@example.com" ] } ``` ## Responses ### 200 The emails were queued for sending. Response body is empty. Empty response body. ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### ShareItemViaEmailRequest - `emails` (array of string, required): Recipient addresses. Required. Every address must be a valid email address, otherwise the request fails with `422` and nothing is sent. - `comment` (string): Accepted for compatibility but currently not included in the email. # Get Shipping Addresses > `GET /inboxes/{inbox_id}/shipping-addresses` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listshippingaddresses/ URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/shipping-addresses` Returns the shipping addresses associated with the given inbox. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `ShippingAddress`) Example: ```json { "current_page": 1, "data": [ { "id": 123456, "created_at": "2020-05-10T10:00:00Z", "updated_at": "2020-05-10T10:00:00Z", "address_line_1": "1004 S Mt Olive St", "address_line_2": "", "addressee": "Molly Smith", "company": "", "country": "United States", "country_abbreviation": "US", "delivery_confidence_percent": null, "inbox_id": 123456, "is_authorized": true, "locality": "PHOENIX", "phone": "(111) 111-1111", "postal_code": "72761", "region": "Arizona", "region_abbreviation": "AZ", "requires_hs_tariff_codes": false, "requires_itn": false, "tags": [ "domestic" ] } ], "from": 1, "last_page": 1, "per_page": 100, "to": 1, "total": 1 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) # Get Shipping Rates > `POST /shipping-addresses/{shipping_address_id}/rate` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getshippingrates/ URL: `POST https://api.earthclassmail.com/v1/shipping-addresses/{shipping_address_id}/rate` Retrieves available shipping rates for shipping the given pieces to a shipping address. Rates are fetched in real time from shipping providers. Pass the `id` of the chosen rate as `rate_id` to createShipment before the rate's `expired_at`. The pieces, insurance and customs details used for the shipment are taken from the rate request, so request the rate with the same options you want to ship with. International shipments need customs information: either `custom_items` (each with a description and declared value, plus an `hs_tariff_code` when the shipping address has `requires_hs_tariff_codes`), or a `customs_description` and `declared_value_in_cents`. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `shipping_address_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `GetShippingRateEstimateRequest` Example — Domestic: ```json { "items": [ { "piece_id": 1234000 }, { "piece_id": 1234001 } ] } ``` Example — Insured domestic: ```json { "items": [ { "piece_id": 123456789 } ], "is_insured": true, "declared_value_in_cents": 100000 } ``` Example — International: ```json { "items": [ { "piece_id": 120000 } ], "custom_items": [ { "description": "men's cotton trousers", "declared_value_in_cents": 20000, "hs_tariff_code": "620520" } ] } ``` ## Responses ### 200 Success Content type: `application/json` Type: `GetShippingRateEstimateResponse` Example: ```json { "rates": [ { "carrier_service": "Express", "carrier_type": "USPS - Express", "created_at": "2020-05-10T10:00:00Z", "expired_at": "2020-05-13T10:00:00Z", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "price_in_cents": 5335, "tracking_available": true }, { "carrier_service": "Priority", "carrier_type": "USPS - Priority", "created_at": "2020-05-10T10:00:00Z", "expired_at": "2020-05-13T10:00:00Z", "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "price_in_cents": 1695, "tracking_available": true }, { "carrier_service": "GroundAdvantage", "carrier_type": "USPS - Ground Advantage", "created_at": "2020-05-10T10:00:00Z", "expired_at": "2020-05-13T10:00:00Z", "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "price_in_cents": 945, "tracking_available": true } ] } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 404 The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### GetShippingRateEstimateRequest - `items` (array of `GetShippingRateEstimateRequestItem`, required): The pieces to ship. Required, at least one. - `custom_items` (array of `GetShippingRateEstimateRequestCustomItem`): Customs line items describing the contents, for international shipments. - `signature_on_delivery` (boolean): Require a signature on delivery. Default: `false`. - `is_insured` (boolean): Insure the shipment. Set `declared_value_in_cents` to the insured value. Default: `false`. - `declared_value_in_cents` (number or null): Total declared value of the shipment, in cents. Used for insurance, and for customs when `custom_items` is not given. Rounded to whole cents. - `customs_description` (string): Description of the contents for customs, for international shipments without `custom_items`. ### GetShippingRateEstimateResponse - `rates` (array of `ShippingRate`) - `insurance` (`GetShippingRateEstimateInsurance`) - `error` (string) ### GetShippingRateEstimateInsurance - `total_insured_value_in_cents` (integer) - `price_in_cents` (integer) ### GetShippingRateEstimateRequestCustomItem - `declared_value_in_cents` (number, required): Declared value of the item, in cents. Rounded to whole cents. - `description` (string, required): Description of the item for customs. - `hs_tariff_code` (string): Harmonized System tariff code. Required when the shipping address has `requires_hs_tariff_codes`, unless `contents_type` is `Documents`. ### GetShippingRateEstimateRequestItem - `piece_id` (integer, required): ID of the piece to ship. - `declared_value_in_cents` (number or null): Declared value of this piece, in cents. Rounded to whole cents. - `customs_description` (string): Description of this piece for customs. - `has_complete_scan` (boolean) ### ShippingRate - `id` (string or null) - `carrier_type` (string) - `carrier_service` (string) - `price_in_cents` (integer) - `created_at` (string) - `expired_at` (string) - `tracking_available` (boolean) # Get Shipments > `GET /inboxes/{inbox_id}/shipments` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listshipments/ URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/shipments` Returns shipments for the given inbox. Supports filtering by status and other criteria. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | | `operation_status` | query | no | string | Filter by shipment status. Comma-separated list. Allowed values: pending, in_progress, complete, problem. | | `piece_id` | query | no | string | Filter by piece IDs. Comma-separated list of integers. | | `shipping_address_id` | query | no | string | Filter by shipping address IDs. Comma-separated list of integers. | | `carrier` | query | no | string | Filter by carrier. Comma-separated list of strings. | | `class` | query | no | string | Filter by carrier service class. Comma-separated list of strings. | | `is_insured` | query | no | boolean | Filter by insurance status. | | `signature_on_delivery` | query | no | boolean | Filter by signature requirement. | | `country_abbreviations` | query | no | string | Filter by destination country. Comma-separated list of ISO 3166-1 alpha-2 country codes. | | `postal_codes` | query | no | string | Filter by destination postal code. Comma-separated list of strings. | | `tracking_number` | query | no | string | Filter by tracking number. Comma-separated list of strings. | | `sort_by` | query | no | string | The field to sort results by. Allowed values: id, requested_at, shipped_at, ship_after, item_count. | | `sort_direction` | query | no | string | The direction to sort results. Allowed values: asc, desc. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `Shipment`) Example: ```json { "current_page": 1, "data": [ { "id": 123456, "created_at": "2024-02-01T10:00:00Z", "updated_at": "2024-02-02T10:00:20Z", "operation_action": "ship", "operation_status": "complete", "tags": [], "aes_itn": null, "completed_at": "2024-07-03T00:00:00Z", "contents_type": null, "custom_items": [], "customs_description": null, "declared_value_in_cents": null, "estimated_shipped_at": "2024-07-02T10:00:00Z", "is_insured": false, "is_shared": false, "items": [ { "customs_description": null, "declared_value_in_cents": null, "has_complete_scan": true, "piece_id": 123456 } ], "owner_user_id": "123456", "rate": { "carrier_service": "Express", "carrier_type": "USPS - Express", "created_at": "2024-04-01T12:00:00Z", "expired_at": "2024-04-04T12:00:00Z", "id": null, "price_in_cents": 3000, "tracking_available": false }, "rate_id": null, "return_address": { "address_line_1": "9450 SW Gemini Dr", "address_line_2": null, "addressee": "John Smith PMB #123456", "country": "United States", "country_abbreviation": "US", "locality": "Beaverton", "postal_code": "97008-7105", "region": "Oregon", "region_abbreviation": "OR" }, "ship_after": "2024-07-02T10:00:00Z", "shipped_at": "2024-07-02T00:00:00Z", "shipping_address": { "id": 123456, "created_at": "2022-10-10T10:00:00Z", "updated_at": "2022-10-10T10:00:00Z", "address_line_1": "1004 S Mt Olive St", "address_line_2": "", "addressee": "Molly Smith", "company": null, "country": "United States", "country_abbreviation": "US", "delivery_confidence_percent": null, "inbox_id": 123456, "is_authorized": null, "locality": "Siloam Springs", "phone": "(111) 111-1111", "postal_code": "11111", "region": "Arizona", "region_abbreviation": "AZ", "requires_hs_tariff_codes": false, "requires_itn": false, "tags": [ "domestic" ] }, "shipping_address_id": 123456, "shipping_comment": null, "signature_on_delivery": false, "tracking_number": "00000000000000000000" } ], "from": 1, "to": 1, "last_page": 1, "per_page": 100, "total": 1 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Shipment - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `operation_status` (string) - `tags` (array of string) - `shipping_address_id` (integer) - `shipping_address` (`ShippingAddress`) - `rate_id` (string or null) - `shipping_comment` (string or null) - `rate` (`ShippingRate`) - `aes_itn` (string or null) - `ship_after` (string or null) - `signature_on_delivery` (boolean) - `items` (array of `ShipmentItem`) - `custom_items` (array of `ShipmentCustomItem`) - `is_insured` (boolean) - `is_shared` (boolean) - `tracking_number` (string or null) - `declared_value_in_cents` (integer or null) - `customs_description` (string or null) - `delivered_at` (string or null) - `shipped_at` (string or null) - `estimated_shipped_at` (string or null) - `completed_at` (string or null) - `return_address` (`ShipmentReturnAddress`) - `delete_scans` (boolean) - `pieces` (array of `Piece`) - `contents_type` (string or null) - `owner_user_id` (string) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### ShipmentCustomItem - `declared_value_in_cents` (integer) - `description` (string) - `hs_tariff_code` (string) ### ShipmentItem - `piece_id` (integer) - `declared_value_in_cents` (integer or null) - `customs_description` (string or null) - `has_complete_scan` (boolean) ### ShipmentReturnAddress - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string or null) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) ### ShippingRate - `id` (string or null) - `carrier_type` (string) - `carrier_service` (string) - `price_in_cents` (integer) - `created_at` (string) - `expired_at` (string) - `tracking_available` (boolean) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Create Shipment > `POST /inboxes/{inbox_id}/shipments` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/createshipment/ URL: `POST https://api.earthclassmail.com/v1/inboxes/{inbox_id}/shipments` Creates a shipment request for one or more pieces using a rate previously retrieved with getShippingRates. The shipping address is the one the rate was requested for. The rate must not be expired, and `items` must list the same pieces the rate was requested for. All pieces must be stored at the same facility and must not be junk mail or have another operation in progress. Declared values and customs details given here replace the ones from the rate request. International shipments need customs information (see getShippingRates). If it is missing, the request fails with `400`. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `CreateShipmentRequest` Example — Create non-insured domestic shipment: ```json { "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "items": [ { "piece_id": 1234000 }, { "piece_id": 1234001 } ] } ``` Example — Create insured domestic shipment: ```json { "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "items": [ { "piece_id": 123456789 } ], "is_insured": true, "declared_value_in_cents": 100000 } ``` Example — Create international shipment: ```json { "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "items": [ { "piece_id": 120000 } ], "contents_type": "Merchandise", "custom_items": [ { "description": "men's cotton trousers", "declared_value_in_cents": 20000, "hs_tariff_code": "620520" } ] } ``` ## Responses ### 200 Success Content type: `application/json` Type: `Shipment` Example — Create non-insured domestic shipment: ```json { "created_at": "2024-11-01T10:00:00Z", "id": 60001, "updated_at": "2024-11-01T10:00:00Z", "operation_action": "ship", "operation_status": "pending", "tags": [], "aes_itn": null, "contents_type": null, "custom_items": [], "customs_description": null, "declared_value_in_cents": null, "estimated_shipped_at": "2024-11-05T20:00:00Z", "is_insured": false, "is_shared": false, "items": [ { "customs_description": null, "declared_value_in_cents": null, "has_complete_scan": false, "piece_id": 1234000 }, { "customs_description": null, "declared_value_in_cents": null, "has_complete_scan": false, "piece_id": 1234001 } ], "owner_user_id": "12345", "pieces": [], "rate": { "carrier_service": "GroundAdvantage", "carrier_type": "USPS - Ground Advantage", "created_at": "2024-11-04T10:00:00Z", "expired_at": "2024-11-07T10:00:00Z", "id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "price_in_cents": 910, "tracking_available": true }, "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "return_address": { "address_line_1": "", "address_line_2": null, "addressee": "", "country": "", "country_abbreviation": "", "locality": "", "postal_code": "", "region": "", "region_abbreviation": "" }, "ship_after": "2024-11-05T20:00:00Z", "shipping_address": { "created_at": "2024-11-04T10:00:00Z", "id": 12345, "updated_at": "2024-11-04T10:00:00Z", "address_line_1": "1004 S Mt Olive St", "address_line_2": "", "addressee": "Molly Smith", "company": null, "country": "United States", "country_abbreviation": "US", "delivery_confidence_percent": null, "inbox_id": 97599, "is_authorized": null, "locality": "PHOENIX", "phone": "", "postal_code": "72761", "region": "Arizona", "region_abbreviation": "AZ", "requires_hs_tariff_codes": false, "requires_itn": false, "tags": [ "domestic" ] }, "shipping_address_id": 12345, "shipping_comment": null, "signature_on_delivery": false, "tracking_number": null } ``` Example — Create insured domestic shipment: ```json { "created_at": "2024-11-04T10:38:05Z", "id": 300000, "updated_at": "2024-11-04T10:38:05Z", "operation_action": "ship", "operation_status": "pending", "tags": [], "aes_itn": null, "contents_type": null, "custom_items": [], "customs_description": null, "declared_value_in_cents": 100000, "estimated_shipped_at": "2024-11-20T20:00:00Z", "is_insured": true, "is_shared": false, "items": [ { "customs_description": null, "declared_value_in_cents": null, "has_complete_scan": true, "piece_id": 123456789 } ], "owner_user_id": "116561", "pieces": [], "rate": { "carrier_service": "GroundAdvantage", "carrier_type": "USPS - Ground Advantage", "created_at": "2024-11-04T10:38:00Z", "expired_at": "2024-11-07T10:38:00Z", "id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "price_in_cents": 1295, "tracking_available": true }, "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "return_address": { "address_line_1": "", "address_line_2": null, "addressee": "", "country": "", "country_abbreviation": "", "locality": "", "postal_code": "", "region": "", "region_abbreviation": "" }, "ship_after": "2024-11-20T20:00:00Z", "shipping_address_id": 123456, "shipping_comment": null, "signature_on_delivery": false, "tracking_number": null } ``` Example — Create international shipment: ```json { "created_at": "2024-11-04T10:55:40Z", "id": 234234, "updated_at": "2024-11-04T10:55:40Z", "operation_action": "ship", "operation_status": "pending", "tags": [], "aes_itn": null, "contents_type": "Merchandise", "custom_items": [ { "declared_value_in_cents": 20000, "description": "men's cotton trousers", "hs_tariff_code": "620520" } ], "customs_description": null, "declared_value_in_cents": null, "estimated_shipped_at": "2024-11-20T18:00:00Z", "is_insured": true, "is_shared": false, "items": [ { "customs_description": null, "declared_value_in_cents": null, "has_complete_scan": false, "piece_id": 120000 } ], "owner_user_id": "116561", "pieces": [], "rate": { "carrier_service": "FirstClassPackageInternationalService", "carrier_type": "USPS - First Class Package International Service", "created_at": "2024-11-04T10:55:22Z", "expired_at": "2024-11-07T10:55:22Z", "id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "price_in_cents": 2855, "tracking_available": true }, "rate_id": "1a5c1a4f-ee30-4269-abbc-63a7fc991342", "return_address": { "address_line_1": "", "address_line_2": null, "addressee": "", "country": "", "country_abbreviation": "", "locality": "", "postal_code": "", "region": "", "region_abbreviation": "" }, "ship_after": "2024-11-20T18:00:00Z", "shipping_address_id": 12345, "shipping_comment": null, "signature_on_delivery": false, "tracking_number": null } ``` ### 400 The request could not be processed, for example an international shipment without customs information. Content type: `application/json` Type: `Error` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ### 404 The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### CreateShipmentRequest - `shipping_address_id` (integer): Ignored. The shipping address is taken from the rate. - `rate_id` (string, required): The `id` of a rate returned by getShippingRates. Required. - `items` (array of `ShipmentItem`, required): The pieces to ship. Must match the pieces the rate was requested for. - `custom_items` (array of `ShipmentCustomItem`): Customs line items. Replaces the ones from the rate request. - `signature_on_delivery` (boolean): Require a signature on delivery. - `is_insured` (boolean): Insure the shipment. - `declared_value_in_cents` (integer or null): Total declared value of the shipment, in cents. - `customs_description` (string or null): Description of the contents for customs. - `aes_itn` (string or null): AES Internal Transaction Number, for destinations whose shipping address has `requires_itn`. - `contents_type` (string or null): Kind of contents, for customs. With `Documents`, HS tariff codes are not required. One of: `Merchandise`, `Documents`, `ReturnedGoods`, `null`. - `ship_after` (string): Earliest date to ship. Optional. If it is missing or not a valid shipping date, the next valid shipping date is used. ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Shipment - `id` (integer) - `created_at` (string) - `updated_at` (string) - `operation_action` (string) - `operation_status` (string) - `tags` (array of string) - `shipping_address_id` (integer) - `shipping_address` (`ShippingAddress`) - `rate_id` (string or null) - `shipping_comment` (string or null) - `rate` (`ShippingRate`) - `aes_itn` (string or null) - `ship_after` (string or null) - `signature_on_delivery` (boolean) - `items` (array of `ShipmentItem`) - `custom_items` (array of `ShipmentCustomItem`) - `is_insured` (boolean) - `is_shared` (boolean) - `tracking_number` (string or null) - `declared_value_in_cents` (integer or null) - `customs_description` (string or null) - `delivered_at` (string or null) - `shipped_at` (string or null) - `estimated_shipped_at` (string or null) - `completed_at` (string or null) - `return_address` (`ShipmentReturnAddress`) - `delete_scans` (boolean) - `pieces` (array of `Piece`) - `contents_type` (string or null) - `owner_user_id` (string) ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### ShipmentCustomItem - `declared_value_in_cents` (integer) - `description` (string) - `hs_tariff_code` (string) ### ShipmentItem - `piece_id` (integer) - `declared_value_in_cents` (integer or null) - `customs_description` (string or null) - `has_complete_scan` (boolean) ### ShipmentReturnAddress - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string or null) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) ### ShippingAddress - `id` (integer) - `created_at` (string) - `updated_at` (string) - `addressee` (string) - `address_line_1` (string) - `address_line_2` (string) - `locality` (string) - `region_abbreviation` (string) - `region` (string) - `country_abbreviation` (string) - `country` (string) - `postal_code` (string) - `phone` (string) - `tags` (array of string) - `delivery_confidence_percent` (number or null) - `inbox_id` (integer or null) - `company` (string or null) - `is_authorized` (boolean or null) - `requires_hs_tariff_codes` (boolean or null) - `requires_itn` (boolean or null) ### ShippingRate - `id` (string or null) - `carrier_type` (string) - `carrier_service` (string) - `price_in_cents` (integer) - `created_at` (string) - `expired_at` (string) - `tracking_available` (boolean) ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Get User > `GET /users/{user_id}` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getuser/ URL: `GET https://api.earthclassmail.com/v1/users/{user_id}` Returns the details of a specific user by their user ID. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `user_id` | path | yes | string | | ## Responses ### 200 Success Content type: `application/json` Type: `User` Example: ```json { "id": 5001, "admin_account_ids": [ 100, 200 ], "created_at": "2024-01-10T08:00:00Z", "email": "jane.doe@example.com", "first_name": "Jane", "is_admin": true, "last_name": "Doe", "phone": "15551234567", "updated_at": "2024-06-01T12:00:00Z", "username": "jane.doe@example.com" } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### User - `id` (integer) - `created_at` (string) - `updated_at` (string) - `uuid` (string) - `first_name` (string) - `last_name` (string) - `email` (string) - `username` (string) - `phone` (string) - `is_admin` (boolean) - `admin_account_ids` (array of integer) # Get Current User > `GET /user` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/getcurrentuser/ URL: `GET https://api.earthclassmail.com/v1/user` Returns the details of the currently authenticated user. Use this to retrieve your user ID, which is required by other endpoints. ## Authorization Send your API key in the `x-api-key` header. ## Responses ### 200 Success Content type: `application/json` Type: `User` Example: ```json { "id": 5001, "admin_account_ids": [ 100, 200 ], "created_at": "2024-01-10T08:00:00Z", "email": "jane.doe@example.com", "first_name": "Jane", "is_admin": true, "last_name": "Doe", "phone": "15551234567", "updated_at": "2024-06-01T12:00:00Z", "username": "jane.doe@example.com" } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### User - `id` (integer) - `created_at` (string) - `updated_at` (string) - `uuid` (string) - `first_name` (string) - `last_name` (string) - `email` (string) - `username` (string) - `phone` (string) - `is_admin` (boolean) - `admin_account_ids` (array of integer) # List User Accounts > `GET /users/{user_id}/accounts` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listuseraccounts/ URL: `GET https://api.earthclassmail.com/v1/users/{user_id}/accounts` Returns the accounts associated with the given user. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `user_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `Account`) Example: ```json { "current_page": 1, "data": [ { "id": 100, "account_status": "Active", "billing_portal_url": "https://www.billingportal.com/manage/1000000/1000000/100000000", "closed_at": null, "account_closure_in_progress": false, "created_at": "2024-01-10T08:00:00Z", "description": null, "has_cancellation_zendesk_ticket": false, "is_account_verified": true, "is_free": false, "name": "Acme Corporation", "terminate_after_date": null, "updated_at": "2024-01-10T08:00:00Z" }, { "id": 200, "account_status": "Closed", "billing_portal_url": "https://www.billingportal.com/manage/2000000/2000000/200000000", "closed_at": "2025-03-15T12:00:00Z", "account_closure_in_progress": false, "created_at": "2024-03-05T14:30:00Z", "description": null, "has_cancellation_zendesk_ticket": true, "is_account_verified": true, "is_free": false, "name": "Wayne Enterprises", "terminate_after_date": "2025-06-15T00:00:00Z", "updated_at": "2025-03-15T12:00:00Z" } ], "from": 1, "to": 2, "last_page": 1, "per_page": 100, "total": 2 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Account - `id` (integer) - `created_at` (string) - `updated_at` (string) - `name` (string) - `description` (string or null) - `closed_at` (string or null) - `billing_portal_url` (string) - `is_account_verified` (boolean) - `is_free` (boolean) - `account_closure_in_progress` (boolean) - `account_status` (string) - `terminate_after_date` (string or null) - `has_cancellation_zendesk_ticket` (boolean) ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. # List User Recipients > `GET /users/{user_id}/recipients` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listuserrecipients/ URL: `GET https://api.earthclassmail.com/v1/users/{user_id}/recipients` Returns the recipients associated with the given user across all their inboxes. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `user_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `Recipient`) Example: ```json { "current_page": 1, "data": [ { "id": 1001, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "name": "Jane Doe", "type": "recipient" }, { "id": 1002, "created_at": "2024-02-20T14:00:00Z", "updated_at": "2024-02-20T14:00:00Z", "name": "John Smith", "type": "recipient" } ], "from": 1, "to": 100, "last_page": 2, "per_page": 100, "total": 120 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Recipient - `id` (integer) - `created_at` (string) - `updated_at` (string) - `name` (string) - `type` (string) - `is_new_pmb` (boolean) - `ecm_number` (string) # Add Tags to Piece > `PUT /pieces/{piece_id}/tags` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/setpiecetags/ URL: `PUT https://api.earthclassmail.com/v1/pieces/{piece_id}/tags` Adds tags to a piece. Only inserts tags not already present on the piece; existing tags are kept. Does not remove any tags. All tags must belong to the piece's inbox. If any tag is not found, the request fails with `404` and no tags are added. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `PutPieceTagsRequest` Example: ```json { "tag_ids": [ 3001, 3002 ] } ``` ## Responses ### 200 Success Content type: `application/json` Type: `Piece` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ### 404 The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Piece - `id` (integer) - `created_at` (string) - `updated_at` (string) - `inbox_id` (integer) - `barcode` (string) - `license_plate` (integer) - `recipient` (`PieceRecipient`) - `mailbox_folder_id` (integer) - `tags` (array of string) - `attributes` (array of string) - `sender` (`PieceSender` or null) - `received_at` (string) - `date_arrived_in_mailbox` (string) - `weight_in_ounces` (number) - `facility_name` (string) - `page_count_estimate` (integer) - `page_count_actual` (integer or null) - `height_in_inches` (number) - `depth_in_inches` (number) - `length_in_inches` (number) - `carrier` (`PieceCarrier`) - `media` (array of `PieceMedia`) - `ocr_data` (string) - `envelope_ocr_data` (string) - `piece_type` (string) - `piece_sub_type` (string) - `insights` (array of `PieceInsight`) - `user_defined_tags` (array of `Tag`) - `matched_by` (array of string) - `operation_action` (string or null) - `end_user_operation_status` (string or null) - `storage_fee_amount_in_cents` (integer) - `can_delete_scan_only` (boolean) - `available_actions` (array of string) - `name` (string) - `detected_checks_count` (integer or null) - `recipient_type` (string) ### PutPieceTagsRequest - `tag_ids` (array of integer, required): Tag IDs to add to the piece. At least one. Tags already on the piece are kept. ### PieceCarrier - `name` (string) - `class` (string) ### PieceInsight - `type` (string) - `confidence` (number) ### PieceMedia - `id` (string) - `url` (string) - `content_type` (string) - `tags` (array of string) - `url_valid_until` (string) - `file_size_in_bytes` (integer) - `piece_id` (integer or null) - `scan_id` (integer or null) - `page_count` (integer or null) - `sequence_number` (integer or null) ### PieceRecipient - `id` (integer) - `name` (string) - `inbox_id` (integer or null) - `type` (string) ### PieceSender - `name` (string) - `address` (string) ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Remove Tag from Piece > `DELETE /pieces/{piece_id}/tags/{tag_id}` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/removetagfrompiece/ URL: `DELETE https://api.earthclassmail.com/v1/pieces/{piece_id}/tags/{tag_id}` Removes a single tag from a piece. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `piece_id` | path | yes | string | | | `tag_id` | path | yes | string | | ## Responses ### 200 Tag removed from piece successfully. Response body is empty. Empty response body. ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 403 Actions are blocked for a piece in the request. When an account's mail actions are blocked, for example because the account wasn't reverified or an identity document expired, pieces received after that can't be changed. These pieces have `actions-blocked-no-reverification` or `actions-blocked-document-expired` in their `attributes`. Content type: `application/json` Type: `Error` Example — Piece actions blocked: ```json { "error": { "code": 403, "message": "piece: Mail actions for piece with ID 123456 has been blocked.", "type": "REST" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. # Update Tag > `PUT /inboxes/{inbox_id}/tags/{tag_id}` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/updateinboxtag/ URL: `PUT https://api.earthclassmail.com/v1/inboxes/{inbox_id}/tags/{tag_id}` Updates an existing tag. This is a full replacement: send every field. Omitting `parent_tag_id` makes the tag a top-level tag. The label rules of createInboxTag apply. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `tag_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `TagInput` Example: ```json { "label": "Invoices" } ``` ## Responses ### 200 Success Content type: `application/json` Type: `Tag` Example: ```json { "id": 204496, "created_at": "2026-06-03T08:35:08Z", "updated_at": "2026-06-03T08:35:08Z", "label": "test-tag-1" } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 404 The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ### 409 The request conflicts with the current state of the resource. Content type: `application/json` Type: `Error` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) ### TagInput - `label` (string, required): The tag's label. Required. Must be unique within the inbox and must not be a reserved system label. - `parent_tag_id` (integer or null): ID of the parent tag, to nest this tag under another tag in the same inbox. Optional. A tag cannot be its own parent. # Delete Tag > `DELETE /inboxes/{inbox_id}/tags/{tag_id}` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/deleteinboxtag/ URL: `DELETE https://api.earthclassmail.com/v1/inboxes/{inbox_id}/tags/{tag_id}` Deletes a tag from the given inbox. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `tag_id` | path | yes | string | | ## Responses ### 200 Tag deleted from inbox successfully. Response body is empty. Empty response body. ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. # List Inbox Tags > `GET /inboxes/{inbox_id}/tags` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/listinboxtags/ URL: `GET https://api.earthclassmail.com/v1/inboxes/{inbox_id}/tags` Lists the tags defined for an inbox. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | | `page` | query | no | integer | The desired page from the result set. Defaults to 1. | | `per_page` | query | no | integer | The number of items per page. Defaults to 100. | ## Responses ### 200 Success Content type: `application/json` - `total` (integer): Total number of items across all pages. - `per_page` (integer): Number of items per page. - `current_page` (integer): The current page number (1-based). - `last_page` (integer): The last available page number. - `from` (integer): The index of the first item on this page (1-based). - `to` (integer): The index of the last item on this page (1-based). - `data` (array of `Tag`) Example: ```json { "current_page": 1, "data": [ { "id": 3001, "label": "Urgent", "piece_counts": 12 }, { "id": 3002, "label": "Invoices", "piece_counts": 45 } ], "from": 1, "to": 2, "last_page": 1, "per_page": 100, "total": 2 } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) # Create Tag > `POST /inboxes/{inbox_id}/tags` Web page: https://reference.earthclassmail.com/v1/rest-api/spec/operations/createinboxtag/ URL: `POST https://api.earthclassmail.com/v1/inboxes/{inbox_id}/tags` Creates a new tag for the given inbox. Labels must be unique within the inbox; creating a tag with a label that already exists fails with `409`. Labels used by the system (for example `scanned`, `shredded` or `archived`) are reserved and fail with `422`, regardless of case. ## Authorization Send your API key in the `x-api-key` header. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | `inbox_id` | path | yes | string | | ## Request body Required. Content type: `application/json` Type: `TagInput` Example: ```json { "label": "Invoices" } ``` ## Responses ### 200 Success Content type: `application/json` Type: `Tag` Example: ```json { "id": 204496, "created_at": "2026-06-03T08:35:08Z", "updated_at": "2026-06-03T08:35:08Z", "label": "test-tag-1" } ``` ### 401 The `x-api-key` header is missing or the key is not valid, or the caller can't access an ID in the request. IDs that don't exist return the same response as IDs the caller can't access. Content type: `application/json` Type: `Error` Example — Missing API key: ```json { "error": { "code": 401, "message": "The request does not include a valid access token. Please provide a valid access token.", "type": "Authorization" } } ``` Example — Invalid API key: ```json { "error": { "code": 401, "message": "x-api-key: x-api-key is invalid", "type": "REST" } } ``` Example — No access to resource: ```json { "error": { "code": 401, "message": "User does not have access to requested resource.", "type": "Authorization" } } ``` ### 404 The referenced resource is accessible, but the requested item does not exist, for example a pending operation. IDs the caller can't access, or that don't exist at all, return `401` instead. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 404, "message": "piece_id: Piece with ID 14460059 does not have outstanding Operation of type Recycle.", "type": "REST" } } ``` ### 409 The request conflicts with the current state of the resource. Content type: `application/json` Type: `Error` ### 422 The request body failed validation. The message names the invalid field. Content type: `application/json` Type: `Error` Example: ```json { "error": { "code": 422, "message": "label: must have a value", "type": "REST", "fields": {} } } ``` ## Schemas ### Error Error envelope returned with 4xx and 5xx responses. - `error` (object) - `code` (integer): Usually the HTTP status code. It can differ; a request to an unknown path returns HTTP 400 with code 500. - `message` (string): Human-readable description of the error. - `type` (string): The kind of error, for example `Authorization` or `REST`. - `fields` (object): Returned only with `422` responses. It may give more details about what failed validation, as lists of messages keyed by the name of the input. ### Tag - `id` (integer) - `created_at` (string) - `updated_at` (string) - `label` (string) - `parent_tag_id` (integer or null) - `piece_counts` (integer or null) ### TagInput - `label` (string, required): The tag's label. Required. Must be unique within the inbox and must not be a reserved system label. - `parent_tag_id` (integer or null): ID of the parent tag, to nest this tag under another tag in the same inbox. Optional. A tag cannot be its own parent.