{"uid":"cap_zAIfTfY-yHd8v2DCy9SoX","slug":"postalform-orders-db85ec47","name":"PostalForm MPP Orders","description":"Unauthenticated calls return 402 Payment Required with WWW-Authenticate: Payment challenges. Retry the exact same body with Authorization: Payment after settlement.","url":"https://postalform.com/api/machine/mpp/orders?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":["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"],"properties":{"x402":{"type":"object","required":["network","pay_to","settlement_tx","settled_at"],"properties":{"pay_to":{"anyOf":[{"type":"string"},{"type":"null"}]},"network":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"settlement_tx":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false},"status":{"type":"string"},"is_paid":{"type":"boolean"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"order_id":{"type":"string","format":"uuid","description":"Canonical server order id. This may differ from request_id when PostalForm reuses an existing unpaid draft."},"certified":{"type":"boolean"},"err_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}]},"price_usd":{"anyOf":[{"type":"number"},{"type":"string"},{"type":"null"}]},"err_status":{"enum":["manual","pending","sent","failed"],"type":"string"},"page_count":{"anyOf":[{"type":"number"},{"type":"null"}]},"status_url":{"type":"string","format":"uri","description":"Poll this same order after either payment path."},"next_action":{"enum":["choose_payment_method","open_checkout","poll_status"],"type":"string"},"campaign_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulk campaign dashboard route for mailing_campaign orders. Null for single-recipient orders."},"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."},"current_step":{"anyOf":[{"type":"string"},{"type":"null"}]},"err_delivery":{"enum":["manual","email"],"type":"string"},"tracking_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"postcard_size":{"anyOf":[{"enum":["4x6","6x9","11x6"],"type":"string"},{"type":"null"}]},"mailpiece_type":{"enum":["letter","postcard"],"type":"string"},"payment_status":{"type":"string"},"machine_payment":{"type":"object","required":["protocol","method","network","recipient","settlement_reference","settled_at"],"properties":{"method":{"anyOf":[{"type":"string"},{"type":"null"}]},"network":{"anyOf":[{"type":"string"},{"type":"null"}]},"testnet":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"protocol":{"enum":["x402","mpp"],"type":"string"},"recipient":{"anyOf":[{"type":"string"},{"type":"null"}]},"settled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"settlement_reference":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":true},"payment_channel":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_options":{"type":"array","items":{"type":"object","required":["type"],"properties":{"url":{"type":"string","format":"uri"},"type":{"enum":["mpp","x402","hosted_checkout"],"type":"string"}}}},"tracking_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"err_delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"payment_intent_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"usps_tracking_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"restricted_delivery":{"type":"boolean"},"return_receipt_format":{"enum":["electronic","physical"],"type":"string"},"err_document_available":{"type":"boolean"},"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_return_receipt":{"type":"boolean"}},"additionalProperties":true},"example":null,"exampleRequest":null,"tags":["mail","print","letters","physical","postal","web"],"displayCostAmount":"3.4","displayCostAsset":"USDC","priceDynamic":true,"priceHint":"Varies","priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"dynamic","summary":"$3.4/call (dynamic — varies by input)","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":"3.4","per":"call","confidence":"exact"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":"3.4","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_tcgWsjhYaDGFxBMeoMfIy","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"3.4","costPer":"request","priority":0,"asset":"usd","unit":"request","depositMicros":null,"planRef":null}],"brandName":"PostalForm","brandSlug":"postalform","brandBaseUrl":"https://postalform.com","brandDocsUrl":"https://postalform.com/agents","whatItDoes":"Create or reuse an MPP machine order to print and mail a physical letter, postcard, or form to a recipient via postal service.","exampleAgentPrompt":"Use PostalForm to mail a physical letter to John Smith at 123 Main St, Springfield IL 62701 — the sender is Acme Corp at 456 Oak Ave, Chicago IL 60601 — and use this PDF I have for the content.","exampleUseCases":null,"resultDescription":"Returns a UUID order_id, payment status (is_paid, payment_status), mailpiece type (letter or postcard), postcard size if applicable, current fulfillment step, price in USD, machine payment details including protocol (x402/mpp), network, recipient wallet, and settlement reference, plus a campaign_url for bulk orders.","failureModes":["402 Payment Required on unauthenticated call — must retry with Authorization: Payment header after settlement","Invalid or missing required fields (recipient_name, sender/recipient address, content) returns 422 validation error","PDF or HTML content malformed or too large returns content error","Conflicting oneOf schema branches (e.g. both bulk and single-recipient fields) causes schema validation failure","Address ID not found in account returns 404 or validation error","Bulk template mode mismatch (text mode but no template_text provided) returns validation error"],"whenToPreferThis":"Use this endpoint when an AI agent needs to physically mail a document, letter, postcard, or form to a real postal address — especially for single-recipient or bulk campaigns using PDF, text, or HTML templates. Prefer over alternatives when payment is handled via x402/MPP crypto payment protocols and physical delivery is required rather than digital communication.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T18:31:06.793Z","isFirstParty":false,"canonicalSlug":"postalform-orders-db85ec47"}