mailbox

send_outbound_mail

Destructive

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.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`color`	No	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`	No	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.
`dry_run`	No	Validate inputs and return cost breakdown without creating a record or spending credits. Use to preview required credits before committing.
`metadata`	No	Arbitrary key-value pairs echoed in GET responses and webhooks. Recommended convention: { "workflow_id": "wf_123", "reason": "Customer cancellation", "correlation_id": "abc" }.
`mail_class`	No	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.	first_class
`package_id`	No	Link this mail to an inbound package (e.g. replying to received correspondence).
`page_count`	No	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.
`return_zip`	No	Return address ZIP code. Defaults to member profile if omitted.
`agent_notes`	No	Instructions for the facility operator (e.g. "Time-sensitive — mail today").
`return_city`	No	Return address city. Defaults to member profile if omitted.
`return_name`	No	Return address name. Defaults to the member's profile name if omitted.
`return_line1`	No	Return address line 1. Defaults to member profile if omitted.
`return_line2`	No	Return address line 2 (suite, unit, etc.).
`return_state`	No	Return address state (2-letter code). Defaults to member profile if omitted.
`recipient_zip`	Yes	5 or 5+4 digit ZIP code (e.g. "90210" or "90210-1234").
`max_cost_cents`	No	Cost cap in cents. If the calculated cost exceeds this, the request is rejected with 422 before credits are spent. Prevents accidental expensive mailings.
`recipient_city`	Yes	Recipient city.
`recipient_name`	No	Person name of the mail recipient. Optional when recipient_company is provided.
`return_company`	No	Optional company or organization line for the return address.
`document_base64`	Yes	Base64-encoded document file. Supported formats: PDF, DOCX, JPG, PNG, TXT, CSV. Max 10MB decoded.
`recipient_line1`	Yes	Street address line 1 of the recipient.
`recipient_line2`	No	Street address line 2 (apartment, suite, unit, etc.).
`recipient_state`	Yes	2-letter US state code (e.g. CA, NY, TX).
`document_filename`	No	Original filename with extension (e.g. "letter.docx"). Required for reliable non-PDF format detection.
`recipient_company`	No	Company or organization line for the recipient. Optional when recipient_name is provided.
`recipient_country`	No	ISO 3166-1 alpha-2 country code. Defaults to "US".	US
`requires_approval`	No	If true, the renter must approve in their dashboard before the mail is printed and sent.
`inbound_capture_id`	No	Optional inbound mail item this outbound piece is replying to. Recommended when drafting from OCR/forwarded-mail context.
`mailbox_md_version`	Yes	Your current MAILBOX.md version (from get_mailbox_md). Required for sync verification.
`postal_mail_thread_id`	No	Optional physical-mail thread to attach this outbound mail to. Lets agents keep inbound and outbound activity in one durable workflow.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes	Submitted outbound mail job or dry-run cost preview.

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses material behaviors far beyond the annotations' destructiveHint=true: production keys spend prepaid mailbox.bot credits, agents never access Stripe/card data/Auto-Fill, a server-managed reload may trigger, and sandbox keys skip debits and fulfillment. This is exactly the kind of high-stakes context an agent needs before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core action and the IMPORTANT credit-spending warning are front-loaded, which is good. However, the description is roughly 20 sentences and repeats pricing prose that already exists in the schema, so several sentences could be trimmed without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 30 parameters and an output schema, the description covers nearly every operational hazard: formats, default pricing, credit debits, approval flow, sandbox behavior, tracking requirements, and lineage attachment. The only notable gap is the cryptic closing note 'Explicit Business mail runs are REST-only,' which is ambiguous.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline applies. The description adds the credit-cost framing and tracking-number constraints, but much of its pricing content is duplicated verbatim in the mail_class and color parameter descriptions, so it does not meaningfully extend parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a precise verb+resource: 'Submit a document for printing and postal mailing by the facility,' and immediately lists the supported formats. This clearly distinguishes the physical-mail-sending action from siblings like send_facility_message and the test outbound mail tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides rich usage context: dry_run=true to preview credits, requires_approval=true to defer the debit, sandbox key behavior, and when tracking_number is mandatory. It does not name sibling alternatives (e.g., create_test_outbound_mail for test sends), so it lacks explicit when-not-to-use guidance, but the conditions for safe use are well conveyed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All mailbox tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.1/5.0

Disambiguation4/5

Most tools map cleanly to distinct resources and actions, forming clear list/get pairs for outbound mail, inbound mail, and postal threads. The main ambiguity is between get_facility_messages and list_facility_conversations, which both target the same Austin HQ conversation, and get_mailbox versus list_inbound_forwarding_addresses are closely related address lookups.

Naming Consistency5/5

All tool names use a consistent lowercase snake_case verb_noun pattern with familiar verbs like get, list, send, cancel, create, update, and propose. There are no mixed naming conventions or vague generic names.

Tool Count3/5

19 tools is within the 16-25 range that feels heavy for a single-domain MCP server. The broad outbound/inbound lifecycle, threads, facility messaging, MAILBOX.md, usage, and webhook support justify much of the count, but a few tools such as the facility conversation list/get pair could reasonably be consolidated.

Completeness4/5

The tool surface covers the core physical mail workflow well: test and real outbound sends, cancellation, inbound forwarding and retrieval, postal threads, facility communication, MAILBOX.md sync, usage, and webhooks. Minor gaps exist around webhook inspection/removal and direct document download, but these are unlikely to cause agent dead-ends in the main workflows.

Resources

Need Help?