Servers Playground How we check Add a server Log in

PostalForm

Working · 2.0 s

com.postalform/postalformv0.1.0 Domain verified

Create mail drafts, upload PDFs, browse forms, track orders, and pay via MPP or x402.

Communication

Website Registry entry

Maintain this server? Claim it

Try it

Call this server's tools from your browser. Nothing to install.

https://postalform.com/mcp

Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.

Tool list from our last check. Connect live to refresh it.

complete_checkout

After the buyer approves the prepared order and total, pay its existing checkout session using a compatible Stripe payment token, including a shared payment token (spt_...). Pass the order ID as checkout_session_id; do not resend the document or addresses. On an interrupted request, retry the same checkout and token. Existing authorized, processing, or paid payments are reused; follow the returned status and messages.

buyerstring, required

Buyer identity details for the approved checkout.

payment_dataobject, required

Buyer-authorized payment token details. Use provider=stripe.

checkout_session_idstring, required

The checkout session id to finalize.

This tool isn't marked read-only, so it may change something on the server or in an account you connected.

I understand, run it anyway

PostalForm MCP server | mcptry

Tools (13)

complete_checkout

Argument	Type	Description
buyer*	any	Buyer identity details for the approved checkout.
payment_data*	object	Buyer-authorized payment token details. Use provider=stripe.
checkout_session_id*	string	The checkout session id to finalize.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "checkout_session_id",
    "buyer",
    "payment_data"
  ],
  "properties": {
    "buyer": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "first_name",
            "email"
          ],
          "properties": {
            "email": {
              "type": "string",
              "format": "email",
              "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
              "maxLength": 256
            },
            "last_name": {
              "type": "string",
              "maxLength": 256,
              "minLength": 1
            },
            "first_name": {
              "type": "string",
              "maxLength": 256,
              "minLength": 1
            },
            "phone_number": {
              "type": "string",
              "maxLength": 32,
              "minLength": 1
            }
          }
        },
        {
          "type": "object",
          "required": [
            "name",
            "email"
          ],
          "properties": {
            "name": {
              "type": "string",
              "maxLength": 256,
              "minLength": 1
            },
            "email": {
              "type": "string",
              "format": "email",
              "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
              "maxLength": 256
            },
            "phone_number": {
              "type": "string",
              "maxLength": 32,
              "minLength": 1
            }
          }
        }
      ],
      "description": "Buyer identity details for the approved checkout."
    },
    "payment_data": {
      "type": "object",
      "required": [
        "token",
        "provider"
      ],
      "properties": {
        "token": {
          "type": "string",
          "minLength": 1
        },
        "provider": {
          "enum": [
            "stripe",
            "adyen"
          ],
          "type": "string"
        },
        "billing_address": {
          "type": "object",
          "required": [
            "name",
            "line_one",
            "city",
            "state",
            "country",
            "postal_code"
          ],
          "properties": {
            "city": {
              "type": "string",
              "maxLength": 60,
              "minLength": 1
            },
            "name": {
              "type": "string",
              "maxLength": 255,
              "minLength": 1
            },
            "state": {
              "type": "string",
              "maxLength": 60,
              "minLength": 1
            },
            "country": {
              "type": "string",
              "maxLength": 2,
              "minLength": 1
            },
            "line_one": {
              "type": "string",
              "maxLength": 60,
              "minLength": 1
            },
            "line_two": {
              "type": "string",
              "maxLength": 60,
              "minLength": 1
            },
            "postal_code": {
              "type": "string",
              "maxLength": 20,
              "minLength": 1
            },
            "phone_number": {
              "type": "string",
              "maxLength": 32,
              "minLength": 1
            }
          }
        }
      },
      "description": "Buyer-authorized payment token details. Use provider=stripe."
    },
    "checkout_session_id": {
      "type": "string",
      "minLength": 1,
      "description": "The checkout session id to finalize."
    }
  }
}

postalform.create_form_order_draft

Prepare a supported workflow form for mailing and return the order ID, total, hosted checkout URL, and checkout session. After buyer approval, a compatible client can use complete_checkout with a Stripe shared payment token; otherwise present the hosted checkout URL. To prepare for MPP, set payment_protocol=mpp and buyer_email; receive a PDF preview, hosted checkout_url fallback and MPP challenge, then use postalform.pay_order with the order_id after buyer approval. Draft creation never pays. For x402, use postalform.create_machine_order.

