| 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. | |
