Mailbox

Official29 tools

by mailbox

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

API for AI agents to send physical letters and certified mail with sandbox/live modes.

Captured live from the server via tools/list.

get_mailbox

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.

No parameters.

list_packages

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.

Parameters (5)

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

get_package

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

Parameters (1)

package_idstringrequired
UUID of the package to retrieve.

get_package_photos

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.

Parameters (2)

package_idstringrequired
UUID of the package to get photos for.
photo_typestring
Filter by photo type. "exterior" = package exterior, "label" = shipping label closeup, "barcode" = barcode scan, "content_scan" = opened package contents.

request_action

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.

Parameters (4)

package_idstringrequired
UUID of the package to act on.
actionstringrequired
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" = send back, "photograph" = take photos, "open_and_scan" = open package and scan contents, "record_video" = video recording of package.
parametersobject
Action-specific parameters. For "forward": { address, city, state, zip }. For "scan": { scan_type }. For "hold": { until_date }.
prioritystring
Processing priority. "urgent" = same-day processing, "high" = next business day, "normal" = standard queue, "low" = when convenient.

request_scan

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.

Parameters (2)

package_idstringrequired
UUID of the package to scan.
scan_typestring
Type of scan. "label" = shipping label only, "envelope" = exterior envelope, "document" = full document OCR, "content" = opened package contents.

get_scan_results

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

Parameters (1)

package_idstringrequired
UUID of the package to get scan results for.

add_tag

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.

Parameters (2)

package_idstringrequired
UUID of the package to tag.
tagstringrequired
Tag name (e.g. "hardware-order", "urgent", "return-needed"). Free-form, case-sensitive.

add_note

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.

Parameters (3)

package_idstringrequired
UUID of the package to annotate.
notestringrequired
Note text (e.g. "Appears to be the replacement GPU from RMA #4521").
metadataobject
Optional structured metadata attached to the note (e.g. { "rma_number": "4521", "vendor": "NVIDIA" }).

create_rule

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.

Parameters (5)

namestringrequired
Human-readable rule name (e.g. "Forward Amazon packages", "Shred junk mail").
conditionsobjectrequired
Conditions that must ALL match for the rule to trigger.
action_typestringrequired
Action to auto-trigger when conditions match.
action_paramsobjectrequired
Parameters for the action (e.g. forwarding address for "forward", scan_type for "scan").
requires_approvalboolean
If true, matched packages require human approval before the action executes.

register_expected

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

Parameters (6)

tracking_numberstring
Carrier tracking number for the expected shipment.
carrierstring
Shipping carrier (e.g. "fedex", "ups", "usps").
descriptionstring
Human-readable description of the shipment (e.g. "Replacement laptop from Dell").
expected_bystring
Expected arrival date in ISO 8601 format. Used for alerts if the package is late.
auto_actionstring
Action to auto-execute when the package arrives.
auto_action_paramsobject
Parameters for the auto-action (e.g. forwarding address).

get_usage

Get usage summary and billing events for a time period. Returns itemized events (scans, forwards, mail sends) with costs, plus period totals. Defaults to the current billing period if no dates are specified.

Parameters (2)

period_startstring
Start of the reporting period in ISO 8601 format. Defaults to current billing period start.
period_endstring
End of the reporting period in ISO 8601 format. Defaults to now.

list_inbound_forwarding_addresses

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.

No parameters.

list_inbound_mail

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 (6)

limitnumber
Maximum number of inbound items to return (1-100).
offsetnumber
Number of inbound items to skip for pagination.
categorystring
Optional category filter such as "Needs review" or "Loan / Mortgage".
statusstring
Optional inbound status filter.
thread_idstring
Only return inbound items linked to this postal mail thread.
includearray
Optional expansions. Defaults to ["drafting"]. Add ocr/lineage only when deeper provenance is needed.

get_inbound_mail

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 (3)

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

list_postal_threads

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 (5)

limitnumber
Maximum number of threads to return (1-100).
offsetnumber
Number of threads to skip for pagination.
categorystring
Optional category filter.
statusstring
Optional thread status filter.
includearray
Optional expansions. Add events to include inbound/outbound timeline references.

get_postal_thread

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 (2)

thread_idstringrequired
UUID of the postal mail thread to retrieve.
includearray
Optional expansions. Add events to include inbound/outbound timeline references.

update_action

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.

Parameters (6)

action_idstringrequired
The action request ID to update.
mailbox_md_versionnumberrequired
Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification.
agent_notesstring
Free-text notes from the agent (e.g. "Forwarding per standing rule #3").
agent_dataobject
Structured data to attach (e.g. OCR results, extracted fields, classification labels).
respond_to_clarificationstring
Response text when action status is needs_clarification. Providing this auto-resumes the action to in_progress.
decision_contextobject
Link this decision to a specific MAILBOX.md instruction for auditability.

get_mailbox_md

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.

No parameters.

propose_mailbox_md_edit

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 (2)

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

send_facility_message

Send a message to the facility operator managing your mailbox. 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 (4)

facility_idstringrequired
The facility to message. Get this from the get_mailbox response.
bodystringrequired
Message text (1-5000 characters).
package_idstring
Optional: link this message to a specific package for context.
action_request_idstring
Optional: link this message to an action request for context.

list_facility_conversations

List your active facility conversations with unread message counts and last message preview. Each conversation corresponds to one facility where you have a mailbox.

Parameters (2)

limitnumber
Maximum number of conversations to return (1-100). Defaults to 20.
offsetnumber
Number of conversations to skip for pagination. Defaults to 0.

get_facility_messages

