openapi: 3.2.0 info: title: PostalForm Payments Machine API version: 1.0.0 description: Machine-oriented print-and-mail endpoints for x402 and MPP payment flows. 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. For both machine payment families, call the validate endpoint first to verify the payload and get a quote before attempting payment. When 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. If 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. For 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. Address countries default to US when omitted. For international manual addresses, include countryCode; for Loqate addresses, the id prefix carries the country. Both modes accept exactly the same mailing countries offered by PostalForm''s checkout address picker: US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. Prefer 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. For 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. Unpaid single-recipient create responses may include preview_url, a signed short-lived URL for reviewing the generated or uploaded PDF before payment. For supported single-mailpiece 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. Statutory multi-recipient workflows are intentionally excluded. For 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. Bulk 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. For 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. For MPP-only shipping labels, use /api/machine/mpp/shipping-labels. Include exact packed weight in ounces and all three parcel dimensions in inches. Validate first, then reuse the identical request_id and body after the 402 challenge. A successful immediate payment returns a signed PDF download URL; delayed settlements expose it from the status endpoint and order completion page once fulfillment finishes. For 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. Use POST /api/machine/orders for x402. The server returns 402 with PAYMENT-REQUIRED and expects PAYMENT-SIGNATURE on retry. Use 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. Poll 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.' servers: - url: https://postalform.com security: [] tags: - name: Machine paths: /api/machine/forms: get: operationId: listMachineForms summary: List workflow forms available to machine order flows description: Search published single-mailpiece PostalForm workflow forms that agents can fill and submit through the x402 or MPP machine order endpoints. Coordinated statutory multi-recipient workflows are excluded. 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' tags: - Machine /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' tags: - Machine /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 return_receipt_format: electronic restricted_delivery: false err_delivery: manual 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 Please 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 Jane Doe,123 Main St,,Springfield,IL,62701,ACCT-100 John 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' tags: - Machine /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. A 202 settled_pending_webhook response means Stripe is verifying the transaction; poll status and do not pay again. 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 return_receipt_format: electronic restricted_delivery: false err_delivery: manual 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 Please 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 Jane Doe,123 Main St,,Springfield,IL,62701,ACCT-100 John 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' tags: - Machine /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' tags: - Machine /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' tags: - Machine /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. A 202 settled_pending_webhook response means Stripe is verifying the transaction; poll status and do not pay again. 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' tags: - Machine /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' tags: - Machine /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 return_receipt_format: electronic restricted_delivery: false err_delivery: manual 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 Please 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 Jane Doe,123 Main St,,Springfield,IL,62701,ACCT-100 John 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' tags: - Machine /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 return_receipt_format: electronic restricted_delivery: false err_delivery: manual 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 Please 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 Jane Doe,123 Main St,,Springfield,IL,62701,ACCT-100 John 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' tags: - Machine /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' tags: - Machine /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' tags: - Machine /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' tags: - Machine /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' tags: - Machine /api/machine/mpp/shipping-labels/validate: post: operationId: validateMppShippingLabel summary: Validate an MPP shipping-label request and return live rates description: Creates an unpurchased EasyPost shipment to obtain live rates. The selected public total includes the live carrier rate, PostalForm service fee, and estimated payment-fee reserve. requestBody: required: true description: Quote and validate a domestic shipping label without triggering payment. content: application/json: schema: $ref: '#/components/schemas/MachineShippingLabelRequest' examples: default: value: request_id: 6df12d40-ae2a-4a06-a169-b7aa392ca7bd buyer_name: Agent Owner buyer_email: owner@example.com from: name: Agent Owner street1: 417 Montgomery St city: San Francisco state: CA zip: '94104' country: US phone: '4155550100' email: owner@example.com to: name: Recipient Example street1: 179 N Harbor Dr city: Redondo Beach state: CA zip: '90277' country: US phone: '3105550199' parcel: weight_oz: 16 length_in: 12 width_in: 9 height_in: 4 carrier: USPS service: GroundAdvantage responses: '200': description: Validation and live rating succeeded content: application/json: schema: $ref: '#/components/schemas/MachineShippingLabelValidationResponse' '409': description: request_id payload mismatch or persisted carrier quote expired content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' '422': description: Payload invalid or requested carrier service unavailable content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' '502': description: EasyPost could not rate the shipment content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' '503': description: Shipping labels are disabled or EasyPost is not configured content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' tags: - Machine /api/machine/mpp/shipping-labels: post: operationId: createMppShippingLabel summary: Create, pay for, and download an MPP shipping label description: 'The unpaid call persists the exact EasyPost shipment/rate and returns MPP challenges. Retry the identical body with Authorization: Payment. Immediate settlements purchase the persisted rate and return label_download_url in the receipt-bearing response; delayed settlements return 202 and complete through the status endpoint.' requestBody: required: true description: Create or reuse an MPP-only shipping-label order. Reuse the same request_id and identical JSON body after a 402 response. content: application/json: schema: $ref: '#/components/schemas/MachineShippingLabelRequest' examples: default: value: request_id: 6df12d40-ae2a-4a06-a169-b7aa392ca7bd buyer_name: Agent Owner buyer_email: owner@example.com from: name: Agent Owner street1: 417 Montgomery St city: San Francisco state: CA zip: '94104' country: US phone: '4155550100' email: owner@example.com to: name: Recipient Example street1: 179 N Harbor Dr city: Redondo Beach state: CA zip: '90277' country: US phone: '3105550199' parcel: weight_oz: 16 length_in: 12 width_in: 9 height_in: 4 carrier: USPS service: GroundAdvantage x-payment-info: protocols: - mpp pricingMode: dynamic minPrice: '0.01' maxPrice: '500.00' responses: '200': description: Payment is complete and the signed PDF label is available content: application/json: schema: $ref: '#/components/schemas/MachineShippingLabelOrder' '202': description: Payment is pending finalization or label fulfillment is retrying content: application/json: schema: $ref: '#/components/schemas/MachineShippingLabelOrder' '402': description: Payment Required; response also includes the persisted quote content: application/problem+json: schema: $ref: '#/components/schemas/MppPaymentRequiredResponse' '409': description: request_id payload mismatch or persisted carrier quote expired content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' '422': description: Payload invalid or requested carrier service unavailable content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' '502': description: EasyPost could not rate the shipment content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' '503': description: Shipping labels are disabled or EasyPost is not configured content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' tags: - Machine /api/machine/mpp/shipping-labels/{id}: get: operationId: getMppShippingLabel summary: Get MPP shipping-label payment, fulfillment, and download 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: Current order status, including a fresh signed PDF link whenever the label is ready content: application/json: schema: $ref: '#/components/schemas/MachineShippingLabelOrder' '404': description: Order not found content: application/json: schema: $ref: '#/components/schemas/MachineErrorResponse' tags: - Machine components: schemas: MachineShippingLabelValidationResponse: type: object additionalProperties: false 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 - card product_type: type: string enum: - shipping_label quote: type: object additionalProperties: false properties: quote_id: type: string description: EasyPost shipment id backing this quote. expires_at: type: string format: date-time selected_rate: type: object additionalProperties: false properties: carrier: type: string service: type: string total_cents: type: integer minimum: 1 currency: type: string enum: - usd delivery_days: anyOf: - type: integer - type: 'null' delivery_date: anyOf: - type: string - type: 'null' delivery_date_guaranteed: anyOf: - type: boolean - type: 'null' required: - carrier - service - total_cents - currency available_rates: type: array items: type: object additionalProperties: false properties: carrier: type: string service: type: string total_cents: type: integer minimum: 1 currency: type: string enum: - usd delivery_days: anyOf: - type: integer - type: 'null' delivery_date: anyOf: - type: string - type: 'null' delivery_date_guaranteed: anyOf: - type: boolean - type: 'null' required: - carrier - service - total_cents - currency note: type: string required: - quote_id - expires_at - selected_rate - available_rates - note required: - request_id - request_hash - order_id - status - protocol - methods - product_type - quote 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 single-mailpiece 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. Statutory workflows requiring coordinated service on multiple recipients are intentionally excluded. 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:;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|.... The country must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. 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 enum: - US - CA - AT - BE - CH - DE - ES - FR - GB - IN - LU - NL description: 'Two-letter country code. Defaults to US when omitted. Must match a country available in PostalForm''s checkout address picker: US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL.' required: - line1 - city - 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|.... The country must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. 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 enum: - US - CA - AT - BE - CH - DE - ES - FR - GB - IN - LU - NL description: 'Two-letter country code. Defaults to US when omitted. Must match a country available in PostalForm''s checkout address picker: US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL.' required: - line1 - city - 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, Canada Post Registered Mail through PostGrid for Canadian destinations, and PinGen registered mail for supported European destinations. Defaults to false. certified_return_receipt: type: boolean description: Return Receipt add-on for US Certified Mail. Defaults to the electronic format. Ignored for Canada Post Registered Mail and PinGen registered-mail destinations where receipt/confirmation is part of the registered service rather than a separate add-on. return_receipt_format: type: string enum: - electronic - physical description: Electronic selects the signed USPS PDF. Physical selects the mailed PS Form 3811 green card. Requires certified_return_receipt=true. restricted_delivery: type: boolean description: Requests USPS Restricted Delivery for addressee-only delivery. Requires certified_return_receipt=true. err_delivery: type: string enum: - manual - email description: Defaults to manual USPS retrieval. Email makes PostalForm acquire and email the electronic receipt when available. err_email: type: string format: email maxLength: 256 description: Optional destination for err_delivery=email. Defaults to buyer_email when omitted. Not valid for physical PS Form 3811. signature_required: type: boolean description: Request USPS signature on delivery. Defaults to false. Forced false for postcards or when mail_class is standard. 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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, recipient_name, and country/country_code/countrycode. Country defaults to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL. All other 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 return_receipt_format: electronic restricted_delivery: false err_delivery: manual - 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 Please 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 Jane Doe,123 Main St,,Springfield,IL,62701,ACCT-100 John 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 MachineShippingLabelRequest: type: object additionalProperties: false description: MPP-only domestic shipping-label payload. PostalForm obtains live rates from the carrier accounts enabled in EasyPost. Omit carrier and service to select the lowest returned rate, or provide both to request a specific service. 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 from: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 100 company: type: string maxLength: 100 street1: type: string minLength: 1 maxLength: 100 street2: type: string maxLength: 100 city: type: string minLength: 1 maxLength: 100 state: type: string pattern: ^[A-Z]{2}$ zip: type: string pattern: ^\d{5}(?:-\d{4})?$ country: type: string enum: - US description: MPP shipping labels currently support US domestic shipments only. phone: type: string minLength: 7 maxLength: 32 email: type: string format: email maxLength: 100 required: - name - street1 - city - state - zip - phone to: type: object additionalProperties: false properties: name: type: string minLength: 1 maxLength: 100 company: type: string maxLength: 100 street1: type: string minLength: 1 maxLength: 100 street2: type: string maxLength: 100 city: type: string minLength: 1 maxLength: 100 state: type: string pattern: ^[A-Z]{2}$ zip: type: string pattern: ^\d{5}(?:-\d{4})?$ country: type: string enum: - US description: MPP shipping labels currently support US domestic shipments only. phone: type: string minLength: 7 maxLength: 32 email: type: string format: email maxLength: 100 required: - name - street1 - city - state - zip - phone parcel: type: object additionalProperties: false description: Measured package dimensions in inches and total packed weight in ounces. Values are rounded up to one decimal place before rating. properties: weight_oz: type: number exclusiveMinimum: 0 maximum: 2400 length_in: type: number exclusiveMinimum: 0 maximum: 108 width_in: type: number exclusiveMinimum: 0 maximum: 108 height_in: type: number exclusiveMinimum: 0 maximum: 108 required: - weight_oz - length_in - width_in - height_in carrier: type: string maxLength: 64 description: Optional EasyPost carrier name, for example USPS, UPS, or FedEx. service: type: string maxLength: 128 description: Optional EasyPost carrier service name, for example GroundAdvantage. required: - request_id - buyer_name - buyer_email - from - to - parcel examples: - request_id: 6df12d40-ae2a-4a06-a169-b7aa392ca7bd buyer_name: Agent Owner buyer_email: owner@example.com from: name: Agent Owner street1: 417 Montgomery St city: San Francisco state: CA zip: '94104' country: US phone: '4155550100' email: owner@example.com to: name: Recipient Example street1: 179 N Harbor Dr city: Redondo Beach state: CA zip: '90277' country: US phone: '3105550199' parcel: weight_oz: 16 length_in: 12 width_in: 9 height_in: 4 carrier: USPS service: GroundAdvantage 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 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. certified: type: boolean certified_return_receipt: type: boolean return_receipt_format: type: string enum: - electronic - physical restricted_delivery: type: boolean err_delivery: type: string enum: - manual - email err_email: anyOf: - type: string format: email - type: 'null' err_status: type: string enum: - manual - pending - sent - failed err_document_available: type: boolean err_delivered_at: anyOf: - type: string format: date-time - type: 'null' tracking_number: anyOf: - type: string - type: 'null' tracking_url: anyOf: - type: string format: uri - type: 'null' usps_tracking_url: anyOf: - type: string format: uri - type: 'null' 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 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 - card 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 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 - card 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 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. 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 return_receipt_format: type: string enum: - electronic - physical restricted_delivery: type: boolean err_delivery: type: string enum: - manual - email err_email: anyOf: - type: string format: email - type: 'null' signature_required: 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 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 MachineShippingLabelOrder: type: object additionalProperties: true properties: order_id: type: string format: uuid status: type: string payment_status: type: string fulfillment_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: - shipping_label carrier: type: string service: type: string tracking_code: anyOf: - type: string - type: 'null' status_url: type: string format: uri order_complete_url: anyOf: - type: string format: uri - type: 'null' label_download_url: anyOf: - type: string format: uri - type: 'null' label_download_expires_at: anyOf: - type: string format: date-time - type: 'null' quote: type: object additionalProperties: false properties: quote_id: type: string description: EasyPost shipment id backing this quote. expires_at: type: string format: date-time selected_rate: type: object additionalProperties: false properties: carrier: type: string service: type: string total_cents: type: integer minimum: 1 currency: type: string enum: - usd delivery_days: anyOf: - type: integer - type: 'null' delivery_date: anyOf: - type: string - type: 'null' delivery_date_guaranteed: anyOf: - type: boolean - type: 'null' required: - carrier - service - total_cents - currency available_rates: type: array items: type: object additionalProperties: false properties: carrier: type: string service: type: string total_cents: type: integer minimum: 1 currency: type: string enum: - usd delivery_days: anyOf: - type: integer - type: 'null' delivery_date: anyOf: - type: string - type: 'null' delivery_date_guaranteed: anyOf: - type: boolean - type: 'null' required: - carrier - service - total_cents - currency note: type: string required: - quote_id - expires_at - selected_rate - available_rates - note error: anyOf: - type: string - type: 'null' required: - order_id - status - payment_status - fulfillment_status - is_paid - current_step - payment_intent_id - payment_channel - price_usd - currency - product_type - carrier - service - tracking_code - status_url - order_complete_url - label_download_url - label_download_expires_at - quote - error 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 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 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. certified: type: boolean certified_return_receipt: type: boolean return_receipt_format: type: string enum: - electronic - physical restricted_delivery: type: boolean err_delivery: type: string enum: - manual - email err_email: anyOf: - type: string format: email - type: 'null' err_status: type: string enum: - manual - pending - sent - failed err_document_available: type: boolean err_delivered_at: anyOf: - type: string format: date-time - type: 'null' tracking_number: anyOf: - type: string - type: 'null' tracking_url: anyOf: - type: string format: uri - type: 'null' usps_tracking_url: anyOf: - type: string format: uri - type: 'null' 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 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