Create a single PDF, letter, workflow-form order, or bulk letter campaign and pay through MPP or x402 after buyer approval. For bulk, provide exactly one of bulk.csv_content or bulk.recipients (JSON address objects with optional merge_fields), plus a shared PDF or text/HTML template. Omit top-level recipient fields and review campaign_url, recipient count and total. Bulk MPP orders can also use postalform.pay_order after fetching its challenge. The unpaid response also includes checkout_url and status_url for this same order. Without an available compatible wallet, give the buyer checkout_url and poll status_url; never recreate the order to change payment paths. Single-recipient clients with a Stripe shared payment token can instead use a draft tool followed by complete_checkout; other clients should present the hosted checkout URL.
View input schema
{
"type": "object",
"properties": {
"payment_protocol": {
"description": "Direct machine payment protocol. Use mpp for Link CLI/Link MCP or Stripe SPT; use x402 for x402 wallet clients. Defaults to mpp.",
"type": "string",
"enum": [
"mpp",
"x402"
]
},
"request_id": {
"description": "Idempotency key. Reuse the same value and same order fields after a payment challenge.",
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"buyer_name": {
"type": "string",
"minLength": 1,
"maxLength": 256,
"description": "Buyer name for receipts."
},
"buyer_email": {
"type": "string",
"maxLength": 256,
"format": "email",
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"description": "Buyer email for receipts."
},
"pdf": {
"description": "Existing PDF to mail. For a single recipient, provide exactly one of pdf, letter, or form. For bulk.content_mode=pdf, this PDF is sent to every CSV or JSON recipient. Prefer upload_token from postalform.create_pdf_upload.",
"anyOf": [
{
"type": "object",
"properties": {
"download_url": {
"type": "string",
"format": "uri"
},
"file_id": {
"type": "string"
}
},
"required": [
"download_url",
"file_id"
]
},
{
"type": "object",
"properties": {
"upload_token": {
"type": "string",
"minLength": 1
}
},
"required": [
"upload_token"
]
},
{
"type": "string",
"minLength": 1
}
]
},
"letter": {
"description": "Letter text to render and mail. Provide exactly one of pdf, letter, or form. Optional format may be text, html, markdown, or rtf; default is text. Optional signature may be a typed string or drawn signature payload.",
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 200
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 20000
},
"signature": {
"anyOf": [
{
"type": "string",
"maxLength": 2000
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"typed",
"drawn"
]
},
"text": {
"type": "string",
"maxLength": 2000
},
"dataUrl": {
"type": "string"
},
"printDataUrl": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"render": {
"type": "object",
"properties": {
"paper": {
"type": "string",
"const": "letter"
},
"font_size": {
"type": "integer",
"minimum": 9,
"maximum": 14
},
"margin_in": {
"type": "number",
"minimum": 0.5,
"maximum": 1.5
},
"font": {
"type": "string",
"enum": [
"times",
"helvetica"
]
}
}
},
"format": {
"type": "string",
"enum": [
"text",
"html",
"markdown",
"rtf"
]
}
},
"required": [
"body"
]
},
"form": {
"description": "Workflow form payload from postalform.get_form_schema. Provide exactly one of pdf, letter, or form.",
"type": "object",
"properties": {
"slug": {
"type": "string",
"minLength": 1
},
"fields": {
"default": {},
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"attachments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"file_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"content_type": {
"type": "string",
"minLength": 1
},
"base64": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"base64"
]
}
}
},
"required": [
"slug"
]
},
"bulk": {
"description": "Bulk letter campaign: exactly one of csv_content or recipients (JSON list), plus shared PDF or text/HTML template. Omit single-recipient fields, letter, form, and postcard options. color and double_sided apply to every mailpiece.",
"type": "object",
"properties": {
"campaign_name": {
"type": "string",
"maxLength": 255
},
"csv_content": {
"description": "Recipient CSV text, mutually exclusive with recipients. Required columns: line1, city, state, zip. Optional: recipient_name, line2, country. Other columns can be used as merge fields.",
"type": "string",
"minLength": 1
},
"recipients": {
"description": "JSON recipient list, mutually exclusive with csv_content. Each address can include merge_fields for text/HTML templates.",
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"recipient_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"line1": {
"type": "string",
"minLength": 1
},
"line2": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"city": {
"type": "string",
"minLength": 1
},
"state": {
"description": "Required for US and Canadian recipients. Omit or send null elsewhere.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"zip": {
"type": "string",
"minLength": 1,
"description": "ZIP/postal code as a string, preserving leading zeros."
},
"country": {
"description": "Mailing country code. Defaults to US.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"merge_fields": {
"description": "Optional template values. {{field_name}} inserts a value as plain text (HTML-escaped in html mode); in html mode, {{{field_name}}} inserts it as HTML. Address field names and full_address are reserved.",
"type": "object",
"propertyNames": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]*$"
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
}
}
},
"required": [
"line1",
"city",
"zip"
],
"additionalProperties": false
}
},
"content_mode": {
"type": "string",
"enum": [
"text",
"html",
"pdf"
],
"description": "pdf sends the same top-level PDF to every recipient; text/html render template_text/template_html with CSV columns or JSON merge_fields."
},
"template_text": {
"description": "Plain-text letter template. {{field}} inserts a merge value; HTML is not allowed.",
"type": "string"
},
"template_html": {
"description": "HTML letter template. {{field}} inserts a merge value as escaped text; {{{field}}} inserts it as HTML (use this for per-recipient HTML bodies). Scripts and remote resources are not loaded; embed images as data: URLs.",
"type": "string"
}
},
"required": [
"content_mode"
],
"additionalProperties": false
},
"file_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"sender_name": {
"type": "string",
"minLength": 1,
"maxLength": 255
},
"sender_address_id": {
"type": "string",
"minLength": 1
},
"sender_address_type": {
"type": "string",
"enum": [
"Address",
"Manual"
]
},
"sender_address_text": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"sender_address_manual": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"minLength": 1
},
"line2": {
"type": "string",
"minLength": 1
},
"city": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"zip": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"countryCode": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
},
"required": [
"line1",
"city",
"zip"
]
},
"recipient_name": {
"description": "Required for a single recipient. Omit when bulk supplies the recipient list.",
"type": "string",
"minLength": 1,
"maxLength": 255
},
"recipient_address_id": {
"type": "string",
"minLength": 1
},
"recipient_address_type": {
"type": "string",
"enum": [
"Address",
"Manual"
]
},
"recipient_address_text": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"recipient_address_manual": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"minLength": 1
},
"line2": {
"type": "string",
"minLength": 1
},
"city": {
"type": "string",
"minLength": 1
},
"state": {
"type": "string",
"minLength": 1,
"maxLength": 60
},
"zip": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"countryCode": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
},
"required": [
"line1",
"city",
"zip"
]
},
"double_sided": {
"type": "boolean"
},
"color": {
"type": "boolean"
},
"mail_class": {
"type": "string",
"enum": [
"standard",
"priority",
"express"
]
},
"certified": {
"type": "boolean"
},
"certified_return_receipt": {
"type": "boolean"
},
"signature_required": {
"type": "boolean"
},
"mailpiece_type": {
"type": "string",
"enum": [
"letter",
"postcard"
]
},
"postcard_size": {
"type": "string",
"enum": [
"4x6",
"6x9",
"11x6"
]
},
"payment_authorization": {
"description": "MPP retry value after paying with Link CLI/Link MCP. Pass the full Authorization header value, usually \"Payment ...\".",
"type": "string",
"minLength": 1
},
"payment_signature": {
"description": "x402 retry value after paying the PAYMENT-REQUIRED challenge.",
"type": "string",
"minLength": 1
}
},
"required": [
"buyer_name",
"buyer_email",
"sender_name"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}