{"server":{"name":"mailbox.bot","version":"1.0.1","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":19,"tools":[{"name":"get_mailbox","description":"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.","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":"get_usage","description":"Get usage summary, billing events, and prepaid credit balance for a time period. Returns itemized events (scans, forwards, mail sends) with costs, period totals, and credits. Defaults to the current billing period if no dates are specified. Use this in Cursor/MCP chat when the human asks how many mailbox.bot credits are left; answer with the prepaid balance and explain that only the signed-in human can add funds.","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":"object","description":"Usage summary, billing events, and prepaid credit balance.","properties":{"period":{"type":"object","description":"Requested usage period.","additionalProperties":true},"summary":{"type":"object","description":"Usage totals and event-type breakdown for the period.","additionalProperties":true},"credits":{"type":"object","description":"Current prepaid credit balance and human top-up URL.","properties":{"balance_cents":{"type":"integer","description":"Current prepaid credit balance in cents."},"balance_display":{"type":"string","description":"Human-readable prepaid credit balance."},"currency":{"type":"string","enum":["usd"],"description":"Credit balance currency."},"billing_url":{"type":"string","description":"Dashboard URL where the signed-in human can add credits."}},"required":["balance_cents","balance_display","currency","billing_url"],"additionalProperties":false},"events":{"type":"array","description":"Usage and billing event records.","items":{"type":"object","description":"One returned record.","additionalProperties":true}}},"required":["period","summary","credits","events"],"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":"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 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."},"source":{"type":"string","enum":["renter","platform_fallback"],"description":"Whether content was saved by the renter or supplied as the safe platform fallback for a blank MAILBOX.md."}},"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 Austin HQ operator managing your mailbox. Facility routing is automatic. Messages appear in the shared conversation visible to you, the renter, and the facility. Optionally link the message to a specific package or action request for context.","inputSchema":{"type":"object","properties":{"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":["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 Austin HQ conversation with its unread message count and last message preview. Facility routing is automatic.","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 Austin HQ. Facility routing is automatic. Returns messages in reverse chronological order with sender role (member, facility, agent). Supports cursor-based pagination. Automatically marks facility messages as read.","inputSchema":{"type":"object","properties":{"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."}},"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. 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 inbound.scan_available. 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. [\"mail.mailed\", \"inbound.received\"]). 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. USPS First-Class Mail has a published $2.00 one-page baseline. Extra pages add configured printing plus any postage increase from weight. If an account's normal first-page formula is lower, cost_breakdown.first_class_baseline_adjustment_cents itemizes the difference separately from carrier postage. Published default pricing for other classes is $2.50 handling + $0.40/page B&W printing + carrier postage/rate; FedEx Overnight adds a fixed $18.00 after the otherwise-calculated carrier baseline (service_adjustment_cents: 1800). 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 the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative. IMPORTANT: With a production key (sk_agent_), this spends the human member's prepaid mailbox.bot credits. Agents never access Stripe, card data, or Auto-Fill settings. If the signed-in human separately enabled Agent Auto-Fill, an eligible live order may trigger a bounded server-managed reload. Use dry_run=true to preview required credits before committing, or requires_approval=true to defer the credit debit until human approval. Sandbox keys (sk_agent_test_) skip credit debits and facility fulfillment. Responses include human_review with send-to address, return address, mail class, document details, preview URL when available, cost, safeguards, and next step; show that to the human before live funded sends. tracking_number is required for priority, certified, certified_return_receipt, FedEx, and UPS mail classes. USPS first_class does not include carrier tracking by default; tracking_number may be null. Optionally attach the outbound mail to inbound context with inbound_capture_id and postal_mail_thread_id so lineage stays explicit. Explicit Business mail runs are REST-only.","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":"Person name of the mail recipient. Optional when recipient_company is provided."},"recipient_company":{"type":"string","description":"Company or organization line for the recipient. Optional when recipient_name is provided."},"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_company":{"type":"string","description":"Optional company or organization line for the return address."},"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","fedex_ground","fedex_express","fedex_2day","fedex_overnight","ups_ground","ups_2day","ups_next_day"],"default":"first_class","description":"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. USPS First-Class Mail has a published $2.00 one-page baseline. Extra pages add configured printing plus any postage increase from weight. If an account's normal first-page formula is lower, cost_breakdown.first_class_baseline_adjustment_cents itemizes the difference separately from carrier postage. Use priority for faster USPS Priority Mail with USPS Tracking, but not Certified Mail proof; priority has a $15.00 published one-page floor. Use certified for USPS tracking plus proof of mailing/delivery; certified has a $20.00 published one-page floor. Use certified_return_receipt when electronic return-receipt evidence is required; certified_return_receipt has a $24.00 published one-page floor. Use fedex_ground or ups_ground for budget private-carrier tracking; fedex_express means FedEx Express Saver/third-business-day, fedex_2day and ups_2day mean second-business-day, and fedex_overnight or ups_next_day mean next-business-day. FedEx express classes use the Standard List document baseline from the configured fulfillment origin unless FedEx One Rate is explicitly configured operationally; fedex_overnight then adds a fixed $18.00 customer price adjustment (service_adjustment_cents: 1800). The same printing rates apply to every mail_class. 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 the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative."},"color":{"type":"boolean","default":false,"description":"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 the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative."},"duplex":{"type":"boolean","default":false,"description":"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_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 spending credits. Use to preview required credits 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 credits are spent. Prevents accidental expensive mailings."}},"required":["document_base64","mailbox_md_version","recipient_line1","recipient_city","recipient_state","recipient_zip"],"anyOf":[{"required":["recipient_name"]},{"required":["recipient_company"]}],"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","null"],"description":"Recipient name, or null when the mail is addressed to a company only."},"recipient_company":{"type":["string","null"],"description":"Optional recipient company or organization line."},"recipient_line1":{"type":"string","description":"Recipient street address line 1."},"recipient_line2":{"type":["string","null"],"description":"Recipient street address line 2."},"recipient_city":{"type":"string","description":"Recipient city."},"recipient_state":{"type":"string","description":"Recipient state."},"recipient_zip":{"type":"string","description":"Recipient ZIP code."},"recipient_country":{"type":"string","description":"Recipient country code."},"return_name":{"type":["string","null"],"description":"Return address name."},"return_company":{"type":["string","null"],"description":"Optional company or organization line for the return address."},"return_line1":{"type":["string","null"],"description":"Return address street line 1."},"return_line2":{"type":["string","null"],"description":"Return address street line 2."},"return_city":{"type":["string","null"],"description":"Return address city."},"return_state":{"type":["string","null"],"description":"Return address state."},"return_zip":{"type":["string","null"],"description":"Return address ZIP."},"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."},"error_message":{"type":["string","null"],"description":"Failure reason when status is failed and a reason is available."},"carrier_delivery_failed":{"type":"boolean","description":"True only when status=failed because a mailed/tracked carrier item later failed delivery."},"failure_stage":{"type":["string","null"],"enum":["carrier_delivery",null],"description":"carrier_delivery for carrier delivery failures; null for submission or fulfillment failures."},"failure_source":{"type":["string","null"],"enum":["fedex_tracking",null],"description":"fedex_tracking when FedEx Track reported the carrier delivery failure; null otherwise."},"mailed_at":{"type":["string","null"],"description":"Timestamp when the item entered the carrier/mail stream."},"delivered_at":{"type":["string","null"],"description":"Timestamp when delivery was confirmed, if available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"document_preview_url":{"type":["string","null"],"format":"uri","description":"Authenticated dashboard URL a human can click to visually verify the submitted source document."},"cost_breakdown":{"type":"object","description":"Authoritative cost components. For color jobs, color_printing_per_page_cents is the total color-page printing price (70 cents by published default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by published default). For a below-formula First-Class quote, first_class_baseline_adjustment_cents is the amount added to reach the published $2.00 one-page baseline and is separate from postage_cents.","additionalProperties":true},"human_review":{"type":"object","description":"Human-readable review payload for CLI/chat confirmation: send-to address, return address, mail class, document preview URL, cost, safeguards, and next step.","additionalProperties":true},"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. For color jobs, color_printing_per_page_cents is the total color-page printing price (70 cents by published default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by published default). For a below-formula First-Class quote, first_class_baseline_adjustment_cents is the amount added to reach the published $2.00 one-page baseline and is separate from postage_cents.","additionalProperties":true}},"required":[],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Send Outbound Mail","readOnlyHint":false,"destructiveHint":true,"idempotentHint":false,"openWorldHint":true}},{"name":"list_outbound_mail","description":"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.","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\" = failure bucket, \"cancelled\" = cancelled before mailing. Use carrier_delivery_failed/failure_stage to identify mailed carrier delivery failures."},"q":{"type":"string","description":"Search recipient name, address lines, city/state/ZIP, tracking number, or agent notes."},"created_after":{"type":"string","description":"Filter mail created at or after this ISO 8601 datetime or YYYY-MM-DD date."},"created_before":{"type":"string","description":"Filter mail created at or before this ISO 8601 datetime or YYYY-MM-DD date. Date-only values include the whole UTC day."},"test_mode":{"type":"boolean","description":"Filter sandbox/test records. Defaults to the key environment for agent-scoped keys; member keys can pass true or false explicitly."},"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","null"],"description":"Recipient name, or null when the mail is addressed to a company only."},"recipient_company":{"type":["string","null"],"description":"Optional recipient company or organization line."},"recipient_line1":{"type":"string","description":"Recipient street address line 1."},"recipient_line2":{"type":["string","null"],"description":"Recipient street address line 2."},"recipient_city":{"type":"string","description":"Recipient city."},"recipient_state":{"type":"string","description":"Recipient state."},"recipient_zip":{"type":"string","description":"Recipient ZIP code."},"recipient_country":{"type":"string","description":"Recipient country code."},"return_name":{"type":["string","null"],"description":"Return address name."},"return_company":{"type":["string","null"],"description":"Optional company or organization line for the return address."},"return_line1":{"type":["string","null"],"description":"Return address street line 1."},"return_line2":{"type":["string","null"],"description":"Return address street line 2."},"return_city":{"type":["string","null"],"description":"Return address city."},"return_state":{"type":["string","null"],"description":"Return address state."},"return_zip":{"type":["string","null"],"description":"Return address ZIP."},"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."},"error_message":{"type":["string","null"],"description":"Failure reason when status is failed and a reason is available."},"carrier_delivery_failed":{"type":"boolean","description":"True only when status=failed because a mailed/tracked carrier item later failed delivery."},"failure_stage":{"type":["string","null"],"enum":["carrier_delivery",null],"description":"carrier_delivery for carrier delivery failures; null for submission or fulfillment failures."},"failure_source":{"type":["string","null"],"enum":["fedex_tracking",null],"description":"fedex_tracking when FedEx Track reported the carrier delivery failure; null otherwise."},"mailed_at":{"type":["string","null"],"description":"Timestamp when the item entered the carrier/mail stream."},"delivered_at":{"type":["string","null"],"description":"Timestamp when delivery was confirmed, if available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"document_preview_url":{"type":["string","null"],"format":"uri","description":"Authenticated dashboard URL a human can click to visually verify the submitted source document."},"cost_breakdown":{"type":"object","description":"Authoritative cost components. For color jobs, color_printing_per_page_cents is the total color-page printing price (70 cents by published default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by published default). For a below-formula First-Class quote, first_class_baseline_adjustment_cents is the amount added to reach the published $2.00 one-page baseline and is separate from postage_cents.","additionalProperties":true},"human_review":{"type":"object","description":"Human-readable review payload for CLI/chat confirmation: send-to address, return address, mail class, document preview URL, cost, safeguards, and next step.","additionalProperties":true},"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, failure metadata, document metadata, and fulfillment photos. Legacy plaintext records may include direct document URLs; encrypted source documents are retrieved through the REST document endpoint with document.read scope.","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. Direct document URLs are only present for legacy plaintext rows.","additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Get Outbound Mail","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false}},{"name":"cancel_outbound_mail","description":"Cancel a queued outbound mail job before facility printing starts. If the mail was funded with prepaid credits, eligible credits are returned to the member ledger. Safe to retry: already-cancelled mail returns cancelled status without creating a duplicate refund. In chat, report cancellation status, returned credits, updated balance, and whether it had already been cancelled. If a transient error occurs, poll the mail status and credits before retrying.","inputSchema":{"type":"object","properties":{"mail_id":{"type":"string","format":"uuid","description":"UUID of the queued outbound mail job to cancel."}},"required":["mail_id"],"additionalProperties":false},"outputSchema":{"type":"object","properties":{"result":{"type":"object","description":"Cancelled queued outbound mail and returned credits when eligible.","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","null"],"description":"Recipient name, or null when the mail is addressed to a company only."},"recipient_company":{"type":["string","null"],"description":"Optional recipient company or organization line."},"recipient_line1":{"type":"string","description":"Recipient street address line 1."},"recipient_line2":{"type":["string","null"],"description":"Recipient street address line 2."},"recipient_city":{"type":"string","description":"Recipient city."},"recipient_state":{"type":"string","description":"Recipient state."},"recipient_zip":{"type":"string","description":"Recipient ZIP code."},"recipient_country":{"type":"string","description":"Recipient country code."},"return_name":{"type":["string","null"],"description":"Return address name."},"return_company":{"type":["string","null"],"description":"Optional company or organization line for the return address."},"return_line1":{"type":["string","null"],"description":"Return address street line 1."},"return_line2":{"type":["string","null"],"description":"Return address street line 2."},"return_city":{"type":["string","null"],"description":"Return address city."},"return_state":{"type":["string","null"],"description":"Return address state."},"return_zip":{"type":["string","null"],"description":"Return address ZIP."},"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."},"error_message":{"type":["string","null"],"description":"Failure reason when status is failed and a reason is available."},"carrier_delivery_failed":{"type":"boolean","description":"True only when status=failed because a mailed/tracked carrier item later failed delivery."},"failure_stage":{"type":["string","null"],"enum":["carrier_delivery",null],"description":"carrier_delivery for carrier delivery failures; null for submission or fulfillment failures."},"failure_source":{"type":["string","null"],"enum":["fedex_tracking",null],"description":"fedex_tracking when FedEx Track reported the carrier delivery failure; null otherwise."},"mailed_at":{"type":["string","null"],"description":"Timestamp when the item entered the carrier/mail stream."},"delivered_at":{"type":["string","null"],"description":"Timestamp when delivery was confirmed, if available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"document_preview_url":{"type":["string","null"],"format":"uri","description":"Authenticated dashboard URL a human can click to visually verify the submitted source document."},"cost_breakdown":{"type":"object","description":"Authoritative cost components. For color jobs, color_printing_per_page_cents is the total color-page printing price (70 cents by published default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by published default). For a below-formula First-Class quote, first_class_baseline_adjustment_cents is the amount added to reach the published $2.00 one-page baseline and is separate from postage_cents.","additionalProperties":true},"human_review":{"type":"object","description":"Human-readable review payload for CLI/chat confirmation: send-to address, return address, mail class, document preview URL, cost, safeguards, and next step.","additionalProperties":true},"test_mode":{"type":"boolean","description":"Whether this is a sandbox/test mail record."}},"additionalProperties":true},"refunded_credits_cents":{"type":"integer","description":"Prepaid credits returned in cents. Zero when nothing was spent or the mail was already cancelled."},"credit_balance_cents":{"type":["integer","null"],"description":"Credit balance after cancellation when available."},"already_cancelled":{"type":"boolean","description":"True when the mail had already been cancelled by a previous request."}},"required":["outbound_mail","refunded_credits_cents","already_cancelled"],"additionalProperties":true}},"required":["result"],"additionalProperties":false},"annotations":{"title":"Cancel Outbound Mail","readOnlyHint":false,"destructiveHint":true,"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. USPS First-Class Mail has a published $2.00 one-page baseline. Extra pages add configured printing plus any postage increase from weight. If an account's normal first-page formula is lower, cost_breakdown.first_class_baseline_adjustment_cents itemizes the difference separately from carrier postage. 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 the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative. FedEx and UPS estimates use the same configured origin and destination zone/region logic as production; FedEx Overnight adds a fixed $18.00 after the otherwise-calculated carrier baseline and reports service_adjustment_cents: 1800. 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. Optional when recipient_company is provided."},"recipient_company":{"type":"string","description":"Company or organization line for the simulated mailpiece. Optional when recipient_name is provided."},"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, private-carrier zone, and FedEx local/regional/national area."},"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. 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. USPS First-Class Mail has a published $2.00 one-page baseline. Extra pages add configured printing plus any postage increase from weight. If an account's normal first-page formula is lower, cost_breakdown.first_class_baseline_adjustment_cents itemizes the difference separately from carrier postage. Use priority for faster USPS Priority Mail with USPS Tracking, but not Certified Mail proof; priority has a $15.00 published one-page floor. Use certified for USPS tracking plus proof of mailing/delivery; certified has a $20.00 published one-page floor. Use certified_return_receipt when electronic return-receipt evidence is required; certified_return_receipt has a $24.00 published one-page floor. Use fedex_ground or ups_ground for budget private-carrier tracking; fedex_express means FedEx Express Saver/third-business-day, fedex_2day and ups_2day mean second-business-day, and fedex_overnight or ups_next_day mean next-business-day. FedEx express classes use the Standard List document baseline from the configured fulfillment origin unless FedEx One Rate is explicitly configured operationally; fedex_overnight then adds a fixed $18.00 customer price adjustment (service_adjustment_cents: 1800). The same printing rates apply to every mail_class. 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 the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative."},"page_count":{"type":"number","default":1,"minimum":1,"maximum":100,"description":"Simulated page count used for pricing."},"color":{"type":"boolean","default":false,"description":"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 the total color-page printing price (70 cents by default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by default). Account-specific pricing can override these defaults; cost_breakdown is authoritative."},"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","null"],"description":"Recipient name, or null when the mail is addressed to a company only."},"recipient_company":{"type":["string","null"],"description":"Optional recipient company or organization line."},"recipient_line1":{"type":"string","description":"Recipient street address line 1."},"recipient_line2":{"type":["string","null"],"description":"Recipient street address line 2."},"recipient_city":{"type":"string","description":"Recipient city."},"recipient_state":{"type":"string","description":"Recipient state."},"recipient_zip":{"type":"string","description":"Recipient ZIP code."},"recipient_country":{"type":"string","description":"Recipient country code."},"return_name":{"type":["string","null"],"description":"Return address name."},"return_company":{"type":["string","null"],"description":"Optional company or organization line for the return address."},"return_line1":{"type":["string","null"],"description":"Return address street line 1."},"return_line2":{"type":["string","null"],"description":"Return address street line 2."},"return_city":{"type":["string","null"],"description":"Return address city."},"return_state":{"type":["string","null"],"description":"Return address state."},"return_zip":{"type":["string","null"],"description":"Return address ZIP."},"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."},"error_message":{"type":["string","null"],"description":"Failure reason when status is failed and a reason is available."},"carrier_delivery_failed":{"type":"boolean","description":"True only when status=failed because a mailed/tracked carrier item later failed delivery."},"failure_stage":{"type":["string","null"],"enum":["carrier_delivery",null],"description":"carrier_delivery for carrier delivery failures; null for submission or fulfillment failures."},"failure_source":{"type":["string","null"],"enum":["fedex_tracking",null],"description":"fedex_tracking when FedEx Track reported the carrier delivery failure; null otherwise."},"mailed_at":{"type":["string","null"],"description":"Timestamp when the item entered the carrier/mail stream."},"delivered_at":{"type":["string","null"],"description":"Timestamp when delivery was confirmed, if available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"document_preview_url":{"type":["string","null"],"format":"uri","description":"Authenticated dashboard URL a human can click to visually verify the submitted source document."},"cost_breakdown":{"type":"object","description":"Authoritative cost components. For color jobs, color_printing_per_page_cents is the total color-page printing price (70 cents by published default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by published default). For a below-formula First-Class quote, first_class_baseline_adjustment_cents is the amount added to reach the published $2.00 one-page baseline and is separate from postage_cents.","additionalProperties":true},"human_review":{"type":"object","description":"Human-readable review payload for CLI/chat confirmation: send-to address, return address, mail class, document preview URL, cost, safeguards, and next step.","additionalProperties":true},"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 carrier, dispatch method, receipt photo, and tracking when the selected service includes tracking; 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","null"],"description":"Recipient name, or null when the mail is addressed to a company only."},"recipient_company":{"type":["string","null"],"description":"Optional recipient company or organization line."},"recipient_line1":{"type":"string","description":"Recipient street address line 1."},"recipient_line2":{"type":["string","null"],"description":"Recipient street address line 2."},"recipient_city":{"type":"string","description":"Recipient city."},"recipient_state":{"type":"string","description":"Recipient state."},"recipient_zip":{"type":"string","description":"Recipient ZIP code."},"recipient_country":{"type":"string","description":"Recipient country code."},"return_name":{"type":["string","null"],"description":"Return address name."},"return_company":{"type":["string","null"],"description":"Optional company or organization line for the return address."},"return_line1":{"type":["string","null"],"description":"Return address street line 1."},"return_line2":{"type":["string","null"],"description":"Return address street line 2."},"return_city":{"type":["string","null"],"description":"Return address city."},"return_state":{"type":["string","null"],"description":"Return address state."},"return_zip":{"type":["string","null"],"description":"Return address ZIP."},"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."},"error_message":{"type":["string","null"],"description":"Failure reason when status is failed and a reason is available."},"carrier_delivery_failed":{"type":"boolean","description":"True only when status=failed because a mailed/tracked carrier item later failed delivery."},"failure_stage":{"type":["string","null"],"enum":["carrier_delivery",null],"description":"carrier_delivery for carrier delivery failures; null for submission or fulfillment failures."},"failure_source":{"type":["string","null"],"enum":["fedex_tracking",null],"description":"fedex_tracking when FedEx Track reported the carrier delivery failure; null otherwise."},"mailed_at":{"type":["string","null"],"description":"Timestamp when the item entered the carrier/mail stream."},"delivered_at":{"type":["string","null"],"description":"Timestamp when delivery was confirmed, if available."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp."},"document_preview_url":{"type":["string","null"],"format":"uri","description":"Authenticated dashboard URL a human can click to visually verify the submitted source document."},"cost_breakdown":{"type":"object","description":"Authoritative cost components. For color jobs, color_printing_per_page_cents is the total color-page printing price (70 cents by published default), while color_surcharge_per_page_cents is the additive upgrade only (30 cents by published default). For a below-formula First-Class quote, first_class_baseline_adjustment_cents is the amount added to reach the published $2.00 one-page baseline and is separate from postage_cents.","additionalProperties":true},"human_review":{"type":"object","description":"Human-readable review payload for CLI/chat confirmation: send-to address, return address, mail class, document preview URL, cost, safeguards, and next step.","additionalProperties":true},"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}}]}