send_outbound_mail
Print and mail documents as physical letters via USPS. Supports PDF, DOCX, images, and more with certified mail, cost caps, and dry-run preview.
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. 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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | Print in color. Adds a per-page color surcharge. | |
| duplex | No | Print double-sided to reduce page count and postage. | |
| dry_run | No | Validate inputs and return cost breakdown without creating a record or charging. Use to preview cost 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 | 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. | 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 any charge. Prevents accidental expensive mailings. | |
| recipient_city | Yes | Recipient city. | |
| recipient_name | Yes | Full name of the mail recipient. | |
| 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_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. |