send_outbound_mail

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