send_outbound_mail
Submit a PDF, DOCX, JPG, PNG, TXT, or CSV document for secure printing and postal mailing, with cost preview and optional human approval before credits are spent.
Instructions
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 Express Saver, 2Day and Overnight are $5.00 below their otherwise-calculated carrier baselines: fedex_express itemizes service_adjustment_cents: -500, FedEx 2Day applies a fixed $13.00 customer price reduction (service_adjustment_cents: -1300), and FedEx Overnight adds a fixed $13.00 adjustment (service_adjustment_cents: 1300); fedex_ground carries a fixed $5.00 markup (service_adjustment_cents: 500). 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
| 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. 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_express, fedex_2day and fedex_overnight are then $5.00 below that baseline: fedex_express itemizes service_adjustment_cents: -500, fedex_2day applies a fixed $13.00 customer price reduction (service_adjustment_cents: -1300), and fedex_overnight adds a fixed $13.00 customer price adjustment (service_adjustment_cents: 1300); fedex_ground carries a fixed $5.00 markup over its baseline (service_adjustment_cents: 500). 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 | Notes for the facility staff (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 mail waits for the renter's approval in their dashboard before it is printed and sent. | |
| delivery_signature | No | Optional signature on delivery for a single letter (batch mail has none). FedEx classes: indirect (FedEx Indirect Signature Required, $8.00: someone at the address, a neighbor, or the recipient on a signed door tag); direct (FedEx Direct Signature Required, $8.50: someone at the address); adult (FedEx Adult Signature Required, $11.00: an adult 21 or older at the address, with ID). priority: direct (USPS Signature Confirmation, $5.00: someone at the address); adult (USPS Adult Signature Required, $11.00: an adult 21 or older at the address, with ID). certified and certified_return_receipt: restricted (USPS Restricted Delivery, $10.00: only the addressee, or an agent they authorized in writing). first_class has no signature service. Omit it or send none for no signature. The fee is added to the price and itemized as cost_breakdown.delivery_signature_cents. | |
| 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 number. 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
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes | Submitted outbound mail job or dry-run cost preview. |