{"server":{"name":"mailbox.bot","version":"1.0.0","protocolVersion":"2025-11-25"},"auth":{"type":"bearer","agent_prefix":"sk_agent_","member_prefix":"sk_live_","location":"header"},"endpoint":"https://mailbox.bot/api/mcp","install_guide":"https://mailbox.bot/mcp-install","tool_count":29,"tools":[{"name":"get_mailbox","description":"Get your agent's postal mailing address, suite number, facility details, and current mailbox status. Returns the full street address you can use as a return address on outbound mail.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Mailbox address, facility, and status details.","properties":{"id":{"type":"string","format":"uuid","description":"Mailbox UUID."},"status":{"type":"string","description":"Current mailbox status."},"suite":{"type":"string","description":"Suite or unit identifier for receiving mail."},"street":{"type":"string","description":"Mailbox street address."},"city":{"type":"string","description":"Mailbox city."},"state":{"type":"string","description":"Mailbox state."},"zip":{"type":"string","description":"Mailbox ZIP code."},"facility":{"type":"object","description":"Facility managing the mailbox.","additionalProperties":true}},"required":[],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Mailbox","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_packages","description":"List inbound packages at your mailbox with optional filters by status, carrier, and date. Returns tracking number, carrier, status, and received timestamp for each package. Use pagination (limit/offset) for large result sets.","inputSchema":{"type":"object","properties":{"status":{"type":"string","enum":["received","stored","forwarding_requested","forwarding_shipped","forwarded","disposed","returned"],"description":"Filter by package lifecycle status. \"received\" = just arrived, \"stored\" = in facility storage, \"forwarded\" = shipped to forwarding address."},"carrier":{"type":"string","enum":["fedex","ups","usps","dhl","amazon","ontrac","lasership"],"description":"Filter by shipping carrier."},"since":{"type":"string","format":"date-time","description":"Only return packages received after this ISO 8601 date-time."},"limit":{"type":"number","default":20,"maximum":100,"description":"Maximum number of packages to return (1-100). Defaults to 20."},"offset":{"type":"number","default":0,"description":"Number of packages to skip for pagination. Defaults to 0."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"array","description":"Inbound package summaries.","items":{"type":"object","description":"One returned record.","additionalProperties":true}}},"required":["result"],"additionalProperties":false},"annotations":{"title":"List Packages","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_package","description":"Get full package details including photos, tracking events, shipping label data (carrier, addresses, weight), forwarding status, storage location, and action history.","inputSchema":{"type":"object","properties":{"package_id":{"type":"string","format":"uuid","description":"UUID of the package to retrieve."}},"required":["package_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Package details with photos, events, and extracted label data.","properties":{"package":{"type":"object","description":"Package record.","additionalProperties":true},"photos":{"type":"array","description":"Package photo records.","items":{"type":"object","description":"One returned record.","additionalProperties":true}},"events":{"type":"array","description":"Package event records.","items":{"type":"object","description":"One returned record.","additionalProperties":true}},"label_data":{"type":"array","description":"Parsed shipping label records.","items":{"type":"object","description":"One returned record.","additionalProperties":true}}},"required":["package","photos","events","label_data"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Package","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_package_photos","description":"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.","inputSchema":{"type":"object","properties":{"package_id":{"type":"string","format":"uuid","description":"UUID of the package to get photos for."},"photo_type":{"type":"string","enum":["exterior","label","barcode","content_scan"],"description":"Filter by photo type. \"exterior\" = package exterior, \"label\" = shipping label closeup, \"barcode\" = barcode scan, \"content_scan\" = opened package contents."}},"required":["package_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"array","description":"Package photo records with OCR metadata.","items":{"type":"object","description":"One returned record.","additionalProperties":true}}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Package Photos","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"request_action","description":"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.","inputSchema":{"type":"object","properties":{"package_id":{"type":"string","format":"uuid","description":"UUID of the package to act on."},"action":{"type":"string","enum":["forward","shred","scan","hold","return_to_sender","dispose","photograph","open_and_scan","record_video"],"description":"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."},"parameters":{"type":"object","description":"Action-specific parameters. For \"forward\": { address, city, state, zip }. For \"scan\": { scan_type }. For \"hold\": { until_date }."},"priority":{"type":"string","enum":["low","normal","high","urgent"],"default":"normal","description":"Processing priority. \"urgent\" = same-day processing, \"high\" = next business day, \"normal\" = standard queue, \"low\" = when convenient."}},"required":["package_id","action"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created facility action request record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Request Action","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true}},{"name":"request_scan","description":"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.","inputSchema":{"type":"object","properties":{"package_id":{"type":"string","format":"uuid","description":"UUID of the package to scan."},"scan_type":{"type":"string","enum":["label","envelope","document","content"],"default":"document","description":"Type of scan. \"label\" = shipping label only, \"envelope\" = exterior envelope, \"document\" = full document OCR, \"content\" = opened package contents."}},"required":["package_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created scan request record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Request Scan","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"get_scan_results","description":"Get document scan results including raw OCR text, structured data fields (addresses, dates, amounts), and confidence scores. Returns empty if scan is still processing.","inputSchema":{"type":"object","properties":{"package_id":{"type":"string","format":"uuid","description":"UUID of the package to get scan results for."}},"required":["package_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"array","description":"Document scan records and OCR results.","items":{"type":"object","description":"One returned record.","additionalProperties":true}}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Scan Results","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"add_tag","description":"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.","inputSchema":{"type":"object","properties":{"package_id":{"type":"string","format":"uuid","description":"UUID of the package to tag."},"tag":{"type":"string","description":"Tag name (e.g. \"hardware-order\", \"urgent\", \"return-needed\"). Free-form, case-sensitive."}},"required":["package_id","tag"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created or existing package tag record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Add Tag","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"add_note","description":"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.","inputSchema":{"type":"object","properties":{"package_id":{"type":"string","format":"uuid","description":"UUID of the package to annotate."},"note":{"type":"string","description":"Note text (e.g. \"Appears to be the replacement GPU from RMA #4521\")."},"metadata":{"type":"object","description":"Optional structured metadata attached to the note (e.g. { \"rma_number\": \"4521\", \"vendor\": \"NVIDIA\" })."}},"required":["package_id","note"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created package note record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Add Note","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"create_rule","description":"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.","inputSchema":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable rule name (e.g. \"Forward Amazon packages\", \"Shred junk mail\")."},"conditions":{"type":"object","description":"Conditions that must ALL match for the rule to trigger.","properties":{"carrier":{"type":"string","description":"Match packages from this carrier (e.g. \"fedex\", \"ups\", \"usps\")."},"weight_oz_gt":{"type":"number","description":"Match packages heavier than this weight in ounces."},"weight_oz_lt":{"type":"number","description":"Match packages lighter than this weight in ounces."},"sender_contains":{"type":"string","description":"Match packages where the sender name or address contains this string (case-insensitive)."},"tracking_prefix":{"type":"string","description":"Match packages whose tracking number starts with this prefix."}}},"action_type":{"type":"string","enum":["forward","shred","scan","hold","return_to_sender","dispose","open_and_scan","record_video"],"description":"Action to auto-trigger when conditions match."},"action_params":{"type":"object","description":"Parameters for the action (e.g. forwarding address for \"forward\", scan_type for \"scan\")."},"requires_approval":{"type":"boolean","default":false,"description":"If true, matched packages require human approval before the action executes."}},"required":["name","conditions","action_type","action_params"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created standing rule record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Create Rule","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"register_expected","description":"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).","inputSchema":{"type":"object","properties":{"tracking_number":{"type":"string","description":"Carrier tracking number for the expected shipment."},"carrier":{"type":"string","description":"Shipping carrier (e.g. \"fedex\", \"ups\", \"usps\")."},"description":{"type":"string","description":"Human-readable description of the shipment (e.g. \"Replacement laptop from Dell\")."},"expected_by":{"type":"string","format":"date-time","description":"Expected arrival date in ISO 8601 format. Used for alerts if the package is late."},"auto_action":{"type":"string","enum":["forward","shred","scan","hold","return_to_sender","dispose","open_and_scan","record_video"],"description":"Action to auto-execute when the package arrives."},"auto_action_params":{"type":"object","description":"Parameters for the auto-action (e.g. forwarding address)."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created expected shipment record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Register Expected Shipment","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"get_usage","description":"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.","inputSchema":{"type":"object","properties":{"period_start":{"type":"string","format":"date-time","description":"Start of the reporting period in ISO 8601 format. Defaults to current billing period start."},"period_end":{"type":"string","format":"date-time","description":"End of the reporting period in ISO 8601 format. Defaults to now."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"array","description":"Usage and billing event records.","items":{"type":"object","description":"One returned record.","additionalProperties":true}}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Usage","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_inbound_forwarding_addresses","description":"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.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Private inbound forwarding email aliases.","properties":{"forwarding_addresses":{"type":"array","description":"Private inbound forwarding email aliases.","items":{"type":"object","description":"One returned record.","additionalProperties":true}}},"required":["forwarding_addresses"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"List Inbound Forwarding Addresses","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_inbound_mail","description":"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.","inputSchema":{"type":"object","properties":{"limit":{"type":"number","default":20,"maximum":100,"description":"Maximum number of inbound items to return (1-100)."},"offset":{"type":"number","default":0,"description":"Number of inbound items to skip for pagination."},"category":{"type":"string","description":"Optional category filter such as \"Needs review\" or \"Loan / Mortgage\"."},"status":{"type":"string","enum":["captured","stored","extracted","needs_review","failed"],"description":"Optional inbound status filter."},"thread_id":{"type":"string","format":"uuid","description":"Only return inbound items linked to this postal mail thread."},"include":{"type":"array","items":{"type":"string","enum":["drafting","files","ocr","lineage"]},"description":"Optional expansions. Defaults to [\"drafting\"]. Add ocr/lineage only when deeper provenance is needed."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Forwarded inbound mail items plus pagination.","properties":{"inbound_mail":{"type":"array","description":"Forwarded inbound mail items with optional draft context.","items":{"type":"object","description":"One returned record.","additionalProperties":true}},"pagination":{"type":"object","description":"Pagination metadata for the current result set.","properties":{"total":{"type":"integer","description":"Total matching records when available."},"limit":{"type":"integer","description":"Maximum records requested."},"offset":{"type":"integer","description":"Records skipped before this page."},"has_more":{"type":"boolean","description":"Whether another page is available."}},"additionalProperties":false}},"required":["inbound_mail","pagination"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"List Inbound Mail","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_inbound_mail","description":"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.","inputSchema":{"type":"object","properties":{"inbound_mail_id":{"type":"string","format":"uuid","description":"UUID of the inbound mail item to retrieve."},"include":{"type":"array","items":{"type":"string","enum":["drafting","files","ocr","lineage","signed_urls"]},"description":"Optional expansions. Defaults to [\"drafting\"]. Add signed_urls only when the agent truly needs temporary file access."},"signed_urls":{"type":"boolean","default":false,"description":"If true, return short-lived signed URLs for stored files."}},"required":["inbound_mail_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"One forwarded inbound mail item.","properties":{"inbound_mail":{"type":"object","description":"Forwarded inbound mail item with optional files, OCR, lineage, and draft context.","additionalProperties":true}},"required":["inbound_mail"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Inbound Mail","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"list_postal_threads","description":"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.","inputSchema":{"type":"object","properties":{"limit":{"type":"number","default":20,"maximum":100,"description":"Maximum number of threads to return (1-100)."},"offset":{"type":"number","default":0,"description":"Number of threads to skip for pagination."},"category":{"type":"string","description":"Optional category filter."},"status":{"type":"string","enum":["open","waiting","closed","archived"],"description":"Optional thread status filter."},"include":{"type":"array","items":{"type":"string","enum":["events"]},"description":"Optional expansions. Add events to include inbound/outbound timeline references."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Postal mail workflow threads plus pagination.","properties":{"postal_threads":{"type":"array","description":"Physical-mail workflow thread records.","items":{"type":"object","description":"One returned record.","additionalProperties":true}},"pagination":{"type":"object","description":"Pagination metadata for the current result set.","properties":{"total":{"type":"integer","description":"Total matching records when available."},"limit":{"type":"integer","description":"Maximum records requested."},"offset":{"type":"integer","description":"Records skipped before this page."},"has_more":{"type":"boolean","description":"Whether another page is available."}},"additionalProperties":false}},"required":["postal_threads","pagination"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"List Postal Threads","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_postal_thread","description":"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.","inputSchema":{"type":"object","properties":{"thread_id":{"type":"string","format":"uuid","description":"UUID of the postal mail thread to retrieve."},"include":{"type":"array","items":{"type":"string","enum":["events"]},"description":"Optional expansions. Add events to include inbound/outbound timeline references."}},"required":["thread_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"One postal mail workflow thread.","properties":{"postal_thread":{"type":"object","description":"Physical-mail workflow thread with optional timeline events.","additionalProperties":true}},"required":["postal_thread"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Postal Thread","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"update_action","description":"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.","inputSchema":{"type":"object","properties":{"action_id":{"type":"string","format":"uuid","description":"The action request ID to update."},"mailbox_md_version":{"type":"number","description":"Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification."},"agent_notes":{"type":"string","description":"Free-text notes from the agent (e.g. \"Forwarding per standing rule #3\")."},"agent_data":{"type":"object","description":"Structured data to attach (e.g. OCR results, extracted fields, classification labels)."},"respond_to_clarification":{"type":"string","description":"Response text when action status is needs_clarification. Providing this auto-resumes the action to in_progress."},"decision_context":{"type":"object","description":"Link this decision to a specific MAILBOX.md instruction for auditability.","properties":{"mailbox_md_section":{"type":"string","description":"Section heading that drove this decision (e.g. \"## Forward Rules\")."},"reasoning":{"type":"string","description":"Which specific instruction matched (e.g. \"Forward all packages from Amazon to home address\")."}}}},"required":["action_id","mailbox_md_version"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Updated facility action request record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Update Action","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_mailbox_md","description":"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.","inputSchema":{"type":"object","properties":{},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Current MAILBOX.md standing instructions.","properties":{"mailbox_md":{"type":"string","description":"Full MAILBOX.md instruction text."},"version":{"type":"integer","description":"Current instruction version."},"hash":{"type":["string","null"],"description":"Content hash when available."},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last update timestamp when available."}},"required":["mailbox_md","version","hash","updated_at"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get MAILBOX.md","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"propose_mailbox_md_edit","description":"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.","inputSchema":{"type":"object","properties":{"suggested_content":{"type":"string","description":"Full proposed MAILBOX.md content (max 10,000 chars). Must include the complete document, not just the diff."},"reason":{"type":"string","description":"Why this change is suggested (e.g. \"Observed 5 Amazon packages this week, all forwarded manually — adding auto-forward rule\")."}},"required":["suggested_content","reason"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created MAILBOX.md suggestion record.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Propose MAILBOX.md Edit","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"send_facility_message","description":"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.","inputSchema":{"type":"object","properties":{"facility_id":{"type":"string","format":"uuid","description":"The facility to message. Get this from the get_mailbox response."},"body":{"type":"string","description":"Message text (1-5000 characters)."},"package_id":{"type":"string","format":"uuid","description":"Optional: link this message to a specific package for context."},"action_request_id":{"type":"string","format":"uuid","description":"Optional: link this message to an action request for context."}},"required":["facility_id","body"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Sent facility message identifiers and body.","properties":{"message_id":{"type":"string","format":"uuid","description":"Created message UUID."},"conversation_id":{"type":"string","format":"uuid","description":"Facility conversation UUID."},"body":{"type":"string","description":"Sent message body."},"created_at":{"type":"string","format":"date-time","description":"Message creation timestamp."}},"required":["message_id","conversation_id","body","created_at"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Send Facility Message","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"list_facility_conversations","description":"List your active facility conversations with unread message counts and last message preview. Each conversation corresponds to one facility where you have a mailbox.","inputSchema":{"type":"object","properties":{"limit":{"type":"number","default":20,"maximum":100,"description":"Maximum number of conversations to return (1-100). Defaults to 20."},"offset":{"type":"number","default":0,"description":"Number of conversations to skip for pagination. Defaults to 0."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Facility conversations plus pagination.","properties":{"conversations":{"type":"array","description":"Facility conversation summaries.","items":{"type":"object","description":"One returned record.","additionalProperties":true}},"pagination":{"type":"object","description":"Pagination metadata for the current result set.","properties":{"total":{"type":"integer","description":"Total matching records when available."},"limit":{"type":"integer","description":"Maximum records requested."},"offset":{"type":"integer","description":"Records skipped before this page."},"has_more":{"type":"boolean","description":"Whether another page is available."}},"additionalProperties":false}},"required":["conversations","pagination"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"List Conversations","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_facility_messages","description":"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.","inputSchema":{"type":"object","properties":{"facility_id":{"type":"string","format":"uuid","description":"UUID of the facility whose conversation to read."},"limit":{"type":"number","default":50,"maximum":100,"description":"Maximum number of messages to return (1-100). Defaults to 50."},"before":{"type":"string","format":"date-time","description":"Cursor: only return messages sent before this ISO 8601 timestamp. Use the oldest message timestamp from the previous page."}},"required":["facility_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Messages exchanged with a facility.","properties":{"messages":{"type":"array","description":"Facility message records in chronological order.","items":{"type":"object","description":"One returned record.","additionalProperties":true}},"facility_name":{"type":"string","description":"Facility display name."},"has_more":{"type":"boolean","description":"Whether older messages are available."}},"required":["messages","facility_name","has_more"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Facility Messages","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"update_webhook","description":"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.","inputSchema":{"type":"object","properties":{"webhook_url":{"type":"string","format":"uri","description":"HTTPS URL to receive webhook POST requests. Must respond with 2xx within 10 seconds."},"event_types":{"type":"array","items":{"type":"string"},"description":"Array of event types to subscribe to (e.g. [\"package.received\", \"mail.status_changed\"]). Empty array disables all events."},"enabled":{"type":"boolean","description":"Set to false to pause webhook delivery without removing the URL."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Webhook configuration status.","properties":{"updated":{"type":"boolean","description":"Whether the webhook settings were accepted."},"webhook_url":{"type":"string","format":"uri","description":"Configured webhook endpoint when supplied."},"event_types":{"type":"array","items":{"type":"string"},"description":"Subscribed event types."},"enabled":{"type":"boolean","description":"Whether webhook delivery is enabled."}},"required":["updated","event_types","enabled"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Update Webhook","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"send_outbound_mail","description":"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. Optionally attach the outbound mail to inbound context with inbound_capture_id and postal_mail_thread_id so lineage stays explicit.","inputSchema":{"type":"object","properties":{"document_base64":{"type":"string","description":"Base64-encoded document file. Supported formats: PDF, DOCX, JPG, PNG, TXT, CSV. Max 10MB decoded."},"document_filename":{"type":"string","description":"Original filename with extension (e.g. \"letter.docx\"). Required for reliable non-PDF format detection."},"page_count":{"type":"number","description":"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_version":{"type":"number","description":"Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification."},"recipient_name":{"type":"string","description":"Full name of the mail recipient."},"recipient_line1":{"type":"string","description":"Street address line 1 of the recipient."},"recipient_line2":{"type":"string","description":"Street address line 2 (apartment, suite, unit, etc.)."},"recipient_city":{"type":"string","description":"Recipient city."},"recipient_state":{"type":"string","description":"2-letter US state code (e.g. CA, NY, TX)."},"recipient_zip":{"type":"string","description":"5 or 5+4 digit ZIP code (e.g. \"90210\" or \"90210-1234\")."},"recipient_country":{"type":"string","default":"US","description":"ISO 3166-1 alpha-2 country code. Defaults to \"US\"."},"return_name":{"type":"string","description":"Return address name. Defaults to the member's profile name if omitted."},"return_line1":{"type":"string","description":"Return address line 1. Defaults to member profile if omitted."},"return_line2":{"type":"string","description":"Return address line 2 (suite, unit, etc.)."},"return_city":{"type":"string","description":"Return address city. Defaults to member profile if omitted."},"return_state":{"type":"string","description":"Return address state (2-letter code). Defaults to member profile if omitted."},"return_zip":{"type":"string","description":"Return address ZIP code. Defaults to member profile if omitted."},"mail_class":{"type":"string","enum":["first_class","priority","certified","certified_return_receipt"],"default":"first_class","description":"USPS mail class. \"first_class\" = 3-5 days, \"priority\" = 1-3 days, \"certified\" = with tracking and proof of mailing, \"certified_return_receipt\" = certified with signed delivery confirmation."},"color":{"type":"boolean","default":false,"description":"Print in color. Adds a per-page color surcharge."},"duplex":{"type":"boolean","default":false,"description":"Print double-sided to reduce page count and postage."},"package_id":{"type":"string","format":"uuid","description":"Link this mail to an inbound package (e.g. replying to received correspondence)."},"inbound_capture_id":{"type":"string","format":"uuid","description":"Optional inbound mail item this outbound piece is replying to. Recommended when drafting from OCR/forwarded-mail context."},"postal_mail_thread_id":{"type":"string","format":"uuid","description":"Optional physical-mail thread to attach this outbound mail to. Lets agents keep inbound and outbound activity in one durable workflow."},"agent_notes":{"type":"string","description":"Instructions for the facility operator (e.g. \"Time-sensitive — mail today\")."},"requires_approval":{"type":"boolean","default":false,"description":"If true, the renter must approve in their dashboard before the mail is printed and sent."},"metadata":{"type":"object","description":"Arbitrary key-value pairs echoed in GET responses and webhooks. Recommended convention: { \"workflow_id\": \"wf_123\", \"reason\": \"Customer cancellation\", \"correlation_id\": \"abc\" }."},"dry_run":{"type":"boolean","default":false,"description":"Validate inputs and return cost breakdown without creating a record or charging. Use to preview cost before committing."},"max_cost_cents":{"type":"integer","description":"Cost cap in cents. If the calculated cost exceeds this, the request is rejected with 422 before any charge. Prevents accidental expensive mailings."}},"required":["document_base64","mailbox_md_version","recipient_name","recipient_line1","recipient_city","recipient_state","recipient_zip"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Submitted outbound mail job or dry-run cost preview.","properties":{"outbound_mail":{"type":"object","description":"Outbound postal mail job summary.","properties":{"id":{"type":"string","format":"uuid","description":"Outbound mail job UUID."},"status":{"type":"string","description":"Current mail lifecycle status."},"mail_class":{"type":"string","description":"Selected postal or carrier service."},"recipient_name":{"type":"string","description":"Recipient name."},"page_count":{"type":"integer","description":"Number of printed pages."},"cost_cents":{"type":"integer","description":"Charged cost in cents, or 0 for sandbox/test records."},"tracking_number":{"type":"string","description":"Carrier tracking number when available."},"carrier":{"type":"string","description":"Carrier name when available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"test_mode":{"type":"boolean","description":"Whether this is a sandbox/test mail record."}},"additionalProperties":true},"total_cents":{"type":"integer","description":"Dry-run estimated total cost in cents."},"cost_breakdown":{"type":"object","description":"Dry-run or submitted-mail cost components.","additionalProperties":true}},"required":[],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Send Outbound Mail","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":true}},{"name":"list_outbound_mail","description":"List outbound mail jobs with status tracking. Returns mail ID, recipient, mail class, status, cost, and timestamps. Filter by status to see pending, in-transit, or delivered mail.","inputSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pending_approval","submitted","ready","mailed","delivered","failed","cancelled"],"description":"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."},"limit":{"type":"number","default":20,"maximum":100,"description":"Maximum number of mail jobs to return (1-100). Defaults to 20."},"offset":{"type":"number","default":0,"description":"Number of mail jobs to skip for pagination. Defaults to 0."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"array","items":{"type":"object","description":"Outbound postal mail job summary.","properties":{"id":{"type":"string","format":"uuid","description":"Outbound mail job UUID."},"status":{"type":"string","description":"Current mail lifecycle status."},"mail_class":{"type":"string","description":"Selected postal or carrier service."},"recipient_name":{"type":"string","description":"Recipient name."},"page_count":{"type":"integer","description":"Number of printed pages."},"cost_cents":{"type":"integer","description":"Charged cost in cents, or 0 for sandbox/test records."},"tracking_number":{"type":"string","description":"Carrier tracking number when available."},"carrier":{"type":"string","description":"Carrier name when available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"test_mode":{"type":"boolean","description":"Whether this is a sandbox/test mail record."}},"additionalProperties":true},"description":"Outbound mail job summaries."}},"required":["result"],"additionalProperties":false},"annotations":{"title":"List Outbound Mail","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"get_outbound_mail","description":"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.","inputSchema":{"type":"object","properties":{"mail_id":{"type":"string","format":"uuid","description":"UUID of the outbound mail job to retrieve."}},"required":["mail_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Full outbound mail job details with signed document URL.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Outbound Mail","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"create_test_outbound_mail","description":"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. Use with a sandbox key to rehearse outbound workflows before sending real physical mail.","inputSchema":{"type":"object","properties":{"recipient_name":{"type":"string","default":"Test Recipient","description":"Recipient name for the simulated mailpiece."},"recipient_line1":{"type":"string","default":"123 Test Street","description":"Recipient street line 1."},"recipient_city":{"type":"string","default":"San Francisco","description":"Recipient city."},"recipient_state":{"type":"string","default":"CA","description":"Recipient 2-letter state code."},"recipient_zip":{"type":"string","default":"94105","description":"Recipient ZIP code. Affects estimated live postage."},"mail_class":{"type":"string","enum":["first_class","priority","certified","certified_return_receipt","fedex_ground","fedex_express","fedex_2day","fedex_overnight","ups_ground","ups_2day","ups_next_day"],"default":"first_class","description":"Mail class to simulate."},"page_count":{"type":"number","default":1,"minimum":1,"maximum":100,"description":"Simulated page count used for pricing."},"color":{"type":"boolean","default":false,"description":"Whether to include color-print surcharge in the live estimate."},"agent_notes":{"type":"string","description":"Optional facility/operator notes for the simulated mailpiece."},"metadata":{"type":"object","description":"Arbitrary metadata echoed in responses and webhooks."}},"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Created sandbox outbound mail job and webhook status.","properties":{"outbound_mail":{"type":"object","description":"Outbound postal mail job summary.","properties":{"id":{"type":"string","format":"uuid","description":"Outbound mail job UUID."},"status":{"type":"string","description":"Current mail lifecycle status."},"mail_class":{"type":"string","description":"Selected postal or carrier service."},"recipient_name":{"type":"string","description":"Recipient name."},"page_count":{"type":"integer","description":"Number of printed pages."},"cost_cents":{"type":"integer","description":"Charged cost in cents, or 0 for sandbox/test records."},"tracking_number":{"type":"string","description":"Carrier tracking number when available."},"carrier":{"type":"string","description":"Carrier name when available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"test_mode":{"type":"boolean","description":"Whether this is a sandbox/test mail record."}},"additionalProperties":true},"message":{"type":"string","description":"Next step instructions for advancing the sandbox record."}},"required":["outbound_mail","message"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Create Test Outbound Mail","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}},{"name":"advance_test_outbound_mail","description":"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.","inputSchema":{"type":"object","properties":{"mail_id":{"type":"string","format":"uuid","description":"UUID of the test_mode outbound mail record to advance."}},"required":["mail_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Advanced sandbox outbound mail job and webhook status.","properties":{"outbound_mail":{"type":"object","description":"Outbound postal mail job summary.","properties":{"id":{"type":"string","format":"uuid","description":"Outbound mail job UUID."},"status":{"type":"string","description":"Current mail lifecycle status."},"mail_class":{"type":"string","description":"Selected postal or carrier service."},"recipient_name":{"type":"string","description":"Recipient name."},"page_count":{"type":"integer","description":"Number of printed pages."},"cost_cents":{"type":"integer","description":"Charged cost in cents, or 0 for sandbox/test records."},"tracking_number":{"type":"string","description":"Carrier tracking number when available."},"carrier":{"type":"string","description":"Carrier name when available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"test_mode":{"type":"boolean","description":"Whether this is a sandbox/test mail record."}},"additionalProperties":true},"message":{"type":"string","description":"Lifecycle transition and webhook status."}},"required":["outbound_mail","message"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Advance Test Outbound Mail","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false}}]}