send_text_letter
Destructive
Mail a letter written as plain text, for letters composed in chat. mailbox.bot sets the text exactly as given on US Letter pages (Times 12 pt, 1-inch margins; no letterhead, logo or signature image) and submits it through send_outbound_mail, so the same scopes, approval, cost caps and proof apply and staff print and mail it. Run with dry_run: true first to see the exact cost; with a live key this spends the account owner's prepaid credits, and a key that requires approval holds the letter until the owner approves it in the dashboard. Requires mailbox_md_version from get_mailbox_md. Up to 15,000 characters of Latin text. For a PDF, letterhead or images, use send_outbound_mail.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | true returns the exact cost and checks without creating, charging or mailing anything. | |
| metadata | No | Your own reference fields, echoed back in status and webhooks. | |
| mail_class | Yes | USPS: first_class (no carrier tracking; mailbox.bot records photo proof), priority (USPS Tracking), certified (USPS tracking plus proof of mailing and delivery), certified_return_receipt (certified plus electronic return receipt). FedEx: fedex_ground, fedex_express (Express Saver, about 3 business days), fedex_2day, fedex_overnight. | |
| return_zip | No | Return ZIP code. | |
| agent_notes | No | Notes for the owner and the facility. | |
| letter_text | Yes | The full letter as plain text: date, greeting, body and sign-off as they should print. Line breaks are kept. | |
| return_city | No | Return city. | |
| return_name | No | Return name. Defaults to the account's saved return address. | |
| return_line1 | No | Return street address. Defaults to the account's saved return address. | |
| return_line2 | No | Return suite or unit. | |
| return_state | No | Return state, 2 letters. | |
| recipient_zip | Yes | Recipient ZIP code. | |
| max_cost_cents | No | Refuse the letter if it would cost more than this, in cents. | |
| recipient_city | Yes | Recipient city. | |
| recipient_name | No | Recipient name. | |
| return_company | No | Return company line. | |
| recipient_line1 | Yes | Recipient street address. | |
| recipient_line2 | No | Suite, unit or floor. | |
| recipient_state | Yes | Recipient state, 2 letters. | |
| recipient_company | No | Recipient company or organization line. | |
| requires_approval | No | true holds the letter until the owner approves it in the dashboard. | |
| 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. | |
| mailbox_md_version | Yes | Current MAILBOX.md version from get_mailbox_md. Required. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes | The send_outbound_mail result: status, cost breakdown, human review and next step. |