# bot.mailbox/mailbox (remote · mailbox.bot)

Physical mail API for AI agents. Send letters, certified mail. Sandbox + live keys via MCP.

- Trust score: 75/100 (medium)
- Change this week: +9
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `mailbox.bot`: 75/100 (this document), [markdown](https://verifymcp.io/servers/bot-mailbox-mailbox/api-mcp.md), [page](https://verifymcp.io/servers/bot-mailbox-mailbox/api-mcp)

## Channel facts

- Endpoint: `https://mailbox.bot/api/mcp`
- Transports: `streamable-http`
- Auth: `required`
- Version: `1.0.1`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 89/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation is enforced on tool calls, but the challenge carries no valid RFC 9728 metadata, so a client cannot discover where to get a token.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC check failed: this domain isn't protected by DNSSEC.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 57/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 5741 tokens (~191/item across 30 items; 30 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability check failed: schema churn in the 8 days we've observed: 0 tool removals, 2 breaking changes, 0 auth/transport breaks, 0 additions.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (100% of tools); any adoption earns full credit.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http bot-mailbox-mailbox https://mailbox.bot/api/mcp
```

### Codex

```toml
[mcp_servers.bot-mailbox-mailbox]
url = "https://mailbox.bot/api/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bot-mailbox-mailbox": {
      "type": "remote",
      "url": "https://mailbox.bot/api/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add bot-mailbox-mailbox --url https://mailbox.bot/api/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  bot-mailbox-mailbox:
    url: "https://mailbox.bot/api/mcp"
```

### Other

```json
{
  "mcpServers": {
    "bot-mailbox-mailbox": {
      "type": "http",
      "url": "https://mailbox.bot/api/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 75, +1)

No change was recorded against any check on this day. Stability & Change Management went from 16 to 20.

### 2026-07-31 (score 74, +5)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 69, +1)

No change was recorded against any check on this day. Stability & Change Management went from 6 to 10.

### 2026-07-29 (score 68, +1)

- [cosmetic] “create_test_outbound_mail” reworded the description of “mail_class”
- [cosmetic] “send_outbound_mail” reworded the description of “mail_class”

### 2026-07-28 (score 67, +1)

- [security regression] Stability: 0.03 → fail
- [security regression] A breaking change shipped without a version bump: still 1.0.1
- [security] Tool “get_facility_messages” rewrote its description, which is the text the model reads
- [security] Tool “list_facility_conversations” rewrote its description, which is the text the model reads
- [security] Tool “send_facility_message” rewrote its description, which is the text the model reads
- [functional regression] “send_facility_message” dropped the required parameter “facility_id”
- [functional regression] “get_facility_messages” dropped the required parameter “facility_id”

### 2026-07-27 (score 66, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 65)

First indexed and scored.

## MCP tools (30)

### `get_mailbox` (~75 tokens)

Get your agent's real mailing address beta endpoint when the account has explicit beta access: street address + mailbox number for approved accounts. For generally available inbound context, use list_inbound_forwarding_addresses instead; that returns a private intake alias for scans, PDFs, photos, provider notices, and notes from addresses the operator already uses.

Output parameters:

- `result` (object): Mailbox address, facility, and status details.

### `list_packages` (~176 tokens)

List inbound mail or packages for approved real mailing address/package beta accounts with optional filters by status, carrier, and date. Returns tracking number, carrier, status, and received timestamp where available. For generally available inbound postal context, use list_inbound_mail with forwarded scans/PDFs/notes instead.

Input parameters:

- `carrier` (string): Filter by shipping carrier.
- `limit` (number): Maximum number of packages to return (1-100). Defaults to 20.
- `offset` (number): Number of packages to skip for pagination. Defaults to 0.
- `since` (string): Only return packages received after this ISO 8601 date-time.
- `status` (string): Filter by package lifecycle status. "received" = just arrived, "stored" = in facility storage, "forwarded" = shipped to forwarding address.

Output parameters:

- `result` (array): Inbound package summaries.

### `get_package` (~52 tokens)

Get full package details including photos, tracking events, shipping label data (carrier, addresses, weight), forwarding status, storage location, and action history.

Input parameters:

- `package_id` (string, required): UUID of the package to retrieve.

Output parameters:

- `result` (object): Package details with photos, events, and extracted label data.

### `get_package_photos` (~106 tokens)

Get photos for a package with OCR-extracted text and confidence scores. Filter by photo type to get only exterior shots, label closeups, barcode scans, or content scans.

Input parameters:

- `package_id` (string, required): UUID of the package to get photos for.
- `photo_type` (string): Filter by photo type. "exterior" = package exterior, "label" = shipping label closeup, "barcode" = barcode scan, "content_scan" = opened package contents.

Output parameters:

- `result` (array): Package photo records with OCR metadata.

### `request_action` (~252 tokens)

Request a physical action on a package at the facility. Actions include forwarding to another address, shredding, scanning documents, holding for pickup, disposing, returning to sender, photographing, opening and scanning contents, or recording a video. Some actions (shred, dispose) are irreversible.

Input parameters:

- `action` (string, required): Action to perform. "forward" = ship to another address, "shred" = destroy (irreversible), "scan" = OCR document scan, "hold" = keep in storage, "dispose" = discard (irreversible), "return_to_sender"…
- `package_id` (string, required): UUID of the package to act on.
- `parameters` (object): Action-specific parameters. For "forward": { address, city, state, zip }. For "scan": { scan_type }. For "hold": { until_date }.
- `priority` (string): Processing priority. "urgent" = same-day processing, "high" = next business day, "normal" = standard queue, "low" = when convenient.

Output parameters:

- `result` (object): Created facility action request record.

### `request_scan` (~108 tokens)

Request document scanning (OCR + structured data extraction) for a package. The facility will scan the document and extract text, addresses, dates, and other structured data. Results are available via get_scan_results after processing.

Input parameters:

- `package_id` (string, required): UUID of the package to scan.
- `scan_type` (string): Type of scan. "label" = shipping label only, "envelope" = exterior envelope, "document" = full document OCR, "content" = opened package contents.

Output parameters:

- `result` (object): Created scan request record.

### `get_scan_results` (~57 tokens)

Get document scan results including raw OCR text, structured data fields (addresses, dates, amounts), and confidence scores. Returns empty if scan is still processing.

Input parameters:

- `package_id` (string, required): UUID of the package to get scan results for.

Output parameters:

- `result` (array): Document scan records and OCR results.

### `add_tag` (~81 tokens)

Add a tag/label to a package for categorization and filtering. Tags are free-form strings. Adding the same tag twice is a no-op.

Input parameters:

- `package_id` (string, required): UUID of the package to tag.
- `tag` (string, required): Tag name (e.g. "hardware-order", "urgent", "return-needed"). Free-form, case-sensitive.

Output parameters:

- `result` (object): Created or existing package tag record.

### `add_note` (~117 tokens)

Add an observation or context note to a package. Notes are visible to the facility operator and the renter. Use for recording decisions, observations, or agent reasoning.

Input parameters:

- `metadata` (object): Optional structured metadata attached to the note (e.g. { "rma_number": "4521", "vendor": "NVIDIA" }).
- `note` (string, required): Note text (e.g. "Appears to be the replacement GPU from RMA #4521").
- `package_id` (string, required): UUID of the package to annotate.

Output parameters:

- `result` (object): Created package note record.

### `create_rule` (~157 tokens)

Create a standing instruction that auto-triggers actions when incoming packages match conditions. Rules run on every new package and execute the specified action if all conditions match. Use requires_approval to add a human review step before execution.

Input parameters:

- `action_params` (object, required): Parameters for the action (e.g. forwarding address for "forward", scan_type for "scan").
- `action_type` (string, required): Action to auto-trigger when conditions match.
- `conditions` (object, required): Conditions that must ALL match for the rule to trigger.
- `name` (string, required): Human-readable rule name (e.g. "Forward Amazon packages", "Shred junk mail").
- `requires_approval` (boolean): If true, matched packages require human approval before the action executes.

Output parameters:

- `result` (object): Created standing rule record.

### `register_expected` (~172 tokens)

Pre-register an expected inbound shipment so it is auto-matched when it arrives at the facility. Optionally specify an action to auto-execute on arrival (e.g. forward immediately, scan on receipt).

Input parameters:

- `auto_action` (string): Action to auto-execute when the package arrives.
- `auto_action_params` (object): Parameters for the auto-action (e.g. forwarding address).
- `carrier` (string): Shipping carrier (e.g. "fedex", "ups", "usps").
- `description` (string): Human-readable description of the shipment (e.g. "Replacement laptop from Dell").
- `expected_by` (string): Expected arrival date in ISO 8601 format. Used for alerts if the package is late.
- `tracking_number` (string): Carrier tracking number for the expected shipment.

Output parameters:

- `result` (object): Created expected shipment record.

### `get_usage` (~143 tokens)

Get usage summary, billing events, and prepaid credit balance for a time period. Returns itemized events (scans, forwards, mail sends) with costs, period totals, and credits. Defaults to the current billing period if no dates are specified. Use this in Cursor/MCP chat when the human asks how many mailbox.bot credits are left; answer with the prepaid balance and explain that only the signed-in human can add funds.

Input parameters:

- `period_end` (string): End of the reporting period in ISO 8601 format. Defaults to now.
- `period_start` (string): Start of the reporting period in ISO 8601 format. Defaults to current billing period start.

Output parameters:

- `result` (object): Usage summary, billing events, and prepaid credit balance.

### `list_inbound_forwarding_addresses` (~122 tokens)

List the renter’s private inbound forwarding aliases on forward.mailbox.bot. These are the unique intake email addresses an operator, assistant, provider, or external agent can forward scans, PDFs, photos, provider notices, notes, and other context-aware documents to so mailbox.bot can build OCR-backed inbound context. Forwarding/emailing attachments here initiates OCR/extraction; this tool discovers the address and does not upload files directly into OCR. The alias is member-scoped, so live and sandbox agent keys for the same member resolve to the same intake address.

Output parameters:

- `result` (object): Private inbound forwarding email aliases.

### `list_inbound_mail` (~165 tokens)

List forwarded inbound mail items captured from private forwarding aliases. Default output includes compact draft_context so an LLM or external agent can reason about OCR context, reply contact candidates, deadlines, and thread linkage before generating outbound mail.

Input parameters:

- `category` (string): Optional category filter such as "Needs review" or "Loan / Mortgage".
- `include` (array): Optional expansions. Defaults to ["drafting"]. Add ocr/lineage only when deeper provenance is needed.
- `limit` (number): Maximum number of inbound items to return (1-100).
- `offset` (number): Number of inbound items to skip for pagination.
- `status` (string): Optional inbound status filter.
- `thread_id` (string): Only return inbound items linked to this postal mail thread.

Output parameters:

- `result` (object): Forwarded inbound mail items plus pagination.

### `get_inbound_mail` (~118 tokens)

Get one forwarded inbound mail item with compact draft_context by default. Use this before drafting an outbound reply when you need sender context, reply contact candidates, deadline clues, source files, and thread linkage in one stable payload.

Input parameters:

- `inbound_mail_id` (string, required): UUID of the inbound mail item to retrieve.
- `include` (array): Optional expansions. Defaults to ["drafting"]. Add signed_urls only when the agent truly needs temporary file access.
- `signed_urls` (boolean): If true, return short-lived signed URLs for stored files.

Output parameters:

- `result` (object): One forwarded inbound mail item.

### `list_postal_threads` (~115 tokens)

List physical-mail threads that group inbound mail context, human review, and outbound sends. Use this to understand which inbound items and outbound documents belong to the same business workflow.

Input parameters:

- `category` (string): Optional category filter.
- `include` (array): Optional expansions. Add events to include inbound/outbound timeline references.
- `limit` (number): Maximum number of threads to return (1-100).
- `offset` (number): Number of threads to skip for pagination.
- `status` (string): Optional thread status filter.

Output parameters:

- `result` (object): Postal mail workflow threads plus pagination.

### `get_postal_thread` (~75 tokens)

Get one physical-mail thread with optional timeline events. Use this to explain how a generated outbound mail piece relates back to prior inbound scans and review decisions.

Input parameters:

- `include` (array): Optional expansions. Add events to include inbound/outbound timeline references.
- `thread_id` (string, required): UUID of the postal mail thread to retrieve.

Output parameters:

- `result` (object): One postal mail workflow thread.

### `update_action` (~202 tokens)

Push notes, structured data, or a clarification response to an existing action request. Use this to add agent reasoning, attach extracted data, or respond when the facility asks for clarification. Requires mailbox_md_version to prove your MAILBOX.md instructions are in sync.

Input parameters:

- `action_id` (string, required): The action request ID to update.
- `agent_data` (object): Structured data to attach (e.g. OCR results, extracted fields, classification labels).
- `agent_notes` (string): Free-text notes from the agent (e.g. "Forwarding per standing rule #3").
- `decision_context` (object): Link this decision to a specific MAILBOX.md instruction for auditability.
- `mailbox_md_version` (number, required): Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification.
- `respond_to_clarification` (string): Response text when action status is needs_clarification. Providing this auto-resumes the action to in_progress.

Output parameters:

- `result` (object): Updated facility action request record.

### `get_mailbox_md` (~65 tokens)

Get the renter's MAILBOX.md standing instructions for this agent. Returns the full instruction text, version number, content hash, and last update timestamp. Call this on startup and cache the version — you must pass it to send_outbound_mail and update_action for sync verification.

Output parameters:

- `result` (object): Current MAILBOX.md standing instructions.

### `propose_mailbox_md_edit` (~124 tokens)

Propose changes to the renter's MAILBOX.md instructions with reasoning. The renter will see your suggestion in their dashboard and can accept, reject, or modify it. Use this when you observe patterns that could be codified into standing instructions.

Input parameters:

- `reason` (string, required): Why this change is suggested (e.g. "Observed 5 Amazon packages this week, all forwarded manually — adding auto-forward rule").
- `suggested_content` (string, required): Full proposed MAILBOX.md content (max 10,000 chars). Must include the complete document, not just the diff.

Output parameters:

- `result` (object): Created MAILBOX.md suggestion record.

### `send_facility_message` (~113 tokens)

Send a message to the Austin HQ operator managing your mailbox. Facility routing is automatic. Messages appear in the shared conversation visible to you, the renter, and the facility. Optionally link the message to a specific package or action request for context.

Input parameters:

- `action_request_id` (string): Optional: link this message to an action request for context.
- `body` (string, required): Message text (1-5000 characters).
- `package_id` (string): Optional: link this message to a specific package for context.

Output parameters:

- `result` (object): Sent facility message identifiers and body.

### `list_facility_conversations` (~72 tokens)

List your Austin HQ conversation with its unread message count and last message preview. Facility routing is automatic.

Input parameters:

- `limit` (number): Maximum number of conversations to return (1-100). Defaults to 20.
- `offset` (number): Number of conversations to skip for pagination. Defaults to 0.

Output parameters:

- `result` (object): Facility conversations plus pagination.

### `get_facility_messages` (~103 tokens)

Read the message thread with Austin HQ. Facility routing is automatic. Returns messages in reverse chronological order with sender role (member, facility, agent). Supports cursor-based pagination. Automatically marks facility messages as read.

Input parameters:

- `before` (string): Cursor: only return messages sent before this ISO 8601 timestamp. Use the oldest message timestamp from the previous page.
- `limit` (number): Maximum number of messages to return (1-100). Defaults to 50.

Output parameters:

- `result` (object): Messages exchanged with a facility.

### `update_webhook` (~135 tokens)

Configure webhook endpoint URL and event subscriptions for real-time notifications. Events include package.received, package.status_changed, action.completed, mail.status_changed, and more. The endpoint must use HTTPS and respond with 2xx within 10 seconds.

Input parameters:

- `enabled` (boolean): Set to false to pause webhook delivery without removing the URL.
- `event_types` (array): Array of event types to subscribe to (e.g. ["package.received", "mail.status_changed"]). Empty array disables all events.
- `webhook_url` (string): HTTPS URL to receive webhook POST requests. Must respond with 2xx within 10 seconds.

Output parameters:

- `result` (object): Webhook configuration status.

### `send_outbound_mail` (~1321 tokens)

Submit a document for printing and postal mailing by the facility. Supported formats: PDF, DOCX, JPG, PNG, TXT, CSV. The document is stored securely and printed by the facility operator. Published default pricing is $2.50 handling + $0.30/page B&W printing + carrier postage/rate; color is an additional $0.40/page, so color pages are $0.70/page before handling and postage. Plan/account overrides can apply; dry_run and cost_breakdown are authoritative. IMPORTANT: With a production key (sk_agent_), this spends the human member's prepaid mailbox.bot credits. Agents never access Stripe, card data, or Auto-Fill settings. If the signed-in human separately enabled Agent Auto-Fill, an eligible live order may trigger a bounded server-managed reload. Use dry_run=true to preview required credits before committing, or requires_approval=true to defer the credit debit until human approval. Sandbox keys (sk_agent_test_) skip credit debits and facility fulfillment. Responses include human_review with send-to address, return address, mail class, document details, preview URL when available, cost, safeguards, and next step; show that to the human before live funded sends. tracking_number is required for priority, certified, certified_return_receipt, FedEx, and UPS mail classes. USPS first_class does not include carrier tracking by default; tracking_number may be null. Optionally attach the outbound mail to inbound context with inbound_capture_id and postal_mail_thread_id so lineage stays explicit. Explicit Business mail runs are REST-only.

Input parameters:

- `agent_notes` (string): Instructions for the facility operator (e.g. "Time-sensitive — mail today").
- `color` (boolean): Print in color. Adds $0.40/page to the default $0.30/page B&W printing rate, making color pages $0.70/page before handling and postage. Account overrides can apply; cost_breakdown is authoritative.
- `document_base64` (string, required): Base64-encoded document file. Supported formats: PDF, DOCX, JPG, PNG, TXT, CSV. Max 10MB decoded.
- `document_filename` (string): Original filename with extension (e.g. "letter.docx"). Required for reliable non-PDF format detection.
- `dry_run` (boolean): Validate inputs and return cost breakdown without creating a record or spending credits. Use to preview required credits before committing.
- `duplex` (boolean): Request double-sided printing when operationally possible. Pricing and page_count are based on the detected or supplied document page count; use dry_run=true to preview exact cost.
- `inbound_capture_id` (string): Optional inbound mail item this outbound piece is replying to. Recommended when drafting from OCR/forwarded-mail context.
- `mail_class` (string): Postal or carrier service. Do not infer speed, tracking, or proof from carrier marketing names. Use first_class for ordinary lowest-cost USPS letters with no carrier tracking number by default. Use p…
- `mailbox_md_version` (number, required): Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification.
- `max_cost_cents` (integer): Cost cap in cents. If the calculated cost exceeds this, the request is rejected with 422 before credits are spent. Prevents accidental expensive mailings.
- `metadata` (object): Arbitrary key-value pairs echoed in GET responses and webhooks. Recommended convention: { "workflow_id": "wf_123", "reason": "Customer cancellation", "correlation_id": "abc" }.
- `package_id` (string): Link this mail to an inbound package (e.g. replying to received correspondence).
- `page_count` (number): Explicit page count for non-PDF documents when exact pagination is known. When supplied for DOCX, TXT, or CSV, it overrides local detection and makes pricing deterministic.
- `postal_mail_thread_id` (string): Optional physical-mail thread to attach this outbound mail to. Lets agents keep inbound and outbound activity in one durable workflow.
- `recipient_city` (string, required): Recipient city.
- `recipient_company` (string): Company or organization line for the recipient. Optional when recipient_name is provided.
- `recipient_country` (string): ISO 3166-1 alpha-2 country code. Defaults to "US".
- `recipient_line1` (string, required): Street address line 1 of the recipient.
- `recipient_line2` (string): Street address line 2 (apartment, suite, unit, etc.).
- `recipient_name` (string): Person name of the mail recipient. Optional when recipient_company is provided.
- `recipient_state` (string, required): 2-letter US state code (e.g. CA, NY, TX).
- `recipient_zip` (string, required): 5 or 5+4 digit ZIP code (e.g. "90210" or "90210-1234").
- `requires_approval` (boolean): If true, the renter must approve in their dashboard before the mail is printed and sent.
- `return_city` (string): Return address city. Defaults to member profile if omitted.
- `return_company` (string): Optional company or organization line for the return address.
- `return_line1` (string): Return address line 1. Defaults to member profile if omitted.
- `return_line2` (string): Return address line 2 (suite, unit, etc.).
- `return_name` (string): Return address name. Defaults to the member's profile name if omitted.
- `return_state` (string): Return address state (2-letter code). Defaults to member profile if omitted.
- `return_zip` (string): Return address ZIP code. Defaults to member profile if omitted.

Output parameters:

- `result` (object): Submitted outbound mail job or dry-run cost preview.

### `list_outbound_mail` (~300 tokens)

List outbound mail jobs with status tracking. Returns mail ID, recipient, mail class, status, cost, timestamps, and failure metadata. Filter by status, created_at date range, or search recipient/address/tracking/agent notes.

Input parameters:

- `created_after` (string): Filter mail created at or after this ISO 8601 datetime or YYYY-MM-DD date.
- `created_before` (string): Filter mail created at or before this ISO 8601 datetime or YYYY-MM-DD date. Date-only values include the whole UTC day.
- `limit` (number): Maximum number of mail jobs to return (1-100). Defaults to 20.
- `offset` (number): Number of mail jobs to skip for pagination. Defaults to 0.
- `q` (string): Search recipient name, address lines, city/state/ZIP, tracking number, or agent notes.
- `status` (string): Filter by mail status. "pending_approval" = awaiting human approval, "submitted" = queued for facility, "ready" = printed and ready to mail, "mailed" = in transit, "delivered" = confirmed delivery, "…
- `test_mode` (boolean): Filter sandbox/test records. Defaults to the key environment for agent-scoped keys; member keys can pass true or false explicitly.

Output parameters:

- `result` (array): Outbound mail job summaries.

### `get_outbound_mail` (~84 tokens)

Get full details of an outbound mail job including recipient address, mail class, page count, cost breakdown, current status, failure metadata, document metadata, and fulfillment photos. Legacy plaintext records may include direct document URLs; encrypted source documents are retrieved through the REST document endpoint with document.read scope.

Input parameters:

- `mail_id` (string, required): UUID of the outbound mail job to retrieve.

Output parameters:

- `result` (object): Full outbound mail job details. Direct document URLs are only present for legacy plaintext rows.

### `cancel_outbound_mail` (~111 tokens)

Cancel a queued outbound mail job before facility printing starts. If the mail was funded with prepaid credits, eligible credits are returned to the member ledger. Safe to retry: already-cancelled mail returns cancelled status without creating a duplicate refund. In chat, report cancellation status, returned credits, updated balance, and whether it had already been cancelled. If a transient error occurs, poll the mail status and credits before retrying.

Input parameters:

- `mail_id` (string, required): UUID of the queued outbound mail job to cancel.

Output parameters:

- `result` (object): Cancelled queued outbound mail and returned credits when eligible.

### `create_test_outbound_mail` (~537 tokens)

Create a sandbox outbound mail record without uploading a real document. The record is always test_mode=true, cost_cents=0, includes estimated_live_cost_cents and cost_breakdown, and queues a mail.submitted webhook. Published default pricing is $0.30/page B&W printing; color adds $0.40/page ($0.70/page total before handling and postage). FedEx and UPS estimates use the same configured origin and destination zone/region logic as production. Use with a sandbox key to rehearse outbound workflows before sending real physical mail.

Input parameters:

- `agent_notes` (string): Optional facility/operator notes for the simulated mailpiece.
- `color` (boolean): Whether to include the additional $0.40/page color-print surcharge in the live estimate ($0.70/page total before handling and postage by default).
- `mail_class` (string): Mail class to simulate. Postal or carrier service. Do not infer speed, tracking, or proof from carrier marketing names. Use first_class for ordinary lowest-cost USPS letters with no carrier tracking…
- `metadata` (object): Arbitrary metadata echoed in responses and webhooks.
- `page_count` (number): Simulated page count used for pricing.
- `recipient_city` (string): Recipient city.
- `recipient_company` (string): Company or organization line for the simulated mailpiece. Optional when recipient_name is provided.
- `recipient_line1` (string): Recipient street line 1.
- `recipient_name` (string): Recipient name for the simulated mailpiece. Optional when recipient_company is provided.
- `recipient_state` (string): Recipient 2-letter state code.
- `recipient_zip` (string): Recipient ZIP code. Affects estimated live postage, private-carrier zone, and FedEx local/regional/national area.

Output parameters:

- `result` (object): Created sandbox outbound mail job and webhook status.

### `advance_test_outbound_mail` (~80 tokens)

Advance a test_mode outbound mail record one lifecycle step and queue the matching webhook. submitted becomes ready with simulated pages/envelope photos; ready becomes mailed with carrier, dispatch method, receipt photo, and tracking when the selected service includes tracking; mailed becomes delivered.

Input parameters:

- `mail_id` (string, required): UUID of the test_mode outbound mail record to advance.

Output parameters:

- `result` (object): Advanced sandbox outbound mail job and webhook status.

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/bot-mailbox-mailbox/api-mcp#diagnostics

## Score history

- 2026-08-03: 75
- 2026-08-02: 75
- 2026-08-01: 74
- 2026-07-31: 74
- 2026-07-30: 69
- 2026-07-29: 68
- 2026-07-28: 67
- 2026-07-27: 66
- 2026-07-26: 65

## Links

- Remote endpoint: https://mailbox.bot/api/mcp
- Authorisation metadata: https://mailbox.bot/.well-known/oauth-protected-resource/api/mcp
- Website: https://mailbox.bot/mcp-install
- Changelog RSS feed: https://verifymcp.io/servers/bot-mailbox-mailbox/api-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/bot-mailbox-mailbox/api-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/bot-mailbox-mailbox/api-mcp