mailbox.bot

arbengine/mailbox-mcp

Turns your physical mailbox into an API endpoint with 29 tools spanning inbound scans, outbound mail dispatch, package tracking, and facility messaging. Forward mail to your private alias at forward.mailbox.bot for OCR extraction, then use get_inbound_mail to pull draft_context into your LLM and send_outbound_mail to generate certified letters or replies. Sandbox keys let you test the full loop before committing to live postage. The hosted endpoint speaks streamable HTTP, so no local bridge needed unless your client demands it. Reach for this when your agent needs to handle lease notices, permit applications, or any workflow where the other party only speaks envelopes and stamps.

GitHub stars: 2
tools: 55
auth: Secret needed
transport: HTTP
last updated: Oct 22, 2026

View on GitHub

Install

From registry metadata

$ npx add-mcp https://mailbox.bot/api/mcp --name mailbox --header 'Authorization: Bearer ${API_TOKEN}'

Run in your terminal. add-mcp asks which agents to add it to, then asks for each value it needs. Add -g to install it for every project.

Review the command, arguments and environment values before installing. MCP servers run with your local permissions.

Other ways

Claude Code

$ claude mcp add --transport http mailbox https://mailbox.bot/api/mcp --header 'Authorization: YOUR_AUTHORIZATION'

Run in your terminal. Add --scope user to make it available in every project.

Tools

Verified live · 55 tools

Verified live against the running server on Nov 6, 2026.

get_mailboxGet your agent's real mailing address: street address + mailbox number (PMB) at the Manhattan Beach, CA facility. The PMB number is assigned after USPS Form 1583 verification. For inbound context from addresses the operator already uses, use list_inbound_forwarding_addresses i...

Get your agent's real mailing address: street address + mailbox number (PMB) at the Manhattan Beach, CA facility. The PMB number is assigned after USPS Form 1583 verification. For inbound context from addresses the operator already uses, use list_inbound_forwarding_addresses i...

No parameters. Call it with no arguments.

get_usageGet 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...2 params

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...

Parameters* required

period_endstring

End of the reporting period in ISO 8601 format. Defaults to now.

period_startstring

Start of the reporting period in ISO 8601 format. Defaults to current billing period start.

list_inbound_forwarding_addressesList 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 mailbo...

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 mailbo...

No parameters. Call it with no arguments.

list_inbound_mailList 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.6 params

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.

Parameters* required

categorystring

Optional category filter such as "Needs review" or "Loan / Mortgage".

includearray

Optional expansions. Defaults to ["drafting"]. Add ocr/lineage only when deeper provenance is needed.

limitnumber

Maximum number of inbound items to return (1-100).default: 20

offsetnumber

Number of inbound items to skip for pagination.default: 0

statusstring

Optional inbound status filter.one of captured · stored · extracted · needs_review · failed

thread_idstring

Only return inbound items linked to this postal mail thread.

get_inbound_mailGet 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.3 params

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.

Parameters* required

inbound_mail_id*string

UUID of the inbound mail item to retrieve.

includearray

Optional expansions. Defaults to ["drafting"]. Add signed_urls only when the agent truly needs temporary file access.

signed_urlsboolean

If true, return short-lived signed URLs for stored files.default: false

list_postal_threadsList 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.5 params

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.

Parameters* required

categorystring

Optional category filter.

includearray

Optional expansions. Add events to include inbound/outbound timeline references.

limitnumber

Maximum number of threads to return (1-100).default: 20

offsetnumber

Number of threads to skip for pagination.default: 0

statusstring

Optional thread status filter.one of open · waiting · closed · archived

get_postal_threadGet 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.2 params

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.

Parameters* required

includearray

Optional expansions. Add events to include inbound/outbound timeline references.

thread_id*string

UUID of the postal mail thread to retrieve.

get_mailbox_mdGet 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 for sync verification.

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 for sync verification.

No parameters. Call it with no arguments.

propose_mailbox_md_editPropose 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.2 params

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.

Parameters* required

reason*string

Why this change is suggested (e.g. "Observed 5 Amazon packages this week, all forwarded manually — adding auto-forward rule").

suggested_content*string

Full proposed MAILBOX.md content (max 10,000 chars). Must include the complete document, not just the diff.

send_facility_messageSend a message to the operator at your mailbox facility. 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.3 params

Send a message to the operator at your mailbox facility. 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.

Parameters* required

action_request_idstring

Optional: link this message to an action request for context.

body*string

Message text (1-5000 characters).

package_idstring

Optional: link this message to a specific package for context.

list_facility_conversationsList your conversation with your mailbox facility, including its unread message count and last message preview. Facility routing is automatic.2 params

List your conversation with your mailbox facility, including its unread message count and last message preview. Facility routing is automatic.

Parameters* required

limitnumber

Maximum number of conversations to return (1-100). Defaults to 20.default: 20

offsetnumber

Number of conversations to skip for pagination. Defaults to 0.default: 0

get_facility_messagesRead the message thread with your mailbox facility. 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.2 params

Read the message thread with your mailbox facility. 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.

Parameters* required

beforestring

Cursor: only return messages sent before this ISO 8601 timestamp. Use the oldest message timestamp from the previous page.

limitnumber

Maximum number of messages to return (1-100). Defaults to 50.default: 50

update_webhookConfigure webhook endpoint URL and event subscriptions for real-time notifications. Outbound events are mail.pending_approval, mail.submitted, mail.ready, mail.mailed, mail.delivered, mail.failed, and mail.cancelled. Canonical physical-custody events are inbound.received and i...3 params