Argument	Type	Description
slug*	string
color	boolean
fields	object
certified	boolean
buyer_name	string	Receipt name; defaults to sender_name for MPP.
mail_class	string
request_id	string
attachments	array
buyer_email	string	Required for MPP receipt delivery.

postalform.create_letter_order_draft

Prepare letter text for mailing and return the order ID, total, hosted checkout URL, and checkout session. Accepts text directly; no PDF upload or browser is needed. Letter drafts may include typed or drawn signatures. After buyer approval, a compatible client can use complete_checkout with a Stripe shared payment token; otherwise present the hosted checkout URL. To prepare for MPP, set payment_protocol=mpp and buyer_email; receive a PDF preview, hosted checkout_url fallback and MPP challenge, then use postalform.pay_order with the order_id after buyer approval. Draft creation never pays. For x402, use postalform.create_machine_order.

Argument	Type	Description
color	boolean
letter*	object
certified	boolean
buyer_name	string	Receipt name; defaults to sender_name for MPP.
mail_class	string
request_id	string
buyer_email	string	Required for MPP receipt delivery.
sender_name*	string

postalform.create_machine_order

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.

Argument	Type	Description
pdf	any	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.
bulk	object	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.
form	object	Workflow form payload from postalform.get_form_schema. Provide exactly one of pdf, letter, or form.
color	boolean
letter	object	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.

postalform.create_order_draft

Prepare an existing PDF for mailing and return the order ID, total, hosted checkout URL, and checkout session. After buyer approval, a compatible client can pass a Stripe shared payment token to complete_checkout; otherwise present the hosted checkout URL. To prepare for MPP, set payment_protocol=mpp and buyer_email; receive a PDF preview, hosted checkout_url fallback and MPP challenge, then use postalform.pay_order with the order_id after buyer approval. Draft creation never pays. For x402, use postalform.create_machine_order.

Argument	Type	Description
pdf*	any	The PDF to mail. Accepts attachment objects ({ download_url, file_id }). Fallbacks: upload_token from postalform.create_pdf_upload, data:application/pdf;base64,..., or a public HTTPS download URL.
color	boolean	Whether to print in color (default: false).
certified	boolean	Whether to add proof mail: USPS Certified Mail for US destinations, Canada Post Registered Mail through PostGrid for Canadian destinations, or PinGen registered mail for supported European destinations (default: false).
file_name	string	Optional display file name.
buyer_name	string	Receipt name; defaults to sender_name for MPP.
mail_class	string	Mail service level (standard, priority, express).
request_id

postalform.create_pdf_upload

Use this when the host cannot provide a PDF file param directly. It creates a short-lived PDF upload URL and upload token (multipart/form-data, file field). Let the HTTP client generate Content-Type with its multipart boundary.

Argument	Type	Description
file_name	string	Optional original file name.
request_id	string	Optional idempotency key. Reuse the same value if retrying the call.
content_type	string	Optional content type hint (application/pdf).
content_length	integer	Optional content length in bytes.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "file_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Optional original file name."
    },
    "request_id": {
      "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)$",
      "description": "Optional idempotency key. Reuse the same value if retrying the call."
    },
    "content_type": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Optional content type hint (application/pdf)."
    },
    "content_length": {
      "type": "integer",
      "maximum": 9007199254740991,
      "minimum": 0,
      "description": "Optional content length in bytes."
    }
  }
}

postalform.get_form_schema

Use this when you need a machine-usable schema for one supported single-mailpiece PostalForm workflow (fields, groups, attachments, and dependencies).

read-only

Argument	Type	Description
slug*	string	Workflow slug (e.g. "8822").

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "description": "Workflow slug (e.g. \"8822\")."
    }
  }
}

postalform.get_order_status

Read payment, processing, stored mailing/carrier status, the latest 50 public tracking events, and electronic return receipt availability. Bulk orders also return campaign_url, recipient count and per-status counts; use the campaign dashboard for individual recipients. Missing carrier evidence is null; processing or a tracking number alone does not prove mailing or delivery. This read does not pay, mail, or acquire receipts.

read-only

Argument	Type	Description
order_id*	string	PostalForm order id.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "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)$",
      "description": "PostalForm order id."
    }
  }
}

postalform.list_forms

