{ "openapi": "3.1.0", "info": { "title": "PostalForm form discovery and mailing validation", "version": "1.0.0", "description": "Discover form schemas and validate a proposed mailing. This Actions profile cannot create paid orders or send mail. Validation transmits the supplied document and addresses to PostalForm." }, "servers": [ { "url": "https://postalform.com" } ], "paths": { "/api/machine/forms": { "get": { "operationId": "listMachineForms", "security": [], "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" } } } } } } }, "/api/machine/forms/{slug}/schema": { "get": { "operationId": "getMachineFormSchema", "security": [], "summary": "Get a machine-usable workflow form schema", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Workflow form slug from GET /api/machine/forms.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Machine workflow form schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineWorkflowFormSchema" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineErrorResponse" } } } } } } }, "/api/machine/orders/validate": { "post": { "operationId": "validateMachineOrder", "security": [], "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\n\nPlease review the enclosed account update and contact us with any questions.", "signature": "Sender Example" }, "file_name": "account-notice.pdf", "sender_name": "Sender Example", "sender_address_type": "Address", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Recipient Example", "recipient_address_type": "Address", "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG", "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701", "double_sided": true, "color": false, "mail_class": "standard", "certified": false, "certified_return_receipt": false } }, "bulk_text": { "value": { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "sender_name": "Sender Example", "sender_address_type": "Address", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_text": "123 Sender St, Springfield, IL 62701", "double_sided": true, "color": false, "mail_class": "standard", "certified": false, "certified_return_receipt": false, "bulk": { "campaign_name": "April Outreach", "csv_content": "recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200", "content_mode": "text", "template_text": "Hello {{recipient_name}}, your account reference is {{account_number}}." } } } } } } }, "responses": { "200": { "description": "Validation succeeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineOrderValidationResponse" } } } }, "409": { "description": "request_id already exists with a different payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineErrorResponse" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MachineErrorResponse" } } } } }, "x-openai-isConsequential": true } } }, "components": { "schemas": { "MachineOrderRequest": { "type": "object", "additionalProperties": false, "description": "Machine order payload shared by the x402 and MPP create/validate endpoints. Send either a single-recipient order or a bulk mailing campaign. For a single-recipient order provide exactly one of pdf, form, or letter. For each provided address party choose exactly one strategy: verified Loqate Address fields or Manual address fields.", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Client-generated idempotency key for one logical mailing. Reuse the same value on payment retries, and generate a fresh UUID for a legitimate second order even if the payload is identical." }, "buyer_name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Buyer / wallet owner display name." }, "buyer_email": { "type": "string", "format": "email", "maxLength": 256, "description": "Required for Stripe receipt delivery." }, "pdf": { "oneOf": [ { "type": "string", "minLength": 1, "description": "A data:application/pdf;base64,... URL or a public 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": 255, "description": "Names are preserved and validated against the selected mailing route and contact role. Narrower limits of 40 or 45 characters may apply. Overlong names are rejected before payment." }, "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": 255, "description": "Names are preserved and validated against the selected mailing route and contact role. Narrower limits of 40 or 45 characters may apply. Overlong names are rejected before payment." }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, which selects USPS First-Class Mail for eligible U.S. letters, not USPS Marketing Mail. International services vary by destination." }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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, mutually exclusive with recipients. 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." }, "recipients": { "type": "array", "minItems": 1, "items": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "recipient_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1 }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "type": "string", "minLength": 1 }, "state": { "description": "Required for US and Canadian recipients. Omit or send null elsewhere.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "zip": { "type": "string", "minLength": 1, "description": "ZIP/postal code as a string, preserving leading zeros." }, "country": { "description": "Mailing country code. Defaults to US.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "merge_fields": { "description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "line1", "city", "zip" ], "additionalProperties": false }, "description": "JSON recipient list, mutually exclusive with csv_content. Use flat address fields and optional merge_fields. Countries default to US and must be one of US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU, NL." }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ], "description": "How PostalForm renders one letter per recipient. text uses template_text merge fields, html uses template_html merge fields, and pdf reuses the top-level pdf for every recipient without merge support." }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." }, "template_html": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is html. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "required": [ "content_mode" ], "allOf": [ { "oneOf": [ { "required": [ "csv_content" ] }, { "required": [ "recipients" ] } ] } ], "oneOf": [ { "type": "object", "properties": { "content_mode": { "const": "text" }, "template_text": { "type": "string", "minLength": 1, "description": "Required when bulk.content_mode is text. Use {{field_name}} merge tags from CSV headers or JSON recipient merge_fields and address fields. Plain text only: HTML tags are rejected because text mode would print them literally." } }, "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. {{field_name}} inserts a CSV column, JSON merge_field or address field as escaped text; {{{field_name}}} inserts it as HTML (use this for per-recipient HTML bodies such as {{{letter_body}}}). A merge value containing HTML referenced with two braces is rejected. Scripts and remote resources are not loaded, so embed images as data: URLs." } }, "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 a public 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\n\nPlease review the enclosed account update and contact us with any questions.", "signature": "Sender Example" }, "file_name": "account-notice.pdf", "sender_name": "Sender Example", "sender_address_type": "Address", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_text": "123 Sender St, Springfield, IL 62701", "recipient_name": "Recipient Example", "recipient_address_type": "Address", "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG", "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701", "double_sided": true, "color": false, "mail_class": "standard", "certified": false, "certified_return_receipt": false }, { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "sender_name": "Sender Example", "sender_address_type": "Address", "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG", "sender_address_text": "123 Sender St, Springfield, IL 62701", "double_sided": true, "color": false, "mail_class": "standard", "certified": false, "certified_return_receipt": false, "bulk": { "campaign_name": "April Outreach", "csv_content": "recipient_name,line1,line2,city,state,zip,account_number\nJane Doe,123 Main St,,Springfield,IL,62701,ACCT-100\nJohn Smith,456 Oak Ave,Apt 2,Chicago,IL,60601,ACCT-200", "content_mode": "text", "template_text": "Hello {{recipient_name}}, your account reference is {{account_number}}." } } ] }, "MachineWorkflowFormListResponse": { "type": "object", "additionalProperties": false, "properties": { "forms": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "certified_mail": { "type": "string", "enum": [ "required", "optional", "none" ] }, "recipient_mode": { "type": "string" }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "id", "label", "required" ] } }, "create_paths": { "type": "object", "additionalProperties": false, "properties": { "x402": { "type": "string" }, "mpp": { "type": "string" } }, "required": [ "x402", "mpp" ] } }, "required": [ "slug", "name", "certified_mail", "recipient_mode", "attachments", "create_paths" ] } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "forms", "next_cursor" ] }, "MachineWorkflowFormSchema": { "type": "object", "additionalProperties": true, "description": "Machine-usable workflow schema returned by the same schema renderer used by PostalForm MCP. It includes fields, groups, attachments, dependencies, and machine_submission.create_paths." }, "MachineFlowerLetterRequest": { "type": "object", "additionalProperties": false, "description": "Dedicated flower-letter payload for machine payment flows. PostalForm validates the Florist One product, ZIP delivery dates, and total before issuing a payment challenge. The requester IP is collected from the incoming request.", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "Client-generated idempotency key. Reuse the same value and exact body after a 402 challenge." }, "buyer_name": { "type": "string", "minLength": 1, "maxLength": 100 }, "buyer_email": { "type": "string", "format": "email", "maxLength": 100 }, "note": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Message attached to the real flowers on the florist card." }, "zipcode": { "type": "string", "pattern": "^\\d{5}(?:-\\d{4})?$", "description": "Recipient delivery ZIP used for Florist One catalog totals and delivery dates." }, "product_code": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Florist One product code selected from the catalog." }, "delivery_date": { "type": "string", "format": "date", "description": "Requested Florist One delivery date. The date is checked again after payment." }, "customer": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "phone": { "type": "string", "minLength": 1, "maxLength": 32, "description": "US 10 digit phone number. Formatting characters are accepted." }, "address1": { "type": "string", "minLength": 1, "maxLength": 100 }, "address2": { "type": "string", "maxLength": 100 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "pattern": "^[A-Z]{2}$" }, "zipcode": { "type": "string", "pattern": "^\\d{5}(?:-\\d{4})?$" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Two-letter country code. Defaults to US when omitted." }, "email": { "type": "string", "format": "email", "description": "Optional customer email. Defaults to buyer_email when omitted." } }, "required": [ "name", "phone", "address1", "city", "state", "zipcode" ] }, "recipient": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "phone": { "type": "string", "minLength": 1, "maxLength": 32, "description": "US 10 digit phone number. Formatting characters are accepted." }, "address1": { "type": "string", "minLength": 1, "maxLength": 100 }, "address2": { "type": "string", "maxLength": 100 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "state": { "type": "string", "pattern": "^[A-Z]{2}$" }, "zipcode": { "type": "string", "pattern": "^\\d{5}(?:-\\d{4})?$" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Two-letter country code. Defaults to US when omitted." }, "institution": { "type": "string", "maxLength": 100, "description": "Optional facility, business, or hospital name." } }, "required": [ "name", "phone", "address1", "city", "state", "zipcode" ] }, "special_instructions": { "type": "string", "maxLength": 100 }, "allow_substitutions": { "type": "boolean", "description": "Defaults to true." } }, "required": [ "request_id", "buyer_name", "buyer_email", "note", "zipcode", "product_code", "delivery_date", "customer", "recipient" ], "examples": [ { "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b", "buyer_name": "Agent Owner", "buyer_email": "owner@example.com", "note": "For your desk, your day, and the smile I hope this brings.", "zipcode": "32503", "product_code": "F1-509", "delivery_date": "2026-05-08", "customer": { "name": "Agent Owner", "phone": "8505550100", "address1": "123 Sender St", "city": "Pensacola", "state": "FL", "zipcode": "32503", "country": "US", "email": "owner@example.com" }, "recipient": { "name": "Recipient Example", "phone": "8505550199", "address1": "456 Recipient Ave", "city": "Pensacola", "state": "FL", "zipcode": "32503", "country": "US" }, "allow_substitutions": true } ] }, "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" } ] }, "MachineOrder": { "type": "object", "additionalProperties": true, "properties": { "checkout_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Signed hosted-checkout fallback for this exact prepared PDF, letter, form, postcard or ordinary bulk order. Give this to the buyer when no compatible wallet is available. GET only reviews; continuing selects hosted payment. Null when payment has started or the order is closed. Poll status_url for a fresh link." }, "status_url": { "type": "string", "format": "uri", "description": "Poll this same order after either payment path." }, "page_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payment_options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mpp", "x402", "hosted_checkout" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type" ] } }, "next_action": { "type": "string", "enum": [ "choose_payment_method", "open_checkout", "poll_status" ] }, "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": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "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" ] }, "MachineHostedCheckoutSelected": { "type": "object", "additionalProperties": true, "properties": { "checkout_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Signed hosted-checkout fallback for this exact prepared PDF, letter, form, postcard or ordinary bulk order. Give this to the buyer when no compatible wallet is available. GET only reviews; continuing selects hosted payment. Null when payment has started or the order is closed. Poll status_url for a fresh link." }, "status_url": { "type": "string", "format": "uri", "description": "Poll this same order after either payment path." }, "page_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payment_options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mpp", "x402", "hosted_checkout" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type" ] } }, "next_action": { "type": "string", "enum": [ "choose_payment_method", "open_checkout", "poll_status" ] }, "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": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "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." }, "code": { "type": "string", "enum": [ "hosted_checkout_selected" ] }, "message": { "type": "string" } }, "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", "code", "message" ] }, "MachineOrderStatus": { "type": "object", "additionalProperties": true, "properties": { "checkout_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Signed hosted-checkout fallback for this exact prepared PDF, letter, form, postcard or ordinary bulk order. Give this to the buyer when no compatible wallet is available. GET only reviews; continuing selects hosted payment. Null when payment has started or the order is closed. Poll status_url for a fresh link." }, "status_url": { "type": "string", "format": "uri", "description": "Poll this same order after either payment path." }, "page_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payment_options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mpp", "x402", "hosted_checkout" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type" ] } }, "next_action": { "type": "string", "enum": [ "choose_payment_method", "open_checkout", "poll_status" ] }, "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": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "testnet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "protocol", "method", "network", "recipient", "settlement_reference", "settled_at" ] }, "x402": { "type": "object", "additionalProperties": false, "properties": { "network": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pay_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settlement_tx": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "network", "pay_to", "settlement_tx", "settled_at" ] }, "campaign_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Bulk campaign dashboard route for mailing_campaign orders. Null for single-recipient orders." }, "order_complete_url": { "type": "string", "description": "Either the completion URL after payment settles or a placeholder message before settlement." } }, "required": [ "order_id", "status", "payment_status", "is_paid", "current_step", "payment_intent_id", "payment_channel", "price_usd", "currency", "mailpiece_type", "postcard_size", "postcard_guidelines_url", "machine_payment", "order_complete_url" ] }, "MachineOrderValidationResponse": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "format": "uuid" }, "request_hash": { "type": "string" }, "order_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Canonical server order id for an existing reusable draft, if one was found. This may differ from request_id when PostalForm collapses duplicate unpaid attempts." }, "status": { "type": "string", "enum": [ "validated_existing_order", "validated_new_order" ] }, "postcard_guidelines_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Canonical postcard PDF formatting guide. Present for postcard validation responses and null for letter responses." }, "bulk": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "recipient_count": { "type": "integer", "minimum": 1 }, "content_mode": { "type": "string", "enum": [ "text", "html", "pdf" ] } }, "required": [ "recipient_count", "content_mode" ] }, { "type": "null" } ], "description": "Bulk campaign metadata when validating a bulk machine request. Null for single-recipient orders." }, "quote": { "type": "object", "additionalProperties": false, "properties": { "price_usd": { "type": "number" }, "full_price_usd": { "type": "number" }, "currency": { "type": "string", "enum": [ "usd" ] }, "page_count": { "type": "integer", "minimum": 1 }, "billable_page_count": { "type": "integer", "minimum": 1 }, "double_sided": { "type": "boolean" }, "color": { "type": "boolean" }, "mail_class": { "type": "string", "enum": [ "standard", "priority", "express" ] }, "certified": { "type": "boolean" }, "certified_return_receipt": { "type": "boolean" }, "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" ] }, "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" ] }, "MachineFlowerLetterOrder": { "type": "object", "additionalProperties": true, "properties": { "order_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "is_paid": { "type": "boolean" }, "current_step": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_intent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payment_channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_usd": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "product_type": { "type": "string", "enum": [ "flower_letter" ] }, "order_complete_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "order_id", "status", "payment_status", "is_paid", "current_step", "payment_intent_id", "payment_channel", "price_usd", "currency", "product_type" ] }, "FlowerLetterPaymentRequiredResponse": { "type": "object", "additionalProperties": true, "properties": { "order_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "payment_required" ] }, "product_type": { "type": "string", "enum": [ "flower_letter" ] }, "message": { "type": "string" }, "price_breakdown": { "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "product_name": { "type": "string" }, "delivery_zipcode": { "type": "string" }, "arrangement_price_cents": { "type": "integer", "description": "Arrangement price before Florist One delivery charges and destination tax." }, "delivery_charge_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "tax_total_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "order_total_cents": { "type": "integer" }, "currency": { "type": "string", "enum": [ "usd" ] }, "note": { "type": "string" } }, "required": [ "product_name", "delivery_zipcode", "arrangement_price_cents", "delivery_charge_cents", "tax_total_cents", "order_total_cents", "currency", "note" ] }, { "type": "null" } ] } }, "required": [ "order_id", "request_id", "status", "product_type", "message" ] }, "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" ] }, "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" ] }, "X402PaymentRequiredResponse": { "type": "object", "additionalProperties": false, "properties": { "checkout_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Signed hosted-checkout fallback for this exact prepared PDF, letter, form, postcard or ordinary bulk order. Give this to the buyer when no compatible wallet is available. GET only reviews; continuing selects hosted payment. Null when payment has started or the order is closed. Poll status_url for a fresh link." }, "status_url": { "type": "string", "format": "uri", "description": "Poll this same order after either payment path." }, "page_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payment_options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mpp", "x402", "hosted_checkout" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type" ] } }, "next_action": { "type": "string", "enum": [ "choose_payment_method", "open_checkout", "poll_status" ] }, "price_usd": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "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" }, "payment": { "type": "object", "additionalProperties": false, "description": "The same x402 v2 challenge as the base64 PAYMENT-REQUIRED response header, for clients that can only read response bodies.", "properties": { "protocol": { "type": "string", "enum": [ "x402" ] }, "x402_version": { "type": "integer", "enum": [ 2 ] }, "payment_required": { "type": "object", "additionalProperties": true, "description": "Decoded x402 v2 PaymentRequired object: x402Version, error, resource, accepts and extensions." }, "payment_required_header": { "type": "string", "description": "Base64 PAYMENT-REQUIRED header value." }, "retry_header": { "type": "string", "enum": [ "PAYMENT-SIGNATURE" ] } }, "required": [ "protocol", "x402_version", "payment_required", "payment_required_header", "retry_header" ] }, "next_step": { "type": "string" } }, "required": [ "order_id", "request_id", "status", "message" ] }, "MppPaymentRequiredResponse": { "type": "object", "additionalProperties": true, "properties": { "checkout_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Signed hosted-checkout fallback for this exact prepared PDF, letter, form, postcard or ordinary bulk order. Give this to the buyer when no compatible wallet is available. GET only reviews; continuing selects hosted payment. Null when payment has started or the order is closed. Poll status_url for a fresh link." }, "status_url": { "type": "string", "format": "uri", "description": "Poll this same order after either payment path." }, "page_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "payment_options": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mpp", "x402", "hosted_checkout" ] }, "url": { "type": "string", "format": "uri" } }, "required": [ "type" ] } }, "next_action": { "type": "string", "enum": [ "choose_payment_method", "open_checkout", "poll_status" ] }, "price_usd": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "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" } ] }, "www_authenticate": { "type": "array", "items": { "type": "string" }, "description": "The same MPP challenges as the WWW-Authenticate response headers, for clients that can only read response bodies." } }, "required": [ "code", "order_id", "request_id", "message", "supported_methods" ] }, "MachineErrorResponse": { "type": "object", "additionalProperties": false, "properties": { "message": { "type": "string" }, "code": { "type": "string" }, "order_id": { "type": "string", "format": "uuid" }, "errors": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "fix_examples": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] } } }, "required": [ "path", "code", "message" ] } } }, "required": [ "message", "code" ] } } } }