{"openapi":"3.1.0","info":{"title":"PostalForm Machine Payments API","version":"1.0.0","description":"Machine-oriented print-and-mail endpoints for x402 and MPP payment flows.\n\nUse OpenAPI as the canonical discovery source for this origin. The /.well-known/x402 manifest is a lightweight compatibility layer for crawlers and agent runtimes that do not yet ingest the full OpenAPI document.\n\nFor both machine payment families, call the validate endpoint first to verify the payload and get a quote before attempting payment.\n\nWhen retrying a create call after a 402 challenge, reuse the same request_id and the exact same JSON body. PostalForm treats request_id as the strict idempotency key and rejects payload drift for that request_id.\n\nIf you intend to send the same document to the same addresses again after a prior order is paid or settled, generate a fresh request_id. PostalForm only collapses recent unpaid duplicate drafts.\n\nFor each address party, choose exactly one strategy: Address with *_address_id and *_address_text, or Manual with *_address_manual. Do not send both strategies for the same party.\n\nAddress countries default to US when omitted. For international manual addresses, include countryCode; for Loqate addresses, the id prefix carries the country.\n\nPrefer pdf as { \"upload_token\": \"...\" } when you already have a finished PDF. The create endpoint also accepts { download_url, file_id }, a data:application/pdf;base64 URL, or an allowlisted HTTPS URL.\n\nFor server-rendered letters, send a top-level letter value instead of pdf. letter may be a string or an object with body, title, signature, render options, and format. signature may be a string or { mode: \"typed\" | \"drawn\", text?, dataUrl?, printDataUrl? }. format can be text, html, markdown, or rtf; default is text.\n\nUnpaid single-recipient create responses may include preview_url, a signed short-lived URL for reviewing the generated or uploaded PDF before payment.\n\nFor structured workflow forms, discover forms with GET /api/machine/forms, fetch GET /api/machine/forms/{slug}/schema, then send a top-level form object instead of pdf or letter to the same create/validate endpoints.\n\nFor bulk mailing campaigns, send a bulk object instead of recipient_name and recipient address fields. bulk.csv_content holds the recipient CSV, bulk.content_mode selects text, html, or pdf rendering, and validation returns bulk.recipient_count plus bulk.content_mode.\n\nBulk machine create and poll responses may include campaign_url. Use that route to inspect row-level mailed-item status, delivery events, and tracking for each CSV recipient.\n\nFor flower letters, use the dedicated /api/machine/flower-letters or /api/machine/mpp/flower-letters endpoints. They require a Florist One product code, recipient ZIP, delivery date, full delivery address, and a 200-character card note.\n\nFor postcards, keep using the same endpoints and payment flow. Set mailpiece_type to postcard, provide postcard_size, and supply pdf as the fully composed postcard PDF. Lob-routed international postcards require postcard_size=\"4x6\" and a U.S. sender/return address; larger international postcards or international postcards with non-U.S. return addresses route to PostGrid before provider submission. See https://postalform.com/postcard-pdf-guidelines for the required 2-page bleed templates and mailing-side layout.\n\nUse POST /api/machine/orders for x402. The server returns 402 with PAYMENT-REQUIRED and expects PAYMENT-SIGNATURE on retry.\n\nUse POST /api/machine/mpp/orders for MPP. The server returns 402 with one or more WWW-Authenticate: Payment challenges and expects Authorization: Payment on retry.\n\nPoll GET /api/machine/orders/{id} or GET /api/machine/mpp/orders/{id} until payment_status becomes paid or the order reaches its terminal status. Those status endpoints accept either the canonical order_id or any aliased request_id returned during create/validate.","license":{"name":"Proprietary","url":"https://postalform.com/terms"},"x-agent-guidance":"Use OpenAPI as the canonical discovery source for this origin. The /.well-known/x402 manifest is a lightweight compatibility layer for crawlers and agent runtimes that do not yet ingest the full OpenAPI document.\n\nFor both machine payment families, call the validate endpoint first to verify the payload and get a quote before attempting payment.\n\nWhen retrying a create call after a 402 challenge, reuse the same request_id and the exact same JSON body. PostalForm treats request_id as the strict idempotency key and rejects payload drift for that request_id.\n\nIf you intend to send the same document to the same addresses again after a prior order is paid or settled, generate a fresh request_id. PostalForm only collapses recent unpaid duplicate drafts.\n\nFor each address party, choose exactly one strategy: Address with *_address_id and *_address_text, or Manual with *_address_manual. Do not send both strategies for the same party.\n\nAddress countries default to US when omitted. For international manual addresses, include countryCode; for Loqate addresses, the id prefix carries the country.\n\nPrefer pdf as { \"upload_token\": \"...\" } when you already have a finished PDF. The create endpoint also accepts { download_url, file_id }, a data:application/pdf;base64 URL, or an allowlisted HTTPS URL.\n\nFor server-rendered letters, send a top-level letter value instead of pdf. letter may be a string or an object with body, title, signature, render options, and format. signature may be a string or { mode: \"typed\" | \"drawn\", text?, dataUrl?, printDataUrl? }. format can be text, html, markdown, or rtf; default is text.\n\nUnpaid single-recipient create responses may include preview_url, a signed short-lived URL for reviewing the generated or uploaded PDF before payment.\n\nFor structured workflow forms, discover forms with GET /api/machine/forms, fetch GET /api/machine/forms/{slug}/schema, then send a top-level form object instead of pdf or letter to the same create/validate endpoints.\n\nFor bulk mailing campaigns, send a bulk object instead of recipient_name and recipient address fields. bulk.csv_content holds the recipient CSV, bulk.content_mode selects text, html, or pdf rendering, and validation returns bulk.recipient_count plus bulk.content_mode.\n\nBulk machine create and poll responses may include campaign_url. Use that route to inspect row-level mailed-item status, delivery events, and tracking for each CSV recipient.\n\nFor flower letters, use the dedicated /api/machine/flower-letters or /api/machine/mpp/flower-letters endpoints. They require a Florist One product code, recipient ZIP, delivery date, full delivery address, and a 200-character card note.\n\nFor postcards, keep using the same endpoints and payment flow. Set mailpiece_type to postcard, provide postcard_size, and supply pdf as the fully composed postcard PDF. Lob-routed international postcards require postcard_size=\"4x6\" and a U.S. sender/return address; larger international postcards or international postcards with non-U.S. return addresses route to PostGrid before provider submission. See https://postalform.com/postcard-pdf-guidelines for the required 2-page bleed templates and mailing-side layout.\n\nUse POST /api/machine/orders for x402. The server returns 402 with PAYMENT-REQUIRED and expects PAYMENT-SIGNATURE on retry.\n\nUse POST /api/machine/mpp/orders for MPP. The server returns 402 with one or more WWW-Authenticate: Payment challenges and expects Authorization: Payment on retry.\n\nPoll GET /api/machine/orders/{id} or GET /api/machine/mpp/orders/{id} until payment_status becomes paid or the order reaches its terminal status. Those status endpoints accept either the canonical order_id or any aliased request_id returned during create/validate."},"security":[],"servers":[{"url":"https://postalform.com"}],"paths":{"/api/machine/forms":{"get":{"operationId":"listMachineForms","summary":"List workflow forms available to machine order flows","description":"Search published PostalForm workflow forms that agents can fill and submit through the x402 or MPP machine order endpoints.","parameters":[{"name":"q","in":"query","required":false,"description":"Optional slug/name search string.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1 to 200. Defaults to 50.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"Cursor returned by the previous list response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Machine workflow form catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineWorkflowFormListResponse"}}}},"400":{"description":"Invalid form catalog query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/forms/{slug}/schema":{"get":{"operationId":"getMachineFormSchema","summary":"Get a machine-usable workflow form schema","parameters":[{"name":"slug","in":"path","required":true,"description":"Workflow form slug from GET /api/machine/forms.","schema":{"type":"string"}}],"responses":{"200":{"description":"Machine workflow form schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineWorkflowFormSchema"}}}},"404":{"description":"Form not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/orders/validate":{"post":{"operationId":"validateMachineOrder","summary":"Validate an x402 machine order and return a quote","requestBody":{"required":true,"description":"Quote and validate an x402 machine order without triggering payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}}}}}},"responses":{"200":{"description":"Validation succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderValidationResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/orders":{"post":{"operationId":"createMachineOrder","summary":"Create or reuse an x402 machine order","description":"Unauthenticated calls return 402 Payment Required when the order is ready to be paid. Retry the exact same body with PAYMENT-SIGNATURE after settlement.","requestBody":{"required":true,"description":"Create or reuse an x402 machine order. Reuse the same request_id and identical JSON body after a 402 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}}}}}},"x-payment-info":{"protocols":["x402"],"pricingMode":"range","minPrice":"3.40","maxPrice":"200.00"},"responses":{"200":{"description":"Existing machine order is already paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrder"}}}},"202":{"description":"Payment settled and order is pending finalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrder"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/X402PaymentRequiredResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/orders/{id}":{"get":{"operationId":"getMachineOrder","summary":"Get x402 machine order status","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical order_id or any aliased request_id returned by the create or validate call.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Machine order status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderStatus"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/flower-letters/validate":{"post":{"operationId":"validateMachineFlowerLetter","summary":"Validate an x402 flower-letter order and return a Florist One quote","requestBody":{"required":true,"description":"Quote and validate a dedicated flower-letter order without triggering payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","note":"For your desk, your day, and the smile I hope this brings.","zipcode":"32503","product_code":"F1-509","delivery_date":"2026-05-08","customer":{"name":"Agent Owner","phone":"8505550100","address1":"123 Sender St","city":"Pensacola","state":"FL","zipcode":"32503","country":"US","email":"owner@example.com"},"recipient":{"name":"Recipient Example","phone":"8505550199","address1":"456 Recipient Ave","city":"Pensacola","state":"FL","zipcode":"32503","country":"US"},"allow_substitutions":true}}}}}},"responses":{"200":{"description":"Validation succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterValidationResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/flower-letters":{"post":{"operationId":"createMachineFlowerLetter","summary":"Create or reuse an x402 flower-letter order","description":"Unauthenticated calls return 402 Payment Required after PostalForm validates the Florist One product, delivery ZIP, delivery date, and final quote.","requestBody":{"required":true,"description":"Create or reuse a dedicated x402 flower-letter order. Reuse the same request_id and identical JSON body after a 402 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","note":"For your desk, your day, and the smile I hope this brings.","zipcode":"32503","product_code":"F1-509","delivery_date":"2026-05-08","customer":{"name":"Agent Owner","phone":"8505550100","address1":"123 Sender St","city":"Pensacola","state":"FL","zipcode":"32503","country":"US","email":"owner@example.com"},"recipient":{"name":"Recipient Example","phone":"8505550199","address1":"456 Recipient Ave","city":"Pensacola","state":"FL","zipcode":"32503","country":"US"},"allow_substitutions":true}}}}}},"x-payment-info":{"protocols":["x402"],"pricingMode":"dynamic","minPrice":"1.00","maxPrice":"250.00"},"responses":{"200":{"description":"Existing flower-letter order is already paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"202":{"description":"Payment settled and provider submission is queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowerLetterPaymentRequiredResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/flower-letters/{id}":{"get":{"operationId":"getMachineFlowerLetter","summary":"Get x402 flower-letter order status","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical order_id or any aliased request_id returned by the create or validate call.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Flower-letter order status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/orders/validate":{"post":{"operationId":"validateMppMachineOrder","summary":"Validate an MPP machine order and return a quote","requestBody":{"required":true,"description":"Quote and validate an MPP machine order without triggering payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}}}}}},"responses":{"200":{"description":"Validation succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderValidationResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/orders":{"post":{"operationId":"createMppMachineOrder","summary":"Create or reuse an MPP machine order","description":"Unauthenticated calls return 402 Payment Required with WWW-Authenticate: Payment challenges. Retry the exact same body with Authorization: Payment after settlement.","requestBody":{"required":true,"description":"Create or reuse an MPP machine order. Reuse the same request_id and identical JSON body after a 402 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"workflow_form":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"rendered_letter":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false}},"bulk_text":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}}}}}},"x-payment-info":{"protocols":["mpp"],"pricingMode":"range","minPrice":"3.40","maxPrice":"200.00"},"responses":{"200":{"description":"Existing machine order is already paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrder"}}}},"202":{"description":"Payment settled and order is pending finalization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrder"}}}},"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/MppPaymentRequiredResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/orders/{id}":{"get":{"operationId":"getMppMachineOrder","summary":"Get MPP machine order status","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical order_id or any aliased request_id returned by the create or validate call.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Machine order status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineOrderStatus"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/flower-letters/validate":{"post":{"operationId":"validateMppMachineFlowerLetter","summary":"Validate an MPP flower-letter order and return a Florist One quote","requestBody":{"required":true,"description":"Quote and validate a dedicated MPP flower-letter order without triggering payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","note":"For your desk, your day, and the smile I hope this brings.","zipcode":"32503","product_code":"F1-509","delivery_date":"2026-05-08","customer":{"name":"Agent Owner","phone":"8505550100","address1":"123 Sender St","city":"Pensacola","state":"FL","zipcode":"32503","country":"US","email":"owner@example.com"},"recipient":{"name":"Recipient Example","phone":"8505550199","address1":"456 Recipient Ave","city":"Pensacola","state":"FL","zipcode":"32503","country":"US"},"allow_substitutions":true}}}}}},"responses":{"200":{"description":"Validation succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterValidationResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/flower-letters":{"post":{"operationId":"createMppMachineFlowerLetter","summary":"Create or reuse an MPP flower-letter order","description":"Unauthenticated calls return 402 Payment Required with WWW-Authenticate: Payment challenges after Florist One validation and quote.","requestBody":{"required":true,"description":"Create or reuse a dedicated MPP flower-letter order. Reuse the same request_id and identical JSON body after a 402 response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterRequest"},"examples":{"default":{"value":{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","note":"For your desk, your day, and the smile I hope this brings.","zipcode":"32503","product_code":"F1-509","delivery_date":"2026-05-08","customer":{"name":"Agent Owner","phone":"8505550100","address1":"123 Sender St","city":"Pensacola","state":"FL","zipcode":"32503","country":"US","email":"owner@example.com"},"recipient":{"name":"Recipient Example","phone":"8505550199","address1":"456 Recipient Ave","city":"Pensacola","state":"FL","zipcode":"32503","country":"US"},"allow_substitutions":true}}}}}},"x-payment-info":{"protocols":["mpp"],"pricingMode":"dynamic","minPrice":"1.00","maxPrice":"250.00"},"responses":{"200":{"description":"Existing flower-letter order is already paid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"202":{"description":"Payment settled and provider submission is queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"402":{"description":"Payment Required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/MppPaymentRequiredResponse"}}}},"409":{"description":"request_id already exists with a different payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}},"422":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}},"/api/machine/mpp/flower-letters/{id}":{"get":{"operationId":"getMppMachineFlowerLetter","summary":"Get MPP flower-letter order status","parameters":[{"name":"id","in":"path","required":true,"description":"Canonical order_id or any aliased request_id returned by the create or validate call.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Flower-letter order status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineFlowerLetterOrder"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MachineErrorResponse"}}}}}}}},"components":{"schemas":{"MachineOrderRequest":{"type":"object","additionalProperties":false,"description":"Machine order payload shared by the x402 and MPP create/validate endpoints. Send either a single-recipient order or a bulk mailing campaign. For a single-recipient order provide exactly one of pdf, form, or letter. For each provided address party choose exactly one strategy: verified Loqate Address fields or Manual address fields.","properties":{"request_id":{"type":"string","format":"uuid","description":"Client-generated idempotency key for one logical mailing. Reuse the same value on payment retries, and generate a fresh UUID for a legitimate second order even if the payload is identical."},"buyer_name":{"type":"string","minLength":1,"maxLength":256,"description":"Buyer / wallet owner display name."},"buyer_email":{"type":"string","format":"email","maxLength":256,"description":"Required for Stripe receipt delivery."},"pdf":{"oneOf":[{"type":"string","minLength":1,"description":"A data:application/pdf;base64,... URL or an allowlisted HTTPS download URL. The canonical format is the upload_token object variant."},{"type":"object","additionalProperties":false,"properties":{"upload_token":{"type":"string","minLength":1,"description":"Preferred canonical PDF reference. Get this from PostalForm PDF upload tooling."}},"required":["upload_token"]},{"type":"object","properties":{"download_url":{"type":"string","format":"uri","description":"HTTPS URL to a PDF file."},"file_id":{"type":"string","minLength":1,"description":"Stable file identifier paired with download_url."}},"required":["download_url","file_id"],"additionalProperties":true}]},"form":{"type":"object","additionalProperties":false,"description":"Nested workflow form payload. Discover available forms with GET /api/machine/forms, fetch the selected schema with GET /api/machine/forms/{slug}/schema, then send this form object instead of pdf or letter.","properties":{"slug":{"type":"string","minLength":1,"description":"Workflow form slug, for example 1120, 5471, or 5472."},"fields":{"type":"object","additionalProperties":true,"description":"Workflow field values keyed by field id from the machine form schema. Compound fields use nested objects keyed by subfield id."},"attachments":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","minLength":1,"description":"Attachment id from the selected workflow schema."},"label":{"type":"string","minLength":1},"file_name":{"type":"string","minLength":1,"maxLength":255},"content_type":{"type":"string","minLength":1,"description":"Optional MIME type. A data URL MIME type also works inside base64."},"base64":{"type":"string","minLength":1,"description":"Base64 file content or a data:<mime>;base64,... URL."}},"required":["id","base64"]},"description":"Optional supporting files required by the workflow schema."}},"required":["slug","fields"]},"letter":{"oneOf":[{"type":"string","minLength":1,"maxLength":20000,"description":"Letter body text for PostalForm to render server-side. Uses text format unless top-level format is set."},{"type":"object","additionalProperties":false,"properties":{"title":{"type":"string","maxLength":200},"body":{"type":"string","minLength":1,"maxLength":20000},"signature":{"anyOf":[{"type":"string","maxLength":2000},{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["typed","drawn"]},"text":{"type":"string","maxLength":2000},"dataUrl":{"type":"string"},"printDataUrl":{"type":"string"}}}]},"format":{"type":"string","enum":["text","html","markdown","rtf"],"description":"How PostalForm renders body. Defaults to text."},"render":{"type":"object","additionalProperties":false,"properties":{"paper":{"type":"string","enum":["letter"],"description":"Only letter paper is supported for machine-rendered letters."},"font_size":{"type":"integer","minimum":9,"maximum":14},"margin_in":{"type":"number","minimum":0.5,"maximum":1.5},"font":{"type":"string","enum":["times","helvetica"]}}}},"required":["body"]}],"description":"Letter content for PostalForm to render server-side into a PDF. Provide exactly one of pdf, form, or letter."},"format":{"type":"string","enum":["text","html","markdown","rtf"],"description":"Optional shorthand for letter.format when letter is provided. Defaults to text."},"file_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional display file name."},"sender_name":{"type":"string","minLength":1,"maxLength":256},"sender_address_id":{"type":"string","minLength":1,"pattern":"^[A-Za-z]{2,4}\\|","description":"Loqate Address id. The leading segment carries the country, for example US|... or CA|.... Required for sender Address mode."},"sender_address_type":{"type":"string","enum":["Address","Manual"],"description":"Address strategy for the sender. Omit to default to Address when manual fields are absent."},"sender_address_text":{"type":"string","minLength":1,"maxLength":2000,"description":"Human-readable address text for sender Address mode."},"sender_address_manual":{"type":"object","additionalProperties":false,"properties":{"line1":{"type":"string","minLength":1,"maxLength":256,"description":"Street address line 1."},"line2":{"type":"string","minLength":1,"maxLength":256,"description":"Optional unit, suite, or secondary line."},"city":{"type":"string","minLength":1,"maxLength":128,"description":"City or locality."},"state":{"type":"string","minLength":1,"maxLength":60,"description":"State, province, or region. Required for US and Canada."},"zip":{"type":"string","minLength":1,"maxLength":20,"description":"ZIP or postal code."},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","description":"Two-letter country code. Defaults to US when omitted."}},"required":["line1","city","state","zip"],"description":"Manual sender address. Required for sender Manual mode."},"recipient_name":{"type":"string","minLength":1,"maxLength":256},"recipient_address_id":{"type":"string","minLength":1,"pattern":"^[A-Za-z]{2,4}\\|","description":"Loqate Address id. The leading segment carries the country, for example US|... or CA|.... Required for recipient Address mode."},"recipient_address_type":{"type":"string","enum":["Address","Manual"],"description":"Address strategy for the recipient. Omit to default to Address when manual fields are absent."},"recipient_address_text":{"type":"string","minLength":1,"maxLength":2000,"description":"Human-readable address text for recipient Address mode."},"recipient_address_manual":{"type":"object","additionalProperties":false,"properties":{"line1":{"type":"string","minLength":1,"maxLength":256,"description":"Street address line 1."},"line2":{"type":"string","minLength":1,"maxLength":256,"description":"Optional unit, suite, or secondary line."},"city":{"type":"string","minLength":1,"maxLength":128,"description":"City or locality."},"state":{"type":"string","minLength":1,"maxLength":60,"description":"State, province, or region. Required for US and Canada."},"zip":{"type":"string","minLength":1,"maxLength":20,"description":"ZIP or postal code."},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$","description":"Two-letter country code. Defaults to US when omitted."}},"required":["line1","city","state","zip"],"description":"Manual recipient address. Required for recipient Manual mode."},"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]},"double_sided":{"type":"boolean","description":"Defaults to true."},"color":{"type":"boolean","description":"Defaults to false."},"mail_class":{"type":"string","enum":["standard","priority","express"],"description":"Mail service level. Defaults to standard."},"certified":{"type":"boolean","description":"Proof-mail add-on. Uses USPS Certified Mail for US destinations and PinGen registered mail for supported European destinations. Defaults to false."},"certified_return_receipt":{"type":"boolean","description":"Electronic Return Receipt add-on for US Certified Mail. Ignored for PinGen registered-mail destinations where receipt/confirmation is part of the registered service rather than a separate add-on."},"mailpiece_type":{"type":"string","enum":["letter","postcard"],"description":"Optional mailpiece type. Defaults to letter. Set to postcard only when pdf is a fully composed postcard PDF that follows the published postcard layout guide. Nested workflow form and letter payloads are letter-only."},"postcard_size":{"type":"string","enum":["4x6","6x9","11x6"],"description":"Required when mailpiece_type is postcard. The uploaded PDF must match the exact 2-page bleed template for that size. See /postcard-pdf-guidelines."}},"required":["request_id","buyer_name","buyer_email","sender_name"],"oneOf":[{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["pdf","recipient_name","sender_address_id","sender_address_text","recipient_address_id","recipient_address_text"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["pdf","recipient_name","sender_address_id","sender_address_text","recipient_address_manual"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["pdf","recipient_name","sender_address_manual","recipient_address_id","recipient_address_text"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["pdf","recipient_name","sender_address_manual","recipient_address_manual"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["form","recipient_name","sender_address_id","sender_address_text","recipient_address_id","recipient_address_text"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["form","recipient_name","sender_address_id","sender_address_text","recipient_address_manual"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["form","recipient_name","sender_address_manual","recipient_address_id","recipient_address_text"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["form","recipient_name","sender_address_manual","recipient_address_manual"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["letter","recipient_name","sender_address_id","sender_address_text","recipient_address_id","recipient_address_text"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["letter","recipient_name","sender_address_id","sender_address_text","recipient_address_manual"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["letter","recipient_name","sender_address_manual","recipient_address_id","recipient_address_text"]},{"not":{"properties":{"bulk":{"type":"object","additionalProperties":false,"properties":{"campaign_name":{"type":"string","minLength":1,"maxLength":255,"description":"Optional human-readable campaign label."},"csv_content":{"type":"string","minLength":1,"description":"Recipient CSV text. Required columns: line1, city, state, zip. Optional columns: line2 and recipient_name. All additional columns become merge fields."},"content_mode":{"type":"string","enum":["text","html","pdf"],"description":"How PostalForm renders one letter per CSV row. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every row without merge support."},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["csv_content","content_mode"],"oneOf":[{"type":"object","properties":{"content_mode":{"const":"text"},"template_text":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is text. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_text"]},{"type":"object","properties":{"content_mode":{"const":"html"},"template_html":{"type":"string","minLength":1,"description":"Required when bulk.content_mode is html. Use {{column_name}} merge tags that match CSV headers."}},"required":["content_mode","template_html"]},{"type":"object","properties":{"content_mode":{"const":"pdf"}},"required":["content_mode"]}]}},"required":["bulk"]},"required":["letter","recipient_name","sender_address_manual","recipient_address_manual"]},{"required":["bulk","sender_address_id","sender_address_text"]},{"required":["bulk","sender_address_manual"]}],"allOf":[{"if":{"required":["bulk"],"properties":{"bulk":{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}}},"then":{"properties":{"pdf":{"oneOf":[{"type":"string","minLength":1,"description":"A data:application/pdf;base64,... URL or an allowlisted HTTPS download URL. The canonical format is the upload_token object variant."},{"type":"object","additionalProperties":false,"properties":{"upload_token":{"type":"string","minLength":1,"description":"Preferred canonical PDF reference. Get this from PostalForm PDF upload tooling."}},"required":["upload_token"]},{"type":"object","properties":{"download_url":{"type":"string","format":"uri","description":"HTTPS URL to a PDF file."},"file_id":{"type":"string","minLength":1,"description":"Stable file identifier paired with download_url."}},"required":["download_url","file_id"],"additionalProperties":true}]}},"required":["pdf"]}}],"examples":[{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","pdf":{"upload_token":"pfu_123"},"file_name":"letter.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false},{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","form":{"slug":"5471","fields":{"foreign_corporation_period_begin":"01/01/2025","foreign_corporation_period_end":"12/31/2025","field_5":"Example Corporation Inc.","field_11":"123-45-6789","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801"}},"file_name":"5471.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false},{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","letter":{"title":"Account notice","format":"markdown","body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","signature":"Sender Example"},"file_name":"account-notice.pdf","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","recipient_name":"Recipient Example","recipient_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false},{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","sender_name":"Sender Example","sender_address_type":"Address","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","double_sided":true,"color":false,"mail_class":"standard","certified":false,"certified_return_receipt":false,"bulk":{"campaign_name":"April Outreach","csv_content":"recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200","content_mode":"text","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."}}]},"MachineWorkflowFormListResponse":{"type":"object","additionalProperties":false,"properties":{"forms":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}]},"certified_mail":{"type":"string","enum":["required","optional","none"]},"recipient_mode":{"type":"string"},"attachments":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"}},"required":["id","label","required"]}},"create_paths":{"type":"object","additionalProperties":false,"properties":{"x402":{"type":"string"},"mpp":{"type":"string"}},"required":["x402","mpp"]}},"required":["slug","name","certified_mail","recipient_mode","attachments","create_paths"]}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["forms","next_cursor"]},"MachineWorkflowFormSchema":{"type":"object","additionalProperties":true,"description":"Machine-usable workflow schema returned by the same schema renderer used by PostalForm MCP. It includes fields, groups, attachments, dependencies, and machine_submission.create_paths."},"MachineFlowerLetterRequest":{"type":"object","additionalProperties":false,"description":"Dedicated flower-letter payload for machine payment flows. PostalForm validates the Florist One product, ZIP delivery dates, and total before issuing a payment challenge. The requester IP is collected from the incoming request.","properties":{"request_id":{"type":"string","format":"uuid","description":"Client-generated idempotency key. Reuse the same value and exact body after a 402 challenge."},"buyer_name":{"type":"string","minLength":1,"maxLength":100},"buyer_email":{"type":"string","format":"email","maxLength":100},"note":{"type":"string","minLength":1,"maxLength":200,"description":"Message attached to the real flowers on the florist card."},"zipcode":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$","description":"Recipient delivery ZIP used for Florist One catalog totals and delivery dates."},"product_code":{"type":"string","minLength":1,"maxLength":64,"description":"Florist One product code selected from the catalog."},"delivery_date":{"type":"string","format":"date","description":"Requested Florist One delivery date. The date is checked again after payment."},"customer":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"phone":{"type":"string","minLength":1,"maxLength":32,"description":"US 10 digit phone number. Formatting characters are accepted."},"address1":{"type":"string","minLength":1,"maxLength":100},"address2":{"type":"string","maxLength":100},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","pattern":"^[A-Z]{2}$"},"zipcode":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Two-letter country code. Defaults to US when omitted."},"email":{"type":"string","format":"email","description":"Optional customer email. Defaults to buyer_email when omitted."}},"required":["name","phone","address1","city","state","zipcode"]},"recipient":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"phone":{"type":"string","minLength":1,"maxLength":32,"description":"US 10 digit phone number. Formatting characters are accepted."},"address1":{"type":"string","minLength":1,"maxLength":100},"address2":{"type":"string","maxLength":100},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","pattern":"^[A-Z]{2}$"},"zipcode":{"type":"string","pattern":"^\\d{5}(?:-\\d{4})?$"},"country":{"type":"string","pattern":"^[A-Z]{2}$","description":"Two-letter country code. Defaults to US when omitted."},"institution":{"type":"string","maxLength":100,"description":"Optional facility, business, or hospital name."}},"required":["name","phone","address1","city","state","zipcode"]},"special_instructions":{"type":"string","maxLength":100},"allow_substitutions":{"type":"boolean","description":"Defaults to true."}},"required":["request_id","buyer_name","buyer_email","note","zipcode","product_code","delivery_date","customer","recipient"],"examples":[{"request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_name":"Agent Owner","buyer_email":"owner@example.com","note":"For your desk, your day, and the smile I hope this brings.","zipcode":"32503","product_code":"F1-509","delivery_date":"2026-05-08","customer":{"name":"Agent Owner","phone":"8505550100","address1":"123 Sender St","city":"Pensacola","state":"FL","zipcode":"32503","country":"US","email":"owner@example.com"},"recipient":{"name":"Recipient Example","phone":"8505550199","address1":"456 Recipient Ave","city":"Pensacola","state":"FL","zipcode":"32503","country":"US"},"allow_substitutions":true}]},"MachineOrder":{"type":"object","additionalProperties":true,"properties":{"order_id":{"type":"string","format":"uuid","description":"Canonical server order id. This may differ from request_id when PostalForm reuses an existing unpaid draft."},"status":{"type":"string"},"payment_status":{"type":"string"},"is_paid":{"type":"boolean"},"current_step":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_intent_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_usd":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"mailpiece_type":{"type":"string","enum":["letter","postcard"]},"postcard_size":{"anyOf":[{"type":"string","enum":["4x6","6x9","11x6"]},{"type":"null"}]},"postcard_guidelines_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Canonical postcard PDF formatting guide. Present for postcard responses and null for letter responses."},"machine_payment":{"type":"object","additionalProperties":true,"properties":{"protocol":{"type":"string","enum":["x402","mpp"]},"method":{"type":"string"},"network":{"type":"string"},"recipient":{"type":"string"},"settlement_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"testnet":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["protocol","method","network","recipient","settlement_reference","settled_at"]},"x402":{"type":"object","additionalProperties":false,"properties":{"network":{"anyOf":[{"type":"string"},{"type":"null"}]},"pay_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"settlement_tx":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["network","pay_to","settlement_tx","settled_at"]},"campaign_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulk campaign dashboard route for mailing_campaign orders. Null for single-recipient orders."}},"required":["order_id","status","payment_status","is_paid","current_step","payment_intent_id","payment_channel","price_usd","currency","mailpiece_type","postcard_size","postcard_guidelines_url","machine_payment"]},"MachineOrderStatus":{"type":"object","additionalProperties":true,"properties":{"order_id":{"type":"string","format":"uuid","description":"Canonical server order id. This may differ from request_id when PostalForm reuses an existing unpaid draft."},"status":{"type":"string"},"payment_status":{"type":"string"},"is_paid":{"type":"boolean"},"current_step":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_intent_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_usd":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"mailpiece_type":{"type":"string","enum":["letter","postcard"]},"postcard_size":{"anyOf":[{"type":"string","enum":["4x6","6x9","11x6"]},{"type":"null"}]},"postcard_guidelines_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Canonical postcard PDF formatting guide. Present for postcard responses and null for letter responses."},"machine_payment":{"type":"object","additionalProperties":true,"properties":{"protocol":{"type":"string","enum":["x402","mpp"]},"method":{"type":"string"},"network":{"type":"string"},"recipient":{"type":"string"},"settlement_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"testnet":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["protocol","method","network","recipient","settlement_reference","settled_at"]},"x402":{"type":"object","additionalProperties":false,"properties":{"network":{"anyOf":[{"type":"string"},{"type":"null"}]},"pay_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"settlement_tx":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["network","pay_to","settlement_tx","settled_at"]},"campaign_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulk campaign dashboard route for mailing_campaign orders. Null for single-recipient orders."},"order_complete_url":{"type":"string","description":"Either the completion URL after payment settles or a placeholder message before settlement."}},"required":["order_id","status","payment_status","is_paid","current_step","payment_intent_id","payment_channel","price_usd","currency","mailpiece_type","postcard_size","postcard_guidelines_url","machine_payment","order_complete_url"]},"MachineOrderValidationResponse":{"type":"object","additionalProperties":false,"properties":{"request_id":{"type":"string","format":"uuid"},"request_hash":{"type":"string"},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Canonical server order id for an existing reusable draft, if one was found. This may differ from request_id when PostalForm collapses duplicate unpaid attempts."},"status":{"type":"string","enum":["validated_existing_order","validated_new_order"]},"postcard_guidelines_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Canonical postcard PDF formatting guide. Present for postcard validation responses and null for letter responses."},"bulk":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"recipient_count":{"type":"integer","minimum":1},"content_mode":{"type":"string","enum":["text","html","pdf"]}},"required":["recipient_count","content_mode"]},{"type":"null"}],"description":"Bulk campaign metadata when validating a bulk machine request. Null for single-recipient orders."},"quote":{"type":"object","additionalProperties":false,"properties":{"price_usd":{"type":"number"},"full_price_usd":{"type":"number"},"currency":{"type":"string","enum":["usd"]},"page_count":{"type":"integer","minimum":1},"billable_page_count":{"type":"integer","minimum":1},"double_sided":{"type":"boolean"},"color":{"type":"boolean"},"mail_class":{"type":"string","enum":["standard","priority","express"]},"certified":{"type":"boolean"},"certified_return_receipt":{"type":"boolean"},"mailpiece_type":{"type":"string","enum":["letter","postcard"]},"postcard_size":{"anyOf":[{"type":"string","enum":["4x6","6x9","11x6"]},{"type":"null"}]},"provider":{"type":"string"}},"required":["price_usd","full_price_usd","currency","page_count","billable_page_count","double_sided","color","mail_class","certified","certified_return_receipt","mailpiece_type","postcard_size","provider"]}},"required":["request_id","request_hash","order_id","status","postcard_guidelines_url","quote"]},"MachineFlowerLetterValidationResponse":{"type":"object","additionalProperties":true,"properties":{"request_id":{"type":"string","format":"uuid"},"request_hash":{"type":"string"},"order_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"status":{"type":"string","enum":["validated_existing_order","validated_new_order"]},"protocol":{"type":"string","enum":["mpp"]},"methods":{"type":"array","items":{"type":"string","enum":["tempo","stripe_spt"]}},"product_type":{"type":"string","enum":["flower_letter"]},"quote":{"type":"object","additionalProperties":true,"properties":{"product":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string"},"name":{"type":"string"},"priceCents":{"type":"integer","description":"Arrangement price before Florist One delivery charges and destination tax."},"small":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"large":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}},"required":["code","name","priceCents"]},"total":{"type":"object","additionalProperties":true,"properties":{"subtotalCents":{"type":"integer"},"orderTotalCents":{"type":"integer"},"taxTotalCents":{"anyOf":[{"type":"integer"},{"type":"null"}]},"deliveryChargeCents":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["subtotalCents","orderTotalCents"]}},"required":["product","total"]}},"required":["request_id","request_hash","order_id","status","product_type","quote"]},"MachineFlowerLetterOrder":{"type":"object","additionalProperties":true,"properties":{"order_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"payment_status":{"type":"string"},"is_paid":{"type":"boolean"},"current_step":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_intent_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_usd":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"product_type":{"type":"string","enum":["flower_letter"]},"order_complete_url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["order_id","status","payment_status","is_paid","current_step","payment_intent_id","payment_channel","price_usd","currency","product_type"]},"FlowerLetterPaymentRequiredResponse":{"type":"object","additionalProperties":true,"properties":{"order_id":{"type":"string","format":"uuid"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["payment_required"]},"product_type":{"type":"string","enum":["flower_letter"]},"message":{"type":"string"},"price_breakdown":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"product_name":{"type":"string"},"delivery_zipcode":{"type":"string"},"arrangement_price_cents":{"type":"integer","description":"Arrangement price before Florist One delivery charges and destination tax."},"delivery_charge_cents":{"anyOf":[{"type":"integer"},{"type":"null"}]},"tax_total_cents":{"anyOf":[{"type":"integer"},{"type":"null"}]},"order_total_cents":{"type":"integer"},"currency":{"type":"string","enum":["usd"]},"note":{"type":"string"}},"required":["product_name","delivery_zipcode","arrangement_price_cents","delivery_charge_cents","tax_total_cents","order_total_cents","currency","note"]},{"type":"null"}]}},"required":["order_id","request_id","status","product_type","message"]},"X402PaymentRequiredResponse":{"type":"object","additionalProperties":false,"properties":{"order_id":{"type":"string","format":"uuid"},"request_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["payment_required"]},"mailpiece_type":{"type":"string","enum":["letter","postcard"]},"postcard_size":{"anyOf":[{"type":"string","enum":["4x6","6x9","11x6"]},{"type":"null"}]},"postcard_guidelines_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Canonical postcard PDF formatting guide. Present for postcard payment challenges and null for letter responses."},"preview_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Signed short-lived PDF preview URL for the unpaid single-recipient draft. Null when no draft PDF preview is available."},"campaign_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulk campaign dashboard route for mailing_campaign orders. Null for single-recipient orders."},"message":{"type":"string"}},"required":["order_id","request_id","status","mailpiece_type","postcard_size","postcard_guidelines_url","message"]},"MppPaymentRequiredResponse":{"type":"object","additionalProperties":true,"properties":{"code":{"type":"string","enum":["payment_required"]},"order_id":{"type":"string","format":"uuid"},"request_id":{"type":"string","format":"uuid"},"documentation_url":{"type":"string","format":"uri"},"postcard_guidelines_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Canonical postcard PDF formatting guide. Present for postcard payment challenges and null for letter responses."},"preview_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Signed short-lived PDF preview URL for the unpaid single-recipient draft. Null when no draft PDF preview is available."},"campaign_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulk campaign dashboard route for mailing_campaign orders. Null for single-recipient orders."},"message":{"type":"string"},"next_step":{"type":"string"},"supported_methods":{"type":"array","items":{"type":"string","enum":["tempo","stripe_spt"]}},"price_breakdown":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"product_name":{"type":"string"},"delivery_zipcode":{"type":"string"},"arrangement_price_cents":{"type":"integer","description":"Arrangement price before Florist One delivery charges and destination tax."},"delivery_charge_cents":{"anyOf":[{"type":"integer"},{"type":"null"}]},"tax_total_cents":{"anyOf":[{"type":"integer"},{"type":"null"}]},"order_total_cents":{"type":"integer"},"currency":{"type":"string","enum":["usd"]},"note":{"type":"string"}},"required":["product_name","delivery_zipcode","arrangement_price_cents","delivery_charge_cents","tax_total_cents","order_total_cents","currency","note"]},{"type":"null"}]}},"required":["code","order_id","request_id","message","supported_methods"]},"MachineErrorResponse":{"type":"object","additionalProperties":false,"properties":{"message":{"type":"string"},"code":{"type":"string"},"order_id":{"type":"string","format":"uuid"},"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"fix_examples":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"object","additionalProperties":true}]}}},"required":["path","code","message"]}}},"required":["message","code"]}}}}