Use this when you need the published single-mailpiece PostalForm workflow catalog available to agents. Coordinated statutory multi-recipient workflows are excluded.

read-only

Argument	Type	Description
q	string	Optional search query (matches slug/name).
limit	integer	Max results (default 50).
cursor	string	Pagination cursor (opaque string).

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "q": {
      "type": "string",
      "description": "Optional search query (matches slug/name)."
    },
    "limit": {
      "type": "integer",
      "maximum": 200,
      "description": "Max results (default 50).",
      "exclusiveMinimum": 0
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor (opaque string)."
    }
  }
}

postalform.pay_order

Get an MPP challenge or pay an existing MPP PDF, letter, workflow-form order, or bulk letter campaign after buyer approval. Use the order_id returned by any draft tool with payment_protocol=mpp or by create_machine_order. When switching from create_machine_order, omit the credential first to get this payment endpoint’s challenge. Review the preview or campaign_url, recipient count and total. No document or addresses are resubmitted. Without payment_authorization this only returns a challenge; with it, this can pay and send real mail. Reuse the same order_id on retries and follow the returned payment status.

Argument	Type	Description
order_id*	string
payment_authorization	string	Buyer-approved MPP Authorization header, usually Payment ... . Omit to retrieve the challenge.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "order_id"
  ],
  "properties": {
    "order_id": {
      "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)$"
    },
    "payment_authorization": {
      "type": "string",
      "minLength": 1,
      "description": "Buyer-approved MPP Authorization header, usually Payment ... . Omit to retrieve the challenge."
    }
  }
}

postalform.ping

Use this when you want a quick health check that the PostalForm MCP server is reachable.

read-only

No arguments.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {}
}

postalform.preview_letter_order_draft

Use this to prepare a non-writing preview for a mailed letter before creating checkout. It renders the letter, validates the addresses, and returns a widget with a create-draft action.

read-only

Argument	Type	Description
color	boolean
letter*	object
certified	boolean
mail_class	string
request_id	string
sender_name*	string
double_sided	boolean
recipient_name*	string
sender_address_id	string
sender_address_text	string

postalform.search_addresses

Use this to search for a mailing address and return Loqate suggestions with IDs. Pass country_code to filter by country; it defaults to US. If a suggestion has type "Container" (building/complex), call this tool again with container=<id> and a refined query to drill down to type "Address". Only type "Address" is valid for order creation.

read-only