Configure webhook endpoint URL and event subscriptions for real-time notifications. Outbound events are mail.pending_approval, mail.submitted, mail.ready, mail.mailed, mail.delivered, mail.failed, and mail.cancelled. Canonical physical-custody events are inbound.received and i...

Parameters* required

enabledboolean

Set to false to pause webhook delivery without removing the URL.

event_typesarray

Array of event types to subscribe to (e.g. ["mail.mailed", "inbound.received"]). Empty array disables all events.

webhook_urlstring

HTTPS URL to receive webhook POST requests. Must respond with 2xx within 10 seconds.

send_outbound_mailSubmit 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. USPS First-Class Mail has a published $2.00 one-page baseline. Extra pages add configured...31 params

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. USPS First-Class Mail has a published $2.00 one-page baseline. Extra pages add configured...

Parameters* required

agent_notesstring

Instructions for the facility operator (e.g. "Time-sensitive — mail today").

colorboolean

Color pages cost $0.70/page total by default before handling and postage: $0.40/page base B&W printing plus a $0.30/page additive color upgrade. In cost_breakdown, color_printing_per_page_cents is...default: false

delivery_signaturestring

Optional signature on delivery for a single letter (batch mail has none). FedEx classes: indirect (FedEx Indirect Signature Required, $8.00: someone at the address, a neighbor, or the recipient on...one of none · indirect · direct · adult · restricted

document_base64*string

Base64-encoded document file. Supported formats: PDF, DOCX, JPG, PNG, TXT, CSV. Max 10MB decoded.

document_filenamestring

Original filename with extension (e.g. "letter.docx"). Required for reliable non-PDF format detection.

dry_runboolean

Validate inputs and return cost breakdown without creating a record or spending credits. Use to preview required credits before committing.default: false

duplexboolean

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.default: false

inbound_capture_idstring

Optional inbound mail item this outbound piece is replying to. Recommended when drafting from OCR/forwarded-mail context.

mail_classstring

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. USP...one of first_class · priority · certified · certified_return_receipt · fedex_ground · fedex_expressdefault: first_class

mailbox_md_version*number

Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification.

max_cost_centsinteger

Cost cap in cents. If the calculated cost exceeds this, the request is rejected with 422 before credits are spent. Prevents accidental expensive mailings.

metadataobject

Arbitrary key-value pairs echoed in GET responses and webhooks. Recommended convention: { "workflow_id": "wf_123", "reason": "Customer cancellation", "correlation_id": "abc" }.

package_idstring

Link this mail to an inbound package (e.g. replying to received correspondence).

page_countnumber

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_idstring

Optional physical-mail thread to attach this outbound mail to. Lets agents keep inbound and outbound activity in one durable workflow.

recipient_city*string

Recipient city.

recipient_companystring

Company or organization line for the recipient. Optional when recipient_name is provided.

recipient_countrystring

ISO 3166-1 alpha-2 country code. Defaults to "US".default: US

recipient_line1*string

Street address line 1 of the recipient.

recipient_line2string

Street address line 2 (apartment, suite, unit, etc.).

+11 more parameters. See the server's own documentation for the full schema.

list_outbound_mailList 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.7 params

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.

Parameters* required

created_afterstring

Filter mail created at or after this ISO 8601 datetime or YYYY-MM-DD date.

created_beforestring

Filter mail created at or before this ISO 8601 datetime or YYYY-MM-DD date. Date-only values include the whole UTC day.

limitnumber

Maximum number of mail jobs to return (1-100). Defaults to 20.default: 20

offsetnumber

Number of mail jobs to skip for pagination. Defaults to 0.default: 0

qstring

Search recipient name, address lines, city/state/ZIP, tracking number, or agent notes.

statusstring

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,...one of pending_approval · submitted · ready · mailed · delivered · failed

test_modeboolean

Filter sandbox/test records. Defaults to the key environment for agent-scoped keys; member keys can pass true or false explicitly.

get_outbound_mailGet 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...1 params

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...

Parameters* required

mail_id*string

UUID of the outbound mail job to retrieve.

cancel_outbound_mailCancel 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, repo...1 params

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, repo...

Parameters* required

mail_id*string

UUID of the queued outbound mail job to cancel.

create_test_outbound_mailCreate 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. USPS First-Class Mail has a published $2.00 one-page baseline...12 params

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. USPS First-Class Mail has a published $2.00 one-page baseline...

Parameters* required

agent_notesstring

Optional facility/operator notes for the simulated mailpiece.

colorboolean

delivery_signaturestring

mail_classstring

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 trackin...one of first_class · priority · certified · certified_return_receipt · fedex_ground · fedex_expressdefault: first_class

metadataobject

Arbitrary metadata echoed in responses and webhooks.

page_countnumber

Simulated page count used for pricing.default: 1

recipient_citystring

Recipient city.default: San Francisco

recipient_companystring

Company or organization line for the simulated mailpiece. Optional when recipient_name is provided.

recipient_line1string

Recipient street line 1.default: 123 Test Street

recipient_namestring

Recipient name for the simulated mailpiece. Optional when recipient_company is provided.default: Test Recipient

recipient_statestring

Recipient 2-letter state code.default: CA

recipient_zipstring

Recipient ZIP code. Affects estimated live postage, private-carrier zone, and FedEx local/regional/national area.default: 94105

advance_test_outbound_mailAdvance 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...1 params

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...

Parameters* required

mail_id*string

UUID of the test_mode outbound mail record to advance.

list_agent_inboxDeprecated: use search_inbound_items. Still served unchanged during the alias window. List/search current assigned postal mail using the same /v1/agent-inbox service. q is literal AND search of IDs, stored metadata and authorized stored OCR (NFKC/lowercase, max 200 characters...5 params

Deprecated: use search_inbound_items. Still served unchanged during the alias window. List/search current assigned postal mail using the same /v1/agent-inbox service. q is literal AND search of IDs, stored metadata and authorized stored OCR (NFKC/lowercase, max 200 characters...

Parameters* required

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

qstring

Literal AND search: every term (max 12, 200 characters, NFKC-normalized and lowercased) must appear in the reference, the sender line or the OCR text of a readable page. Not fuzzy; punctuation is l...

received_afterstring

Inclusive intake time (ISO 8601 with offset): when the facility logged the item, never a printed date.

received_beforestring

Exclusive intake time (ISO 8601 with offset); must be after received_after.

get_agent_inbox_contextDeprecated: use get_inbound_item. Still served unchanged during the alias window. Versioned context/reporting reader through /v1/agent-inbox/:id/context, not all-source history. For OCR matching indexed search, use get_agent_inbox_sources after its rollout. Member-sample conte...1 params

Deprecated: use get_inbound_item. Still served unchanged during the alias window. Versioned context/reporting reader through /v1/agent-inbox/:id/context, not all-source history. For OCR matching indexed search, use get_agent_inbox_sources after its rollout. Member-sample conte...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

get_agent_inbox_sourcesDeprecated: use get_inbound_item. Still served unchanged during the alias window. Primary OCR read after list_agent_inbox: GET /v1/agent-inbox/:id/sources. Requires assigned-inbox and indexed-source reads enabled for the account, plus agent.inbox.read + agent.read. After index...3 params

Deprecated: use get_inbound_item. Still served unchanged during the alias window. Primary OCR read after list_agent_inbox: GET /v1/agent-inbox/:id/sources. Requires assigned-inbox and indexed-source reads enabled for the account, plus agent.inbox.read + agent.read. After index...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

list_agent_inbox_scansDeprecated: use get_inbound_pages. Still served unchanged during the alias window. List/search completed facility-captured scan jobs for this assigned member sample through /v1/agent-inbox/:id/scans. Sandbox agent key only, with both read scopes even without q. q is literal AN...4 params

Deprecated: use get_inbound_pages. Still served unchanged during the alias window. List/search completed facility-captured scan jobs for this assigned member sample through /v1/agent-inbox/:id/scans. Sandbox agent key only, with both read scopes even without q. q is literal AN...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

qstring

get_agent_inbox_scanDeprecated: use get_inbound_pages. Still served unchanged during the alias window. Read one exact completed facility capture and its saved page OCR through /v1/agent-inbox/:id/scans/:operationId. Sandbox agent key assigned to the member sample only. Use request_id from list_ag...2 params

Deprecated: use get_inbound_pages. Still served unchanged during the alias window. Read one exact completed facility capture and its saved page OCR through /v1/agent-inbox/:id/scans/:operationId. Sandbox agent key assigned to the member sample only. Use request_id from list_ag...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

request_id*string

Captured-scan request id from list_agent_inbox_scans.

get_agent_inbox_activityDeprecated: use get_inbound_activity. Still served unchanged during the alias window. Read current authorized inbox retrieval receipts and agent-reported outcomes through /v1/agent-inbox/activity. Optional item_id filters one item; needs agent.inbox.read. Sample activity also...2 params

Deprecated: use get_inbound_activity. Still served unchanged during the alias window. Read current authorized inbox retrieval receipts and agent-reported outcomes through /v1/agent-inbox/activity. Optional item_id filters one item; needs agent.inbox.read. Sample activity also...

Parameters* required

item_idstring

Optional inbound item id (UUID); narrows the timeline to one item.

limitinteger

Page size, 1–50 (default 25).default: 25

report_agent_inbox_outcomeDeprecated: no successor; retired when the alias window closes. Still served unchanged until then. Report actual external-worker processing through /v1/agent-inbox/:id/acknowledgments. Send the exact fetched context_version, outcome and non-sensitive run_id in request. Needs a...3 params

Deprecated: no successor; retired when the alias window closes. Still served unchanged until then. Report actual external-worker processing through /v1/agent-inbox/:id/acknowledgments. Send the exact fetched context_version, outcome and non-sensitive run_id in request. Needs a...

Parameters* required

idempotency_key*string

Caller-generated replay key (8–200 visible ASCII characters) for this one intent. The same key with the same input replays the stored result; the same key with different input is refused.

item_id*string

Inbound item id (UUID) from a list or search result.

request*object

Outcome report: context_version from get_agent_inbox_context, outcome (processed, needs_review or failed) and your run_id.

get_agent_inbox_handlingDeprecated: use get_inbound_item. Still served unchanged during the alias window. Read /v1/agent-inbox/:id/handling capabilities, version and history. Gated private-mail Live and member-sample Sandbox workflow only; no generated fixtures or managed-PMB fallback. Server chooses...1 params

Deprecated: use get_inbound_item. Still served unchanged during the alias window. Read /v1/agent-inbox/:id/handling capabilities, version and history. Gated private-mail Live and member-sample Sandbox workflow only; no generated fixtures or managed-PMB fallback. Server chooses...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

propose_agent_inbox_handlingDeprecated: use request_inbound_action. Still served unchanged during the alias window. Propose through /v1/agent-inbox/:id/handling with dedicated agent.inbox.propose and read scopes. Request confirmed:false and destructive_confirmed:false; humans approve before the paired fa...3 params

Deprecated: use request_inbound_action. Still served unchanged during the alias window. Propose through /v1/agent-inbox/:id/handling with dedicated agent.inbox.propose and read scopes. Request confirmed:false and destructive_confirmed:false; humans approve before the paired fa...

Parameters* required

idempotency_key*string

Caller-generated replay key (8–200 visible ASCII characters) for this one intent. The same key with the same input replays the stored result; the same key with different input is refused.

item_id*string

Inbound item id (UUID) from a list or search result.

request*value

Handling proposal: action_type open_and_scan, forward_original (with destination; mail_class defaults to priority and first_class needs untracked_acknowledged) or discard_original, with the item's...

seed_agent_inbox_sandboxDeprecated: no successor; retired when the alias window closes. Still served unchanged until then. Explicitly seed an isolated provider-free two_page_letter or needs_review fixture through /v1/agent-inbox/sandbox/seed. Sandbox agent key only. Exact retry key/scenario reuses th...2 params

Deprecated: no successor; retired when the alias window closes. Still served unchanged until then. Explicitly seed an isolated provider-free two_page_letter or needs_review fixture through /v1/agent-inbox/sandbox/seed. Sandbox agent key only. Exact retry key/scenario reuses th...

Parameters* required

idempotency_key*string

Caller-generated replay key (8–200 visible ASCII characters) for this one intent. The same key with the same input replays the stored result; the same key with different input is refused.

scenario*string

Fixture to seed: two_page_letter or needs_review. Sandbox agent keys only; the same key and scenario reuse the fixture.one of two_page_letter · needs_review

list_webhook_endpointsList the member's webhooks (name, URL, events, keyword rules, status), without secrets. Legacy agent callback settings are separate. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/Live-Sandbox authorization as /api/v1/webhooks/endpoints. Reuse th...

List the member's webhooks (name, URL, events, keyword rules, status), without secrets. Legacy agent callback settings are separate. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/Live-Sandbox authorization as /api/v1/webhooks/endpoints. Reuse th...

No parameters. Call it with no arguments.

create_webhook_endpointCreate a webhook: name, public HTTPS URL, events (inbound.received, inbound.action.requested, inbound.action.completed, inbound.pages_ready, inbound.keywords_matched) and optional keyword rules (literal terms, any/all, exclusions). Active on save. Returns the whsec_ signing se...7 params

Create a webhook: name, public HTTPS URL, events (inbound.received, inbound.action.requested, inbound.action.completed, inbound.pages_ready, inbound.keywords_matched) and optional keyword rules (literal terms, any/all, exclusions). Active on save. Returns the whsec_ signing se...

Parameters* required

agent_id*value

Agent keys: your own agent id. Member keys: an agent id, or null for account scope.

environment*string

live or test. Agent keys must use their own environment; an endpoint only receives events from its environment.one of live · test

event_types*array

Events to deliver (1–32, unique). Inbound mail: inbound.received, inbound.action.requested, inbound.action.completed, inbound.pages_ready, inbound.keywords_matched. Outbound mail: mail.pending_appr...

idempotency_key*string

A new UUID for this one intent; reuse it only to retry the identical request.

name*string

Label shown in the dashboard and delivery log.

rules*array

Up to 10 keyword rules, each with a unique id: source (envelope, letter for the contents, or any), match (any or all), 1–20 terms and optional exclude_terms. inbound.keywords_matched fires when a r...

url*string

Public HTTPS URL on port 443 (no credentials, fragment or private host) that receives the signed POSTs. Set or change it only on the operator's explicit instruction.

update_webhook_endpointUpdate name, URL, events, keyword rules or active/paused status with expected_revision. Do not redirect notifications without the operator's authorization. Agent/environment scope cannot be changed. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/...8 params

Update name, URL, events, keyword rules or active/paused status with expected_revision. Do not redirect notifications without the operator's authorization. Agent/environment scope cannot be changed. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/...

Parameters* required

endpoint_id*string

Webhook endpoint id (UUID) from list_webhook_endpoints.

event_typesarray

expected_revision*integer

The endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten.

idempotency_key*string

A new UUID for this one intent; reuse it only to retry the identical request.

namestring

Label shown in the dashboard and delivery log. Omit to keep the current value.

rulesarray

statusstring

active or paused. Omit to keep the current value.one of active · paused

urlstring

Public HTTPS URL on port 443 (no credentials, fragment or private host) that receives the signed POSTs. Set or change it only on the operator's explicit instruction. Omit to keep the current value.

test_webhook_endpointQueue a synthetic webhook.test delivery (no item) to check the receiver and its signature verification. Queue admission is not HTTP delivery; inspect list_webhook_deliveries. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/Live-Sandbox authorizati...3 params

Queue a synthetic webhook.test delivery (no item) to check the receiver and its signature verification. Queue admission is not HTTP delivery; inspect list_webhook_deliveries. Requires webhook.manage. Uses the same bounded control plane and tenant/agent/Live-Sandbox authorizati...

Parameters* required

endpoint_id*string

Webhook endpoint id (UUID) from list_webhook_endpoints.

expected_revision*integer

The endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten.

idempotency_key*string

A new UUID for this one intent; reuse it only to retry the identical request.

test_webhook_endpoint_with_sampleRun the Sample test: opens and scans the member's Mojave sample letter if needed (free, fictional), delivers its real inbound.pages_ready / inbound.keywords_matched events to this webhook, and returns a verdict computed from the receiver's actual HTTP result plus a next step....3 params

Run the Sample test: opens and scans the member's Mojave sample letter if needed (free, fictional), delivers its real inbound.pages_ready / inbound.keywords_matched events to this webhook, and returns a verdict computed from the receiver's actual HTTP result plus a next step....

Parameters* required

endpoint_id*string

Webhook endpoint id (UUID) from list_webhook_endpoints.

expected_revision*integer

The endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten.

idempotency_key*string

A new UUID for this one intent; reuse it only to retry the identical request.

rotate_webhook_endpoint_secretRotate the signing secret only with explicit operator authorization and confirm_rotation:true. Old signatures overlap for 24 hours; update the receiver's secure secret configuration. Never expose either secret in logs or prompts. Requires webhook.manage. Uses the same bounded...4 params

Rotate the signing secret only with explicit operator authorization and confirm_rotation:true. Old signatures overlap for 24 hours; update the receiver's secure secret configuration. Never expose either secret in logs or prompts. Requires webhook.manage. Uses the same bounded...

Parameters* required

confirm_rotation*boolean

Must be true, and only with the operator's explicit authorization. The old secret keeps verifying for 24 hours.

endpoint_id*string

Webhook endpoint id (UUID) from list_webhook_endpoints.

expected_revision*integer

The endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten.

idempotency_key*string

A new UUID for this one intent; reuse it only to retry the identical request.

list_webhook_deliveriesRead the latest 50 deliveries and their exact JSON payloads (identifiers, sender line, dates, matched terms; never page text) for one webhook. HTTP 2xx delivered means receipt, not external-agent processing. No signing secrets or receiver response body. Requires webhook.manage...1 params

Read the latest 50 deliveries and their exact JSON payloads (identifiers, sender line, dates, matched terms; never page text) for one webhook. HTTP 2xx delivered means receipt, not external-agent processing. No signing secrets or receiver response body. Requires webhook.manage...

Parameters* required

endpoint_id*string

Webhook endpoint id (UUID) from list_webhook_endpoints.

replay_webhook_deliveryExplicitly retry a failed delivery after correcting the receiver. Preserves event_id for deduplication and rechecks the current endpoint revision. Does not replay successful deliveries or approve facility handling. Requires webhook.manage. Uses the same bounded control plane a...4 params

Explicitly retry a failed delivery after correcting the receiver. Preserves event_id for deduplication and rechecks the current endpoint revision. Does not replay successful deliveries or approve facility handling. Requires webhook.manage. Uses the same bounded control plane a...

Parameters* required

delivery_id*string

A failed delivery's id from list_webhook_deliveries; successful deliveries are not replayed.

endpoint_id*string

Webhook endpoint id (UUID) from list_webhook_endpoints.

expected_revision*integer

The endpoint's current revision from list_webhook_endpoints; a stale revision is refused so concurrent edits are never overwritten.

idempotency_key*string

A new UUID for this one intent; reuse it only to retry the identical request.

list_inbound_itemsDeprecated: use search_inbound_items. Still served unchanged during the alias window. Search managed-renter physical mail through GET /v1/inbound-items?search_mode=documents. q uses literal AND terms across authorized saved metadata, exterior OCR and completed requested inside...7 params

Deprecated: use search_inbound_items. Still served unchanged during the alias window. Search managed-renter physical mail through GET /v1/inbound-items?search_mode=documents. q uses literal AND terms across authorized saved metadata, exterior OCR and completed requested inside...

Parameters* required

kindstring

Only items of this kind.one of letter · flat · parcel

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

qstring

Literal AND search of authorized saved metadata and OCR; NFKC/lowercase, at most 200 characters and 12 terms. No fuzzy search or new extraction.

received_afterstring

Inclusive canonical intake time (RFC3339 with timezone, up to six fractional-second digits); not a date printed in a letter.

received_beforestring

Exclusive canonical intake time (RFC3339 with timezone, up to six fractional-second digits); not a date inferred from OCR.

statusstring

Only items in this custody status.one of received · stored · held · forwarding · forwarded · returning

get_inbound_item_sourcesDeprecated: use get_inbound_item. Still served unchanged during the alias window. Read saved exterior and authorized completed inside-page evidence through GET /v1/inbound-items/:id/sources. Group by item.id/reference_code and owner mailbox, then request_id/bundle_id, then pag...3 params

Deprecated: use get_inbound_item. Still served unchanged during the alias window. Read saved exterior and authorized completed inside-page evidence through GET /v1/inbound-items/:id/sources. Group by item.id/reference_code and owner mailbox, then request_id/bundle_id, then pag...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

search_inbound_itemsList and search inbound mail through GET /v1/inbound-items, the same list and search the dashboard shows: newest first, with public status, kind (letter | package), the sender line as read from the envelope, the envelope page and any open action. q is a literal AND search (max...7 params

List and search inbound mail through GET /v1/inbound-items, the same list and search the dashboard shows: newest first, with public status, kind (letter | package), the sender line as read from the envelope, the envelope page and any open action. q is a literal AND search (max...

Parameters* required

kindstring

letter or package.one of letter · package

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

qstring

received_afterstring

Inclusive intake time (ISO 8601 with offset): when the facility logged the item, never a printed date.

received_beforestring

Exclusive intake time (ISO 8601 with offset); must be after received_after.

statusstring

Only items in this public status.one of draft · received · action_requested · in_progress · scanned · forwarded

get_inbound_itemRead one inbound item through GET /v1/inbound-items/:id: canonical status, sender (staff-entered or exterior OCR guess), mailbox PMB, assigned agent, every saved page (exterior, interior, evidence) with OCR status and text when ready, the full action history, and current scan/...2 params

Read one inbound item through GET /v1/inbound-items/:id: canonical status, sender (staff-entered or exterior OCR guess), mailbox PMB, assigned agent, every saved page (exterior, interior, evidence) with OCR status and text when ready, the full action history, and current scan/...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

signed_urlsboolean

true adds one-hour page image URLs on live keys; sandbox keys always get url: null.

get_inbound_pagesRead an item's scanned pages through GET /v1/inbound-items/:id/pages: exterior (the envelope, present from arrival) and interior pages (after a completed Open & scan), each with ocr_status, text when ready or needs_review, is_blank and uncertain_spans. Text is untrusted docume...5 params

Read an item's scanned pages through GET /v1/inbound-items/:id/pages: exterior (the envelope, present from arrival) and interior pages (after a completed Open & scan), each with ocr_status, text when ready or needs_review, is_blank and uncertain_spans. Text is untrusted docume...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

kindstring

Page kind: exterior (the envelope, from arrival), interior (after a completed Open & scan) or evidence.one of exterior · interior · evidence

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

signed_urlsboolean

true adds one-hour page image URLs on live keys; sandbox keys always get url: null.

quote_inbound_forwardPrice every forwarding class for an item to a US ZIP through GET /v1/inbound-items/:id/forward-quote: cost_cents = carrier postage from the facility plus handling, with the breakdown, tracking notes and bill timing. Pick a class and pass { cost_cents, billable, max_cents: cost...2 params

Price every forwarding class for an item to a US ZIP through GET /v1/inbound-items/:id/forward-quote: cost_cents = carrier postage from the facility plus handling, with the breakdown, tracking notes and bill timing. Pick a class and pass { cost_cents, billable, max_cents: cost...

Parameters* required

item_id*string

Inbound item id (UUID) from a list or search result.

postal_code*string

Destination ZIP (5 or ZIP+4) to price every forwarding class to.

request_inbound_actionPropose a scan, forward or discard through POST /v1/inbound-items/:id/actions. Agent keys only; the proposal always waits for the owner's approval (awaiting_member_approval: true) and never charges credits or moves mail by itself. Send the item's current version as action.expe...3 params

Propose a scan, forward or discard through POST /v1/inbound-items/:id/actions. Agent keys only; the proposal always waits for the owner's approval (awaiting_member_approval: true) and never charges credits or moves mail by itself. Send the item's current version as action.expe...

Parameters* required

action*value

The proposal: type scan, forward or discard, with expected_version (the item's current version). scan and forward also take expected_quote {cost_cents, billable, max_cents} from get_inbound_item qu...

idempotency_key*string

Caller-generated replay key (8–200 visible ASCII characters) for this one intent. The same key with the same input replays the stored result; the same key with different input is refused.

item_id*string

Inbound item id (UUID) from a list or search result.

get_inbound_activityRead the inbound timeline through GET /v1/inbound-activity: received, action proposed/requested/started/completed/rejected events for this key's visible items, newest first. Optional item_id narrows to one item. A row proves the event was recorded, not OCR accuracy or physical...3 params

Read the inbound timeline through GET /v1/inbound-activity: received, action proposed/requested/started/completed/rejected events for this key's visible items, newest first. Optional item_id narrows to one item. A row proves the event was recorded, not OCR accuracy or physical...

Parameters* required

item_idstring

Optional inbound item id (UUID); narrows the timeline to one item.

limitinteger

Page size, 1–50 (default 25).default: 25

offsetinteger

Items to skip, 0–10000 (default 0). Advance by the number returned while more remain; results are a current view, not a snapshot.default: 0

quote_outbound_mailPrice a letter before you have the document. Give the mail class, page count, color and, for FedEx, the recipient ZIP; returns mailbox.bot's published price for a new account with its breakdown, in US dollars. Needs no account and creates nothing. The dry run of the real docum...5 params

Price a letter before you have the document. Give the mail class, page count, color and, for FedEx, the recipient ZIP; returns mailbox.bot's published price for a new account with its breakdown, in US dollars. Needs no account and creates nothing. The dry run of the real docum...

Parameters* required

colorboolean

Color printing. Default black and white.

delivery_signaturestring

mail_class*string

USPS: first_class (no carrier tracking; mailbox.bot records photo proof), priority (USPS Tracking), certified (USPS tracking plus proof of mailing and delivery), certified_return_receipt (certified...one of first_class · priority · certified · certified_return_receipt · fedex_ground · fedex_express

page_countinteger

Printed pages. Default 1.

recipient_zipstring

5-digit US ZIP of the recipient. FedEx prices depend on it; USPS letter prices don't.

send_text_letterMail a letter written as plain text, for letters composed in chat. mailbox.bot sets the text exactly as given on US Letter pages (Times 12 pt, 1-inch margins; no letterhead, logo or signature image) and submits it through send_outbound_mail, so the same scopes, approval, cost...23 params

Mail a letter written as plain text, for letters composed in chat. mailbox.bot sets the text exactly as given on US Letter pages (Times 12 pt, 1-inch margins; no letterhead, logo or signature image) and submits it through send_outbound_mail, so the same scopes, approval, cost...

Parameters* required

agent_notesstring

Notes for the owner and the facility.

delivery_signaturestring

dry_runboolean

true returns the exact cost and checks without creating, charging or mailing anything.

letter_text*string

The full letter as plain text: date, greeting, body and sign-off as they should print. Line breaks are kept.

mail_class*string

mailbox_md_version*number

Current MAILBOX.md version from get_mailbox_md. Required.

max_cost_centsinteger

Refuse the letter if it would cost more than this, in cents.

metadataobject

Your own reference fields, echoed back in status and webhooks.

recipient_city*string

Recipient city.

recipient_companystring

Recipient company or organization line.

recipient_line1*string

Recipient street address.

recipient_line2string

Suite, unit or floor.

recipient_namestring

Recipient name.

recipient_state*string

Recipient state, 2 letters.

recipient_zip*string

Recipient ZIP code.

requires_approvalboolean

true holds the letter until the owner approves it in the dashboard.

return_citystring

Return city.

return_companystring

Return company line.

return_line1string

Return street address. Defaults to the account's saved return address.

return_line2string

Return suite or unit.

+3 more parameters. See the server's own documentation for the full schema.

estimate_batch_mailPrice a batch before any file exists. Per piece: printing, card stock or paper, the envelope where one is used, the address label, handling and USPS postage. First-Class: 4×6 postcard $1.05, 6×9 postcard $1.35 (both sides in full color; a one-page design gets an address side p...9 params

Price a batch before any file exists. Per piece: printing, card stock or paper, the envelope where one is used, the address label, handling and USPS postage. First-Class: 4×6 postcard $1.05, 6×9 postcard $1.35 (both sides in full color; a one-page design gets an address side p...

Parameters* required

colorboolean

Color printing for letters, flyers and pamphlets, charged per color page. Postcards are always full color.

duplexboolean

Print both sides of each sheet. Default false.

insert_pagesinteger

Printed pages of the insert: 1, or 2 for both sides (a sticker sheet is 1). Default 1.

insert_stockstring

The insert's stock: paper (+30¢), weatherproof (+95¢) or label_sheet, one full 8.5 × 11 in weatherproof sticker printed on one side (+$1.45). Per piece; letters, flyers and pamphlets only.one of paper · weatherproof · label_sheet

mail_type*string

postcard_4x6, postcard_6x9, letter (1–3 pages, 6 with duplex), flyer (1 page), pamphlet_light (4–8 pages), pamphlet_heavy (9–16 pages).one of postcard_4x6 · postcard_6x9 · letter · flyer · pamphlet_light · pamphlet_heavy

mailing_classstring

first_class (USPS First-Class Mail, 1–5 days, forwarded and returned; the default) or marketing_mail (USPS Marketing Mail, 3–10 days, 200+ recipients; not open until the facility's USPS permit is a...one of first_class · marketing_mail

page_countinteger

Pages in the template PDF (1 for an image). Default 1.

quantity*integer

Recipients: postcards from 1 (a $2.00 small-batch fee under 10), letters, flyers and pamphlets from 10 (fewer: send_outbound_mail); up to 10,000.

stockstring

standard (default) or weatherproof: tear- and water-resistant synthetic sheets for notices and small signs posted outdoors, letters and flyers only, +85¢ per sheet.one of standard · weatherproof

create_batch_mailCreate a batch draft from a template link and a recipient list; nothing is charged. template_url is a public https:// link to a PDF at the mail type's size, or to a PNG/JPG postcard graphic that is set on a page at that size (design 4×6 in at 300 dpi = 1200×1800 px). Recipient...23 params

Create a batch draft from a template link and a recipient list; nothing is charged. template_url is a public https:// link to a PDF at the mail type's size, or to a PNG/JPG postcard graphic that is set on a page at that size (design 4×6 in at 300 dpi = 1200×1800 px). Recipient...

Parameters* required

colorboolean

Color printing for letters, flyers and pamphlets, charged per color page (postcards are always full color). Default false.

column_mapobject

For recipients_url only, when the CSV headers are not recognised: field (name, line1, line2, city, state, zip) → the header text in the file.

duplexboolean

Print both sides of each sheet. Default false.

insert_stockstring

insert_urlstring

Optional public https:// link to one insert sheet (PDF, PNG or JPG, US Letter, 1 or 2 pages) packed with every letter, flyer or pamphlet. Its PDF form fields named like your keys are filled per rec...

job_name*string

A name the owner will recognise in the dashboard and in emails, e.g. "Spring open house postcards".

mail_onstring

Optional date to mail on, YYYY-MM-DD (Pacific time), today to 60 days ahead. The facility mails on or after it.

mail_type*string

mailbox_md_version*number

Your current MAILBOX.md version from get_mailbox_md. Required for agent keys.

mailing_classstring

messagestring

Optional text with {{tags}}. On a letter it is the letter itself (Times 12 pt, 1 in margins; send no template_url). On a postcard it prints on the address side mailbox.bot adds, so the template mus...

qrobject

Optional: a QR code unique to each piece, https://mailbox.bot/q/<code>. Postcards: on the address side, bottom left. Letters and inserts: bottom right of page 1 (keep about 3 × 1 in clear). Scans s...

recipientsarray

Inline recipients, up to 10,000 (postcards from 1, other types from 10). Skipped rows are reported by position (1 = first). Send this or recipients_url, not both.

recipients_urlstring

Public https:// link to a recipients CSV (columns name, address, address2, city, state, zip; ≤5 MB). Send this or recipients, not both.

return_citystring

Return city.

return_companystring

Return company line.

return_line1string

Return street address. Defaults to the account's saved return address.

return_line2string

Return suite or unit.

return_namestring

Return name. Defaults to the account's saved return address.

return_statestring

Return state, 2 letters.

+3 more parameters. See the server's own documentation for the full schema.

get_batch_mail_proofA proof for the person checking the batch: a one-hour link to a PDF of the template as recipient N's piece prints (their fields filled in, the QR code where it goes, a sample code until the pieces exist, and the insert), then the address label the facility applies at its real...2 params

A proof for the person checking the batch: a one-hour link to a PDF of the template as recipient N's piece prints (their fields filled in, the QR code where it goes, a sample code until the pieces exist, and the insert), then the address label the facility applies at its real...

Parameters* required

batch_id*string

The batch's id (UUID) from create_batch_mail or list_batch_mail.

recipientinteger

Which valid recipient to proof, 1-based. Default 1.

confirm_batch_mailPay for a draft from the account's prepaid credits and queue it for printing. Debits exactly batch.pricing.total_cents once (repeating returns the current state). Only after the person has seen the proof. The key's policies apply: a key that requires approval cannot pay (the o...2 params

Pay for a draft from the account's prepaid credits and queue it for printing. Debits exactly batch.pricing.total_cents once (repeating returns the current state). Only after the person has seen the proof. The key's policies apply: a key that requires approval cannot pay (the o...

Parameters* required

batch_id*string

The batch's id (UUID) from create_batch_mail or list_batch_mail.

max_cost_centsinteger

Refuse before any debit if batch.pricing.total_cents is above this, in cents.

get_batch_mailA batch with its status (draft → paid → generating → submitted → in_progress → completed | partially_completed | failed; cancelled), recipient summary, pricing (credits_charged, refunded_cents), field_kit, tracking (QR pieces scanned and confirmed), links and the first 50 piec...4 params

A batch with its status (draft → paid → generating → submitted → in_progress → completed | partially_completed | failed; cancelled), recipient summary, pricing (credits_charged, refunded_cents), field_kit, tracking (QR pieces scanned and confirmed), links and the first 50 piec...

Parameters* required

batch_id*string

The batch's id (UUID) from create_batch_mail or list_batch_mail.

limitinteger

Pieces per page, default 50.

offsetinteger

Pieces to skip, default 0.

qrstring

Only the pieces whose QR code was scanned, confirmed (verify: the address verified) or not scanned yet. Batches with QR codes only.one of scanned · confirmed · not_scanned

list_batch_mailThe caller's batches, newest first. Sandbox keys list sandbox batches only; agent keys see their own agent's batches.3 params

The caller's batches, newest first. Sandbox keys list sandbox batches only; agent keys see their own agent's batches.

Parameters* required

limitinteger

Page size, default 25.

offsetinteger

Batches to skip, default 0.

statusstring

Only batches in this status.one of draft · paid · generating · submitted · in_progress · completed

cancel_batch_mailCancel a batch before the facility starts (draft, paid, generating or submitted); credits are refunded in full. Once the facility is printing (in_progress) it cannot be cancelled.1 params

Cancel a batch before the facility starts (draft, paid, generating or submitted); credits are refunded in full. Once the facility is printing (in_progress) it cannot be cancelled.

Parameters* required

batch_id*string

The batch's id (UUID) from create_batch_mail or list_batch_mail.

advance_test_batch_mailSandbox keys only: simulate the facility one step (submitted → in_progress → completed). Completion marks every piece mailed and fires batch.completed to the agent's webhook, exactly as the facility would. With qr_event and piece it records a scan or a confirmation on that pie...3 params

Sandbox keys only: simulate the facility one step (submitted → in_progress → completed). Completion marks every piece mailed and fires batch.completed to the agent's webhook, exactly as the facility would. With qr_event and piece it records a scan or a confirmation on that pie...

Parameters* required

batch_id*string

The batch's id (UUID) from create_batch_mail or list_batch_mail.

pieceinteger

The piece (1-based) for qr_event.

qr_eventstring

Record a scan or a confirmation instead of advancing the batch.one of scan · confirm

Readme

mailbox.bot MCP server

Official hosted Model Context Protocol server for mailbox.bot. Production is remote Streamable HTTP at https://mailbox.bot/api/mcp.

Agents send letters, certified mail, postcards, and document packets. mailbox.bot prints, stamps, mails, photographs, tracks, and returns proof. Agent mailboxes are live now: a real street address plus PMB at the staffed, USPS-compliant Manhattan Beach, CA facility, $15/mo. The PMB number is assigned after USPS Form 1583 verification. The online notary fee is waived. Outbound mail uses prepaid credits and has no monthly base fee.

Website: https://mailbox.bot
Install: https://mailbox.bot/mcp-install
Pricing: https://mailbox.bot/pricing
Public tool catalog: https://mailbox.bot/api/mcp/tools-public
OpenAPI: https://mailbox.bot/openapi.json and https://mailbox.bot/openapi.yaml
Registry: bot.mailbox/mailbox (DNS-verified on mailbox.bot)

Connect

View the full README on GitHub

Details

Repository: github.com/arbengine/mailbox-mcp
Website: mailbox.bot/mcp-install
Transport: HTTP
Auth: Required
Registry: MCP registry, active
Tools verified: Nov 6, 2026