Read the message thread with a specific facility. Returns messages in reverse chronological order with sender role (member, facility, agent). Supports cursor-based pagination. Automatically marks facility messages as read.

Parameters (3)

facility_idstringrequired
UUID of the facility whose conversation to read.
limitnumber
Maximum number of messages to return (1-100). Defaults to 50.
beforestring
Cursor: only return messages sent before this ISO 8601 timestamp. Use the oldest message timestamp from the previous page.

update_webhook

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.

Parameters (3)

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

send_outbound_mail

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. IMPORTANT: With a production key (sk_agent_), this immediately charges the member's card on file. Use dry_run=true to preview cost before committing, or requires_approval=true to defer until human approval. Sandbox keys (sk_agent_test_) skip billing entirely. tracking_number is guaranteed/required for certified, certified_return_receipt, FedEx, and UPS mail classes. USPS first_class and priority do not guarantee tracking; 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.

Parameters (29)

document_base64stringrequired
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.
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.
mailbox_md_versionnumberrequired
Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification.
recipient_namestringrequired
Full name of the mail recipient.
recipient_line1stringrequired
Street address line 1 of the recipient.
recipient_line2string
Street address line 2 (apartment, suite, unit, etc.).
recipient_citystringrequired
Recipient city.
recipient_statestringrequired
2-letter US state code (e.g. CA, NY, TX).
recipient_zipstringrequired
5 or 5+4 digit ZIP code (e.g. "90210" or "90210-1234").
recipient_countrystring
ISO 3166-1 alpha-2 country code. Defaults to "US".
return_namestring
Return address name. Defaults to the member's profile name if omitted.
return_companystring
Optional company or organization line for the return address.
return_line1string
Return address line 1. Defaults to member profile if omitted.
return_line2string
Return address line 2 (suite, unit, etc.).
return_citystring
Return address city. Defaults to member profile if omitted.
return_statestring
Return address state (2-letter code). Defaults to member profile if omitted.
return_zipstring
Return address ZIP code. Defaults to member profile if omitted.
mail_classstring
Postal or carrier service. Use first_class for ordinary USPS letters without guaranteed tracking. Use certified for USPS tracking and proof of mailing; use certified_return_receipt when a return receipt is required. Use fedex_* or ups_* classes when private-carrier tracking is required. FedEx express classes use the Standard List document baseline from the configured fulfillment origin unless FedEx One Rate is explicitly configured operationally.
colorboolean
Print in color. Adds a per-page color surcharge.
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.
package_idstring
Link this mail to an inbound package (e.g. replying to received correspondence).
inbound_capture_idstring
Optional inbound mail item this outbound piece is replying to. Recommended when drafting from OCR/forwarded-mail context.
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.
agent_notesstring
Instructions for the facility operator (e.g. "Time-sensitive — mail today").
requires_approvalboolean
If true, the renter must approve in their dashboard before the mail is printed and sent.
metadataobject
Arbitrary key-value pairs echoed in GET responses and webhooks. Recommended convention: { "workflow_id": "wf_123", "reason": "Customer cancellation", "correlation_id": "abc" }.
dry_runboolean
Validate inputs and return cost breakdown without creating a record or charging. Use to preview cost before committing.
max_cost_centsinteger
Cost cap in cents. If the calculated cost exceeds this, the request is rejected with 422 before any charge. Prevents accidental expensive mailings.

list_outbound_mail

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

Parameters (7)

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, "failed" = delivery failed, "cancelled" = cancelled before mailing.
qstring
Search recipient name, address lines, city/state/ZIP, tracking number, or agent notes.
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.
test_modeboolean
Filter sandbox/test records. Defaults to the key environment for agent-scoped keys; member keys can pass true or false explicitly.
limitnumber
Maximum number of mail jobs to return (1-100). Defaults to 20.
offsetnumber
Number of mail jobs to skip for pagination. Defaults to 0.

get_outbound_mail

Get full details of an outbound mail job including recipient address, mail class, page count, cost breakdown, current status, fulfillment photos, and a time-limited signed URL to download the original PDF.

Parameters (1)

mail_idstringrequired
UUID of the outbound mail job to retrieve.

create_test_outbound_mail

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

Parameters (10)

recipient_namestring
Recipient name for the simulated mailpiece.
recipient_line1string
Recipient street line 1.
recipient_citystring
Recipient city.
recipient_statestring
Recipient 2-letter state code.
recipient_zipstring
Recipient ZIP code. Affects estimated live postage, private-carrier zone, and FedEx local/regional/national area.
mail_classstring
Mail class to simulate. Postal or carrier service. Use first_class for ordinary USPS letters without guaranteed tracking. Use certified for USPS tracking and proof of mailing; use certified_return_receipt when a return receipt is required. Use fedex_* or ups_* classes when private-carrier tracking is required. FedEx express classes use the Standard List document baseline from the configured fulfillment origin unless FedEx One Rate is explicitly configured operationally.
page_countnumber
Simulated page count used for pricing.
colorboolean
Whether to include color-print surcharge in the live estimate.
agent_notesstring
Optional facility/operator notes for the simulated mailpiece.
metadataobject
Arbitrary metadata echoed in responses and webhooks.

advance_test_outbound_mail

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 tracking, carrier, dispatch method, and receipt photo; mailed becomes delivered.

Parameters (1)

mail_idstringrequired
UUID of the test_mode outbound mail record to advance.

Install

Tools (29)

get_mailboxlist_packagesget_packageget_package_photosrequest_actionrequest_scanget_scan_resultsadd_tag

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mailbox.bot/api/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mailbox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mailbox.bot/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.