Argument	Type	Description
query*	string	Partial address text, e.g. "123 Main St"
target	string	Which address field is being searched (used for UI context).
container	string	Loqate container id for drilling into suggestions, if provided
country_code	string	Two-letter country code to filter suggestions. Defaults to US.

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 3,
      "description": "Partial address text, e.g. \"123 Main St\""
    },
    "target": {
      "enum": [
        "sender",
        "recipient"
      ],
      "type": "string",
      "description": "Which address field is being searched (used for UI context)."
    },
    "container": {
      "type": "string",
      "description": "Loqate container id for drilling into suggestions, if provided"
    },
    "country_code": {
      "type": "string",
      "maxLength": 2,
      "minLength": 2,
      "description": "Two-letter country code to filter suggestions. Defaults to US."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "slug",
    "sender_name",
    "sender_address_type"
  ],
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1
    },
    "color": {
      "type": "boolean"
    },
    "fields": {
      "type": "object",
      "default": {},
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "certified": {
      "type": "boolean"
    },
    "buyer_name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "Receipt name; defaults to sender_name for MPP."
    },
    "mail_class": {
      "enum": [
        "standard",
        "priority",
        "express"
      ],
      "type": "string"
    },
    "request_id": {
      "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)$"
    },
    "attachments": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "base64"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "label": {
            "type": "string"
          },
          "base64": {
            "type": "string",
            "minLength": 1
          },
          "file_name": {
            "type": "string"
          },
          "content_type": {
            "type": "string"
          }
        }
      }
    },
    "buyer_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "maxLength": 256,
      "description": "Required for MPP receipt delivery."
    },
    "sender_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "double_sided": {
      "type": "boolean"
    },
    "recipient_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "payment_protocol": {
      "enum": [
        "hosted",
        "mpp"
      ],
      "type": "string",
      "description": "Optional payment path. Defaults to hosted checkout. Choose mpp to return a payment challenge for this same prepared order; buyer_email is required. Draft creation never pays."
    },
    "sender_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "sender_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "sender_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string"
    },
    "recipient_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "sender_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    },
    "recipient_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "recipient_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string"
    },
    "use_workflow_recipient": {
      "type": "boolean",
      "description": "Deprecated compatibility field. Predefined and computed workflow recipients are always enforced and cannot be overridden."
    },
    "certified_return_receipt": {
      "type": "boolean"
    },
    "recipient_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "letter",
    "sender_name",
    "sender_address_type",
    "recipient_name",
    "recipient_address_type"
  ],
  "properties": {
    "color": {
      "type": "boolean"
    },
    "letter": {
      "type": "object",
      "required": [
        "body"
      ],
      "properties": {
        "body": {
          "type": "string",
          "maxLength": 20000,
          "minLength": 1
        },
        "title": {
          "type": "string",
          "maxLength": 200
        },
        "render": {
          "type": "object",
          "properties": {
            "font": {
              "enum": [
                "times",
                "helvetica"
              ],
              "type": "string"
            },
            "paper": {
              "type": "string",
              "const": "letter"
            },
            "font_size": {
              "type": "integer",
              "maximum": 14,
              "minimum": 9
            },
            "margin_in": {
              "type": "number",
              "maximum": 1.5,
              "minimum": 0.5
            }
          }
        },
        "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
            }
          ]
        }
      }
    },
    "certified": {
      "type": "boolean"
    },
    "buyer_name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "Receipt name; defaults to sender_name for MPP."
    },
    "mail_class": {
      "enum": [
        "standard",
        "priority",
        "express"
      ],
      "type": "string"
    },
    "request_id": {
      "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_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "maxLength": 256,
      "description": "Required for MPP receipt delivery."
    },
    "sender_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "double_sided": {
      "type": "boolean"
    },
    "recipient_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "payment_protocol": {
      "enum": [
        "hosted",
        "mpp"
      ],
      "type": "string",
      "description": "Optional payment path. Defaults to hosted checkout. Choose mpp to return a payment challenge for this same prepared order; buyer_email is required. Draft creation never pays."
    },
    "sender_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "sender_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "sender_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string"
    },
    "recipient_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "sender_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    },
    "recipient_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "recipient_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string"
    },
    "certified_return_receipt": {
      "type": "boolean"
    },
    "recipient_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "buyer_name",
    "buyer_email",
    "sender_name"
  ],
  "properties": {
    "pdf": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "download_url",
            "file_id"
          ],
          "properties": {
            "file_id": {
              "type": "string"
            },
            "download_url": {
              "type": "string",
              "format": "uri"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "upload_token"
          ],
          "properties": {
            "upload_token": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        {
          "type": "string",
          "minLength": 1
        }
      ],
      "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."
    },
    "bulk": {
      "type": "object",
      "required": [
        "content_mode"
      ],
      "properties": {
        "recipients": {
          "type": "array",
          "items": {
            "type": "object",
            "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. Each address can include merge_fields for text/HTML templates."
        },
        "csv_content": {
          "type": "string",
          "minLength": 1,
          "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."
        },
        "content_mode": {
          "enum": [
            "text",
            "html",
            "pdf"
          ],
          "type": "string",
          "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."
        },
        "campaign_name": {
          "type": "string",
          "maxLength": 255
        },
        "template_html": {
          "type": "string",
          "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."
        },
        "template_text": {
          "type": "string",
          "description": "Plain-text letter template. {{field}} inserts a merge value; HTML is not allowed."
        }
      },
      "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.",
      "additionalProperties": false
    },
    "form": {
      "type": "object",
      "required": [
        "slug"
      ],
      "properties": {
        "slug": {
          "type": "string",
          "minLength": 1
        },
        "fields": {
          "type": "object",
          "default": {},
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "attachments": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "base64"
            ],
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1
              },
              "label": {
                "type": "string",
                "minLength": 1
              },
              "base64": {
                "type": "string",
                "minLength": 1
              },
              "file_name": {
                "type": "string",
                "maxLength": 255,
                "minLength": 1
              },
              "content_type": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        }
      },
      "description": "Workflow form payload from postalform.get_form_schema. Provide exactly one of pdf, letter, or form."
    },
    "color": {
      "type": "boolean"
    },
    "letter": {
      "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"
        },
        "render": {
          "type": "object",
          "properties": {
            "font": {
              "enum": [
                "times",
                "helvetica"
              ],
              "type": "string"
            },
            "paper": {
              "type": "string",
              "const": "letter"
            },
            "font_size": {
              "type": "integer",
              "maximum": 14,
              "minimum": 9
            },
            "margin_in": {
              "type": "number",
              "maximum": 1.5,
              "minimum": 0.5
            }
          }
        },
        "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
            }
          ]
        }
      },
      "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."
    },
    "certified": {
      "type": "boolean"
    },
    "file_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "buyer_name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "Buyer name for receipts."
    },
    "mail_class": {
      "enum": [
        "standard",
        "priority",
        "express"
      ],
      "type": "string"
    },
    "request_id": {
      "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)$",
      "description": "Idempotency key. Reuse the same value and same order fields after a payment challenge."
    },
    "buyer_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "maxLength": 256,
      "description": "Buyer email for receipts."
    },
    "sender_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "double_sided": {
      "type": "boolean"
    },
    "postcard_size": {
      "enum": [
        "4x6",
        "6x9",
        "11x6"
      ],
      "type": "string"
    },
    "mailpiece_type": {
      "enum": [
        "letter",
        "postcard"
      ],
      "type": "string"
    },
    "recipient_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Required for a single recipient. Omit when bulk supplies the recipient list."
    },
    "payment_protocol": {
      "enum": [
        "mpp",
        "x402"
      ],
      "type": "string",
      "description": "Direct machine payment protocol. Use mpp for Link CLI/Link MCP or Stripe SPT; use x402 for x402 wallet clients. Defaults to mpp."
    },
    "payment_signature": {
      "type": "string",
      "minLength": 1,
      "description": "x402 retry value after paying the PAYMENT-REQUIRED challenge."
    },
    "sender_address_id": {
      "type": "string",
      "minLength": 1
    },
    "signature_required": {
      "type": "boolean"
    },
    "sender_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "sender_address_type": {
      "enum": [
        "Address",
        "Manual"
      ],
      "type": "string"
    },
    "recipient_address_id": {
      "type": "string",
      "minLength": 1
    },
    "payment_authorization": {
      "type": "string",
      "minLength": 1,
      "description": "MPP retry value after paying with Link CLI/Link MCP. Pass the full Authorization header value, usually \"Payment ...\"."
    },
    "sender_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    },
    "recipient_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "recipient_address_type": {
      "enum": [
        "Address",
        "Manual"
      ],
      "type": "string"
    },
    "certified_return_receipt": {
      "type": "boolean"
    },
    "recipient_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "pdf",
    "sender_name",
    "sender_address_type",
    "recipient_name",
    "recipient_address_type"
  ],
  "properties": {
    "pdf": {
      "anyOf": [
        {
          "type": "object",
          "required": [
            "download_url",
            "file_id"
          ],
          "properties": {
            "file_id": {
              "type": "string"
            },
            "download_url": {
              "type": "string",
              "format": "uri"
            }
          }
        },
        {
          "type": "object",
          "required": [
            "upload_token"
          ],
          "properties": {
            "upload_token": {
              "type": "string",
              "minLength": 1
            }
          }
        },
        {
          "type": "string",
          "minLength": 1
        }
      ],
      "description": "The PDF to mail. Accepts attachment objects ({ download_url, file_id }). Fallbacks: upload_token from postalform.create_pdf_upload, data:application/pdf;base64,..., or a public HTTPS download URL."
    },
    "color": {
      "type": "boolean",
      "description": "Whether to print in color (default: false)."
    },
    "certified": {
      "type": "boolean",
      "description": "Whether to add proof mail: USPS Certified Mail for US destinations, Canada Post Registered Mail through PostGrid for Canadian destinations, or PinGen registered mail for supported European destinations (default: false)."
    },
    "file_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Optional display file name."
    },
    "buyer_name": {
      "type": "string",
      "maxLength": 256,
      "minLength": 1,
      "description": "Receipt name; defaults to sender_name for MPP."
    },
    "mail_class": {
      "enum": [
        "standard",
        "priority",
        "express"
      ],
      "type": "string",
      "description": "Mail service level (standard, priority, express)."
    },
    "request_id": {
      "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)$",
      "description": "Optional idempotency key. Reuse the same value if retrying the call."
    },
    "buyer_email": {
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      "maxLength": 256,
      "description": "Required for MPP receipt delivery."
    },
    "sender_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Sender's name (return address)."
    },
    "double_sided": {
      "type": "boolean",
      "description": "Whether to print double-sided (default: true)."
    },
    "recipient_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Recipient's name."
    },
    "payment_protocol": {
      "enum": [
        "hosted",
        "mpp"
      ],
      "type": "string",
      "description": "Optional payment path. Defaults to hosted checkout. Choose mpp to return a payment challenge for this same prepared order; buyer_email is required. Draft creation never pays."
    },
    "sender_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Loqate address id for the sender (required when sender_address_type is Address)."
    },
    "sender_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "Human-readable sender address preview (required when sender_address_type is Address; optional for Manual)."
    },
    "sender_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string",
      "description": "Address suggestion type for the sender (from postalform.search_addresses). Use Manual to pass a structured address with countryCode when outside the US."
    },
    "recipient_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1,
      "description": "Loqate address id for the recipient (required when recipient_address_type is Address)."
    },
    "sender_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      },
      "description": "Sender manual address fields (required when sender_address_type is Manual)."
    },
    "recipient_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1,
      "description": "Human-readable recipient address preview (required when recipient_address_type is Address; optional for Manual)."
    },
    "recipient_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string",
      "description": "Address suggestion type for the recipient (from postalform.search_addresses). Use Manual to pass a structured address with countryCode when outside the US."
    },
    "certified_return_receipt": {
      "type": "boolean",
      "description": "Add Electronic Return Receipt for US Certified Mail. Ignored for Canada Post Registered Mail and PinGen registered-mail destinations (default: false)."
    },
    "recipient_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      },
      "description": "Recipient manual address fields (required when recipient_address_type is Manual)."
    }
  }
}

