{"uid":"cap_uO3-O0rk-Mw7GeKFtZa7V","slug":"postalform-validate-101cd1f7","name":"PostalForm MPP Order Validate","description":"Validate an MPP machine order and return a quote","url":"https://postalform.com/api/machine/mpp/orders/validate?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","allOf":[{"if":{"required":["bulk"],"properties":{"bulk":{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}}},"then":{"required":["pdf"],"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","required":["upload_token"],"properties":{"upload_token":{"type":"string","minLength":1,"description":"Preferred canonical PDF reference. Get this from PostalForm PDF upload tooling."}},"additionalProperties":false},{"type":"object","required":["download_url","file_id"],"properties":{"file_id":{"type":"string","minLength":1,"description":"Stable file identifier paired with download_url."},"download_url":{"type":"string","format":"uri","description":"HTTPS URL to a PDF file."}},"additionalProperties":true}]}}}}],"oneOf":[{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["pdf","recipient_name","sender_address_id","sender_address_text","recipient_address_id","recipient_address_text"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["pdf","recipient_name","sender_address_id","sender_address_text","recipient_address_manual"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["pdf","recipient_name","sender_address_manual","recipient_address_id","recipient_address_text"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["pdf","recipient_name","sender_address_manual","recipient_address_manual"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["form","recipient_name","sender_address_id","sender_address_text","recipient_address_id","recipient_address_text"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["form","recipient_name","sender_address_id","sender_address_text","recipient_address_manual"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["form","recipient_name","sender_address_manual","recipient_address_id","recipient_address_text"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["form","recipient_name","sender_address_manual","recipient_address_manual"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["letter","recipient_name","sender_address_id","sender_address_text","recipient_address_id","recipient_address_text"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["letter","recipient_name","sender_address_id","sender_address_text","recipient_address_manual"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["letter","recipient_name","sender_address_manual","recipient_address_id","recipient_address_text"]},{"not":{"required":["bulk"],"properties":{"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false}}},"required":["letter","recipient_name","sender_address_manual","recipient_address_manual"]},{"required":["bulk","sender_address_id","sender_address_text"]},{"required":["bulk","sender_address_manual"]}],"examples":[{"pdf":{"upload_token":"pfu_123"},"color":false,"certified":false,"file_name":"letter.pdf","buyer_name":"Agent Owner","mail_class":"standard","request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_email":"owner@example.com","sender_name":"Sender Example","double_sided":true,"err_delivery":"manual","recipient_name":"Recipient Example","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","restricted_delivery":false,"sender_address_text":"123 Sender St, Springfield, IL 62701","sender_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","return_receipt_format":"electronic","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","recipient_address_type":"Address","certified_return_receipt":false},{"form":{"slug":"5471","fields":{"field_5":"Example Corporation Inc.","field_6":"123 Market St","field_8":"Wilmington","field_9":"DE","field_10":"19801","field_11":"123-45-6789","foreign_corporation_period_end":"12/31/2025","foreign_corporation_period_begin":"01/01/2025"}},"color":false,"certified":false,"file_name":"5471.pdf","buyer_name":"Agent Owner","mail_class":"standard","request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_email":"owner@example.com","sender_name":"Sender Example","double_sided":true,"recipient_name":"Recipient Example","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","sender_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","recipient_address_type":"Address","certified_return_receipt":false},{"color":false,"letter":{"body":"# Account notice\n\nPlease review the enclosed account update and contact us with any questions.","title":"Account notice","format":"markdown","signature":"Sender Example"},"certified":false,"file_name":"account-notice.pdf","buyer_name":"Agent Owner","mail_class":"standard","request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_email":"owner@example.com","sender_name":"Sender Example","double_sided":true,"recipient_name":"Recipient Example","sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","sender_address_type":"Address","recipient_address_id":"US|LP|Pz0_Qj4_bGJg|199825276|99_ENG","recipient_address_text":"456 Recipient Ave, Springfield, IL 62701","recipient_address_type":"Address","certified_return_receipt":false},{"bulk":{"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","campaign_name":"April Outreach","template_text":"Hello {{recipient_name}}, your account reference is {{account_number}}."},"color":false,"certified":false,"buyer_name":"Agent Owner","mail_class":"standard","request_id":"8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b","buyer_email":"owner@example.com","sender_name":"Sender Example","double_sided":true,"sender_address_id":"US|LP|Pz0_Qj4_bGJg|16074807|13_ENG","sender_address_text":"123 Sender St, Springfield, IL 62701","sender_address_type":"Address","certified_return_receipt":false}],"required":["request_id","buyer_name","buyer_email","sender_name"],"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","required":["upload_token"],"properties":{"upload_token":{"type":"string","minLength":1,"description":"Preferred canonical PDF reference. Get this from PostalForm PDF upload tooling."}},"additionalProperties":false},{"type":"object","required":["download_url","file_id"],"properties":{"file_id":{"type":"string","minLength":1,"description":"Stable file identifier paired with download_url."},"download_url":{"type":"string","format":"uri","description":"HTTPS URL to a PDF file."}},"additionalProperties":true}]},"bulk":{"type":"object","allOf":[{"oneOf":[{"required":["csv_content"]},{"required":["recipients"]}]}],"oneOf":[{"type":"object","required":["content_mode","template_text"],"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."}}},{"type":"object","required":["content_mode","template_html"],"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."}}},{"type":"object","required":["content_mode"],"properties":{"content_mode":{"const":"pdf"}}}],"required":["content_mode"],"properties":{"recipients":{"type":"array","items":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["line1","city","zip"],"properties":{"zip":{"type":"string","minLength":1,"description":"ZIP/postal code as a string, preserving leading zeros."},"city":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"anyOf":[{"type":"string"},{"type":"null"}]},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Required for US and Canadian recipients. Omit or send null elsewhere."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Mailing country code. Defaults to US."},"merge_fields":{"type":"object","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.","propertyNames":{"type":"string","pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"null"}]}},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"minItems":1,"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."},"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."},"content_mode":{"enum":["text","html","pdf"],"type":"string","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."},"campaign_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional human-readable campaign label."},"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."},"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."}},"additionalProperties":false},"form":{"type":"object","required":["slug","fields"],"properties":{"slug":{"type":"string","minLength":1,"description":"Workflow form slug, for example 1120, 5471, or 5472."},"fields":{"type":"object","description":"Workflow field values keyed by field id from the machine form schema. Compound fields use nested objects keyed by subfield id.","additionalProperties":true},"attachments":{"type":"array","items":{"type":"object","required":["id","base64"],"properties":{"id":{"type":"string","minLength":1,"description":"Attachment id from the selected workflow schema."},"label":{"type":"string","minLength":1},"base64":{"type":"string","minLength":1,"description":"Base64 file content or a data:<mime>;base64,... URL."},"file_name":{"type":"string","maxLength":255,"minLength":1},"content_type":{"type":"string","minLength":1,"description":"Optional MIME type. A data URL MIME type also works inside base64."}},"additionalProperties":false},"description":"Optional supporting files required by the workflow schema."}},"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.","additionalProperties":false},"color":{"type":"boolean","description":"Defaults to false."},"format":{"enum":["text","html","markdown","rtf"],"type":"string","description":"Optional shorthand for letter.format when letter is provided. Defaults to text."},"letter":{"oneOf":[{"type":"string","maxLength":20000,"minLength":1,"description":"Letter body text for PostalForm to render server-side. Uses text format unless top-level format is set."},{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":20000,"minLength":1},"title":{"type":"string","maxLength":200},"format":{"enum":["text","html","markdown","rtf"],"type":"string","description":"How PostalForm renders body. Defaults to text."},"render":{"type":"object","properties":{"font":{"enum":["times","helvetica"],"type":"string"},"paper":{"enum":["letter"],"type":"string","description":"Only letter paper is supported for machine-rendered letters."},"font_size":{"type":"integer","maximum":14,"minimum":9},"margin_in":{"type":"number","maximum":1.5,"minimum":0.5}},"additionalProperties":false},"signature":{"anyOf":[{"type":"string","maxLength":2000},{"type":"object","properties":{"mode":{"enum":["typed","drawn"],"type":"string"},"text":{"type":"string","maxLength":2000},"dataUrl":{"type":"string"},"printDataUrl":{"type":"string"}},"additionalProperties":false}]}},"additionalProperties":false}],"description":"Letter content for PostalForm to render server-side into a PDF. Provide exactly one of pdf, form, or letter."},"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."},"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."},"file_name":{"type":"string","maxLength":255,"minLength":1,"description":"Optional display file name."},"buyer_name":{"type":"string","maxLength":256,"minLength":1,"description":"Buyer / wallet owner display name."},"mail_class":{"enum":["standard","priority","express"],"type":"string","description":"Mail service level. Defaults to standard."},"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_email":{"type":"string","format":"email","maxLength":256,"description":"Required for Stripe receipt delivery."},"sender_name":{"type":"string","maxLength":256,"minLength":1},"double_sided":{"type":"boolean","description":"Defaults to true."},"err_delivery":{"enum":["manual","email"],"type":"string","description":"Defaults to manual USPS retrieval. Email makes PostalForm acquire and email the electronic receipt when available."},"postcard_size":{"enum":["4x6","6x9","11x6"],"type":"string","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."},"mailpiece_type":{"enum":["letter","postcard"],"type":"string","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."},"recipient_name":{"type":"string","maxLength":256,"minLength":1},"sender_address_id":{"type":"string","pattern":"^[A-Za-z]{2,4}\\|","minLength":1,"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."},"signature_required":{"type":"boolean","description":"Request USPS signature on delivery. Defaults to false. Forced false for postcards or when mail_class is standard."},"restricted_delivery":{"type":"boolean","description":"Requests USPS Restricted Delivery for addressee-only delivery. Requires certified_return_receipt=true."},"sender_address_text":{"type":"string","maxLength":2000,"minLength":1,"description":"Human-readable address text for sender Address mode."},"sender_address_type":{"enum":["Address","Manual"],"type":"string","description":"Address strategy for the sender. Omit to default to Address when manual fields are absent."},"recipient_address_id":{"type":"string","pattern":"^[A-Za-z]{2,4}\\|","minLength":1,"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."},"return_receipt_format":{"enum":["electronic","physical"],"type":"string","description":"Electronic selects the signed USPS PDF. Physical selects the mailed PS Form 3811 green card. Requires certified_return_receipt=true."},"sender_address_manual":{"type":"object","required":["line1","city","zip"],"properties":{"zip":{"type":"string","maxLength":20,"minLength":1,"description":"ZIP or postal code."},"city":{"type":"string","maxLength":128,"minLength":1,"description":"City or locality."},"line1":{"type":"string","maxLength":256,"minLength":1,"description":"Street address line 1."},"line2":{"type":"string","maxLength":256,"minLength":1,"description":"Optional unit, suite, or secondary line."},"state":{"type":"string","maxLength":60,"minLength":1,"description":"State, province, or region. Required for US and Canada."},"countryCode":{"enum":["US","CA","AT","BE","CH","DE","ES","FR","GB","IN","LU","NL"],"type":"string","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."}},"description":"Manual sender address. Required for sender Manual mode.","additionalProperties":false},"recipient_address_text":{"type":"string","maxLength":2000,"minLength":1,"description":"Human-readable address text for recipient Address mode."},"recipient_address_type":{"enum":["Address","Manual"],"type":"string","description":"Address strategy for the recipient. Omit to default to Address when manual fields are absent."},"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."},"recipient_address_manual":{"type":"object","required":["line1","city","zip"],"properties":{"zip":{"type":"string","maxLength":20,"minLength":1,"description":"ZIP or postal code."},"city":{"type":"string","maxLength":128,"minLength":1,"description":"City or locality."},"line1":{"type":"string","maxLength":256,"minLength":1,"description":"Street address line 1."},"line2":{"type":"string","maxLength":256,"minLength":1,"description":"Optional unit, suite, or secondary line."},"state":{"type":"string","maxLength":60,"minLength":1,"description":"State, province, or region. Required for US and Canada."},"countryCode":{"enum":["US","CA","AT","BE","CH","DE","ES","FR","GB","IN","LU","NL"],"type":"string","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."}},"description":"Manual recipient address. Required for recipient Manual mode.","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.","additionalProperties":false},"responseSchema":{"type":"object","required":["request_id","request_hash","order_id","status","postcard_guidelines_url","quote"],"properties":{"bulk":{"anyOf":[{"type":"object","required":["recipient_count","content_mode"],"properties":{"content_mode":{"enum":["text","html","pdf"],"type":"string"},"recipient_count":{"type":"integer","minimum":1}},"additionalProperties":false},{"type":"null"}],"description":"Bulk campaign metadata when validating a bulk machine request. Null for single-recipient orders."},"quote":{"type":"object","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"],"properties":{"color":{"type":"boolean"},"currency":{"enum":["usd"],"type":"string"},"provider":{"type":"string"},"certified":{"type":"boolean"},"err_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"price_usd":{"type":"number"},"mail_class":{"enum":["standard","priority","express"],"type":"string"},"page_count":{"type":"integer","minimum":1},"double_sided":{"type":"boolean"},"err_delivery":{"enum":["manual","email"],"type":"string"},"postcard_size":{"anyOf":[{"enum":["4x6","6x9","11x6"],"type":"string"},{"type":"null"}]},"full_price_usd":{"type":"number"},"mailpiece_type":{"enum":["letter","postcard"],"type":"string"},"signature_required":{"type":"boolean"},"billable_page_count":{"type":"integer","minimum":1},"restricted_delivery":{"type":"boolean"},"return_receipt_format":{"enum":["electronic","physical"],"type":"string"},"certified_return_receipt":{"type":"boolean"}},"additionalProperties":false},"status":{"enum":["validated_existing_order","validated_new_order"],"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."},"request_id":{"type":"string","format":"uuid"},"request_hash":{"type":"string"},"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."}},"additionalProperties":false},"example":null,"exampleRequest":null,"tags":["mail","print","letters","physical","postal","web"],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"proven_free","priceSource":"registry","requiresHandshake":false,"reviewCount":1,"rating":{"score":"0.58","successRate":"0.50","reviews":1,"stars":"3.3","state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"free","summary":"Free","primary":null,"accepted":[]},"paymentMethods":[],"brandName":"PostalForm","brandSlug":"postalform","brandBaseUrl":"https://postalform.com","brandDocsUrl":"https://postalform.com/agents","whatItDoes":"Validates an MPP machine print-and-mail order and returns a price quote before payment and fulfillment","exampleAgentPrompt":"Before I pay, validate my PostalForm letter order and give me a quote — it's a single-page color letter on standard mail class, sending from 123 Main St, Springfield IL 62701 to Jane Doe at 456 Elm Ave, Chicago IL 60601, using the PDF I uploaded.","exampleUseCases":null,"resultDescription":"Returns a validated order object including a unique order ID, request ID, request hash, a detailed quote (price in USD, page count, billable page count, mail class, mailpiece type, color, double-sided, certified flags, and the upstream provider), validation status indicating whether this is a new or existing draft order, and a postcard guidelines URL if applicable. For bulk campaigns, also returns the recipient count and content mode.","failureModes":["Missing required fields (recipient name, sender/recipient address, content) returns a 400 validation error","Invalid address format or missing address fields returns a 400 error","Conflicting schema conditions (e.g. bulk PDF mode without pdf field) returns a 400 error","Unauthenticated or unpaid requests return 402 Payment Required with WWW-Authenticate challenge","Invalid PDF or unsupported content mode returns a 422 error","Network timeout returns a 5xx error"],"whenToPreferThis":"Use this endpoint when you need to validate a PostalForm MPP machine order and obtain a binding price quote before committing to payment and fulfillment. It is the required pre-flight step before placing a real postal order via PostalForm's agent-native API. Choose this over generic postal APIs when you need AI-agent-friendly structured quotes with certified mail options, bulk campaign validation, and postcard or letter mailpiece types.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":6,"lastUsedAt":"2026-07-06T21:52:21.266Z","lastSuccessfullyRanAt":"2026-07-06T21:52:21.266Z","lastHealthCheckAt":"2026-10-11T12:37:14.452Z","isFirstParty":false,"canonicalSlug":"postalform-validate-101cd1f7"}