Input schema (JSON)

{
  "type": "object",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "required": [
    "letter",
    "sender_name",
    "sender_address_type",
    "recipient_name",
    "recipient_address_type"
  ],
  "properties": {
    "color": {
      "type": "boolean"
    },
    "letter": {
      "type": "object",
      "required": [
        "body"
      ],
      "properties": {
        "body": {
          "type": "string",
          "maxLength": 20000,
          "minLength": 1
        },
        "title": {
          "type": "string",
          "maxLength": 200
        },
        "render": {
          "type": "object",
          "properties": {
            "font": {
              "enum": [
                "times",
                "helvetica"
              ],
              "type": "string"
            },
            "paper": {
              "type": "string",
              "const": "letter"
            },
            "font_size": {
              "type": "integer",
              "maximum": 14,
              "minimum": 9
            },
            "margin_in": {
              "type": "number",
              "maximum": 1.5,
              "minimum": 0.5
            }
          }
        },
        "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
            }
          ]
        }
      }
    },
    "certified": {
      "type": "boolean"
    },
    "mail_class": {
      "enum": [
        "standard",
        "priority",
        "express"
      ],
      "type": "string"
    },
    "request_id": {
      "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)$"
    },
    "sender_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "double_sided": {
      "type": "boolean"
    },
    "recipient_name": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "sender_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "sender_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "sender_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string"
    },
    "recipient_address_id": {
      "type": "string",
      "maxLength": 255,
      "minLength": 1
    },
    "sender_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    },
    "recipient_address_text": {
      "type": "string",
      "maxLength": 2000,
      "minLength": 1
    },
    "recipient_address_type": {
      "enum": [
        "Address",
        "Container",
        "Manual"
      ],
      "type": "string"
    },
    "certified_return_receipt": {
      "type": "boolean"
    },
    "recipient_address_manual": {
      "type": "object",
      "required": [
        "line1",
        "line2",
        "city",
        "zip"
      ],
      "properties": {
        "zip": {
          "type": "string",
          "maxLength": 20,
          "minLength": 1
        },
        "city": {
          "type": "string",
          "minLength": 1
        },
        "line1": {
          "type": "string",
          "minLength": 1
        },
        "line2": {
          "type": "string",
          "minLength": 1
        },
        "state": {
          "type": "string",
          "maxLength": 60,
          "minLength": 1
        },
        "country": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        },
        "countryCode": {
          "type": "string",
          "maxLength": 2,
          "minLength": 2
        }
      }
    }
  }
}