Server definition
- Hash
- sha256:4886c2975438cf8dbaea15ffb569461d8902cdabcf4d73c9da495a0e25fe1634
- What it is
- What a remote MCP server returned when asked what it offers: 13 tools
The blob, as servednamed by its sha256
{
"instructions": "PostalForm prints and mails physical letters, documents, and forms via USPS. Typical flow: validate addresses, prepare a draft and review its price, then obtain buyer approval before complete_checkout with a compatible Stripe payment token, hosted checkout, or a direct MPP/x402 payment. Every unpaid machine order also returns a hosted checkout_url fallback. Without a compatible wallet, present that URL and poll status_url. For MPP, any PDF, letter, or form draft can use payment_protocol=mpp and buyer_email. Review the preview and total, then call postalform.pay_order with only the order_id and buyer-approved credential. Generated letters accept text directly; no PDF upload or browser is needed. Docs and guidance: https://postalform.com/agents (agent payment workflows), https://postalform.com/developers (API reference), https://postalform.com/openapi.json (OpenAPI spec). Developers and agents can provision PostalForm infrastructure and build on these APIs at https://projects.postalform.com (Stripe Projects CLI or regular login). Support: [email protected].",
"tools": [
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"buyer": {
"anyOf": [
{
"properties": {
"email": {
"format": "email",
"maxLength": 256,
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"type": "string"
},
"first_name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"last_name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"phone_number": {
"maxLength": 32,
"minLength": 1,
"type": "string"
}
},
"required": [
"first_name",
"email"
],
"type": "object"
},
{
"properties": {
"email": {
"format": "email",
"maxLength": 256,
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"type": "string"
},
"name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"phone_number": {
"maxLength": 32,
"minLength": 1,
"type": "string"
}
},
"required": [
"name",
"email"
],
"type": "object"
}
],
"description": "Buyer identity details for the approved checkout."
},
"checkout_session_id": {
"description": "The checkout session id to finalize.",
"minLength": 1,
"type": "string"
},
"payment_data": {
"description": "Buyer-authorized payment token details. Use provider=stripe.",
"properties": {
"billing_address": {
"properties": {
"city": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 1,
"type": "string"
},
"line_one": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"line_two": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"phone_number": {
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"postal_code": {
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
}
},
"required": [
"name",
"line_one",
"city",
"state",
"country",
"postal_code"
],
"type": "object"
},
"provider": {
"enum": [
"stripe",
"adyen"
],
"type": "string"
},
"token": {
"minLength": 1,
"type": "string"
}
},
"required": [
"token",
"provider"
],
"type": "object"
}
},
"required": [
"checkout_session_id",
"buyer",
"payment_data"
],
"type": "object"
},
"name": "complete_checkout",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"buyer": {
"additionalProperties": false,
"properties": {
"email": {
"format": "email",
"maxLength": 256,
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"type": "string"
},
"first_name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"last_name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"phone_number": {
"maxLength": 32,
"minLength": 1,
"type": "string"
}
},
"required": [
"first_name",
"email"
],
"type": "object"
},
"currency": {
"type": "string"
},
"fulfillment_address": {
"additionalProperties": false,
"properties": {
"city": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 1,
"type": "string"
},
"line_one": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"line_two": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"phone_number": {
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"postal_code": {
"maxLength": 20,
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
}
},
"required": [
"name",
"line_one",
"city",
"state",
"country",
"postal_code"
],
"type": "object"
},
"fulfillment_option_id": {
"minLength": 1,
"type": "string"
},
"fulfillment_options": {
"items": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"carrier": {
"minLength": 1,
"type": "string"
},
"carrier_info": {
"minLength": 1,
"type": "string"
},
"earliest_delivery_time": {
"minLength": 1,
"type": "string"
},
"id": {
"minLength": 1,
"type": "string"
},
"latest_delivery_time": {
"minLength": 1,
"type": "string"
},
"subtitle": {
"minLength": 1,
"type": "string"
},
"subtotal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tax": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"title": {
"minLength": 1,
"type": "string"
},
"total": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"type": {
"const": "shipping",
"type": "string"
}
},
"required": [
"type",
"id",
"title",
"subtitle",
"earliest_delivery_time",
"latest_delivery_time",
"subtotal",
"tax",
"total"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"id": {
"minLength": 1,
"type": "string"
},
"subtitle": {
"minLength": 1,
"type": "string"
},
"subtotal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tax": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"title": {
"minLength": 1,
"type": "string"
},
"total": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"type": {
"const": "digital",
"type": "string"
}
},
"required": [
"type",
"id",
"title",
"subtotal",
"tax",
"total"
],
"type": "object"
}
]
},
"type": "array"
},
"id": {
"minLength": 1,
"type": "string"
},
"line_items": {
"items": {
"additionalProperties": false,
"properties": {
"base_amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"discount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"id": {
"minLength": 1,
"type": "string"
},
"item": {
"additionalProperties": false,
"properties": {
"id": {
"minLength": 1,
"type": "string"
},
"quantity": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"quantity"
],
"type": "object"
},
"subtotal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tax": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"total": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"item",
"base_amount",
"discount",
"subtotal",
"tax",
"total"
],
"type": "object"
},
"type": "array"
},
"links": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"terms_of_use",
"privacy_policy",
"seller_shop_policies"
],
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
},
"value": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"messages": {
"items": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"content": {
"minLength": 1,
"type": "string"
},
"content_type": {
"enum": [
"plain",
"markdown"
],
"type": "string"
},
"param": {
"minLength": 1,
"type": "string"
},
"type": {
"const": "info",
"type": "string"
}
},
"required": [
"type",
"param",
"content_type",
"content"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"code": {
"enum": [
"missing",
"invalid",
"out_of_stock",
"payment_declined",
"requires_sign_in",
"requires_3ds"
],
"type": "string"
},
"content": {
"minLength": 1,
"type": "string"
},
"content_type": {
"enum": [
"plain",
"markdown"
],
"type": "string"
},
"param": {
"minLength": 1,
"type": "string"
},
"type": {
"const": "error",
"type": "string"
}
},
"required": [
"type",
"code",
"content_type",
"content"
],
"type": "object"
}
]
},
"type": "array"
},
"order": {
"additionalProperties": false,
"properties": {
"checkout_session_id": {
"minLength": 1,
"type": "string"
},
"id": {
"minLength": 1,
"type": "string"
},
"permalink_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"id",
"checkout_session_id",
"permalink_url"
],
"type": "object"
},
"status": {
"enum": [
"not_ready_for_payment",
"ready_for_payment",
"completed",
"canceled"
],
"type": "string"
},
"totals": {
"items": {
"additionalProperties": false,
"properties": {
"amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"display_text": {
"minLength": 1,
"type": "string"
},
"type": {
"enum": [
"items_base_amount",
"items_discount",
"subtotal",
"discount",
"fulfillment",
"tax",
"fee",
"total"
],
"type": "string"
}
},
"required": [
"type",
"display_text",
"amount"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"id",
"buyer",
"status",
"currency",
"line_items",
"fulfillment_options",
"totals",
"messages",
"links"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"attachments": {
"items": {
"properties": {
"base64": {
"minLength": 1,
"type": "string"
},
"content_type": {
"type": "string"
},
"file_name": {
"type": "string"
},
"id": {
"minLength": 1,
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"id",
"base64"
],
"type": "object"
},
"type": "array"
},
"buyer_email": {
"description": "Required for MPP receipt delivery.",
"format": "email",
"maxLength": 256,
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"type": "string"
},
"buyer_name": {
"description": "Receipt name; defaults to sender_name for MPP.",
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"certified": {
"type": "boolean"
},
"certified_return_receipt": {
"type": "boolean"
},
"color": {
"type": "boolean"
},
"double_sided": {
"type": "boolean"
},
"fields": {
"additionalProperties": {},
"default": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
"mail_class": {
"enum": [
"standard",
"priority",
"express"
],
"type": "string"
},
"payment_protocol": {
"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.",
"enum": [
"hosted",
"mpp"
],
"type": "string"
},
"recipient_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"recipient_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"recipient_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"recipient_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"recipient_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"sender_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"sender_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"sender_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"sender_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"sender_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"slug": {
"minLength": 1,
"type": "string"
},
"use_workflow_recipient": {
"description": "Deprecated compatibility field. Predefined and computed workflow recipients are always enforced and cannot be overridden.",
"type": "boolean"
}
},
"required": [
"slug",
"sender_name",
"sender_address_type"
],
"type": "object"
},
"name": "postalform.create_form_order_draft",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"checkout_session": {
"additionalProperties": false,
"properties": {
"currency": {
"minLength": 1,
"type": "string"
},
"id": {
"minLength": 1,
"type": "string"
},
"line_items": {
"items": {
"additionalProperties": false,
"properties": {
"base_amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"discount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"id": {
"minLength": 1,
"type": "string"
},
"item": {
"additionalProperties": false,
"properties": {
"id": {
"minLength": 1,
"type": "string"
},
"quantity": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"quantity"
],
"type": "object"
},
"subtotal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tax": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"total": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"item",
"base_amount",
"discount",
"subtotal",
"tax",
"total"
],
"type": "object"
},
"type": "array"
},
"links": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"terms_of_use",
"privacy_policy",
"seller_shop_policies"
],
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
},
"value": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"payment_provider": {
"additionalProperties": false,
"properties": {
"merchant_id": {
"minLength": 1,
"type": "string"
},
"provider": {
"enum": [
"stripe",
"adyen"
],
"type": "string"
},
"supported_payment_methods": {
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
}
},
"required": [
"provider",
"supported_payment_methods"
],
"type": "object"
},
"status": {
"enum": [
"not_ready_for_payment",
"ready_for_payment",
"completed",
"canceled"
],
"type": "string"
},
"totals": {
"items": {
"additionalProperties": false,
"properties": {
"amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"display_text": {
"minLength": 1,
"type": "string"
},
"type": {
"enum": [
"items_base_amount",
"items_discount",
"subtotal",
"discount",
"fulfillment",
"tax",
"fee",
"total"
],
"type": "string"
}
},
"required": [
"type",
"display_text",
"amount"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"id",
"payment_provider",
"status",
"currency",
"line_items",
"totals",
"links"
],
"type": "object"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"payment": {
"additionalProperties": false,
"properties": {
"bulk": {
"additionalProperties": false,
"properties": {
"campaign_id": {
"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)$",
"type": "string"
},
"content_mode": {
"enum": [
"text",
"html",
"pdf"
],
"type": "string"
},
"recipient_count": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"status": {
"type": "string"
},
"status_counts": {
"additionalProperties": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"campaign_id",
"recipient_count",
"content_mode",
"status",
"status_counts"
],
"type": "object"
},
"campaign_url": {
"format": "uri",
"type": "string"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"endpoint": {
"format": "uri",
"type": "string"
},
"is_paid": {
"type": "boolean"
},
"mailpiece_type": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"next_action": {
"type": "string"
},
"next_step": {
"type": "string"
},
"order_complete_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"payment": {},
"payment_options": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_status": {
"type": "string"
},
"postcard_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"protocol": {
"enum": [
"mpp",
"x402"
],
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"status": {
"type": "string"
},
"status_url": {
"format": "uri",
"type": "string"
},
"view": {
"const": "machine_order",
"type": "string"
}
},
"required": [
"view",
"protocol",
"order_id",
"request_id",
"endpoint",
"status",
"payment_status",
"is_paid",
"price_usd",
"currency",
"mailpiece_type",
"postcard_size",
"order_complete_url"
],
"type": "object"
},
"payment_protocol": {
"enum": [
"hosted",
"mpp"
],
"type": "string"
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
]
},
"recipient_address_text": {
"type": "string"
},
"recipient_name": {
"type": "string"
},
"sender_address_text": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"view": {
"const": "order_draft",
"type": "string"
}
},
"required": [
"view",
"order_id",
"page_count",
"price_usd",
"checkout_url",
"sender_name",
"sender_address_text",
"recipient_name",
"recipient_address_text"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"buyer_email": {
"description": "Required for MPP receipt delivery.",
"format": "email",
"maxLength": 256,
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"type": "string"
},
"buyer_name": {
"description": "Receipt name; defaults to sender_name for MPP.",
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"certified": {
"type": "boolean"
},
"certified_return_receipt": {
"type": "boolean"
},
"color": {
"type": "boolean"
},
"double_sided": {
"type": "boolean"
},
"letter": {
"properties": {
"body": {
"maxLength": 20000,
"minLength": 1,
"type": "string"
},
"render": {
"properties": {
"font": {
"enum": [
"times",
"helvetica"
],
"type": "string"
},
"font_size": {
"maximum": 14,
"minimum": 9,
"type": "integer"
},
"margin_in": {
"maximum": 1.5,
"minimum": 0.5,
"type": "number"
},
"paper": {
"const": "letter",
"type": "string"
}
},
"type": "object"
},
"signature": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"dataUrl": {
"type": "string"
},
"mode": {
"enum": [
"typed",
"drawn"
],
"type": "string"
},
"printDataUrl": {
"type": "string"
},
"text": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
}
]
},
"title": {
"maxLength": 200,
"type": "string"
}
},
"required": [
"body"
],
"type": "object"
},
"mail_class": {
"enum": [
"standard",
"priority",
"express"
],
"type": "string"
},
"payment_protocol": {
"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.",
"enum": [
"hosted",
"mpp"
],
"type": "string"
},
"recipient_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"recipient_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"recipient_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"recipient_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"recipient_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"sender_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"sender_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"sender_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"sender_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"sender_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
}
},
"required": [
"letter",
"sender_name",
"sender_address_type",
"recipient_name",
"recipient_address_type"
],
"type": "object"
},
"name": "postalform.create_letter_order_draft",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"checkout_session": {
"additionalProperties": false,
"properties": {
"currency": {
"minLength": 1,
"type": "string"
},
"id": {
"minLength": 1,
"type": "string"
},
"line_items": {
"items": {
"additionalProperties": false,
"properties": {
"base_amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"discount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"id": {
"minLength": 1,
"type": "string"
},
"item": {
"additionalProperties": false,
"properties": {
"id": {
"minLength": 1,
"type": "string"
},
"quantity": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"quantity"
],
"type": "object"
},
"subtotal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tax": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"total": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"item",
"base_amount",
"discount",
"subtotal",
"tax",
"total"
],
"type": "object"
},
"type": "array"
},
"links": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"terms_of_use",
"privacy_policy",
"seller_shop_policies"
],
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
},
"value": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"payment_provider": {
"additionalProperties": false,
"properties": {
"merchant_id": {
"minLength": 1,
"type": "string"
},
"provider": {
"enum": [
"stripe",
"adyen"
],
"type": "string"
},
"supported_payment_methods": {
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
}
},
"required": [
"provider",
"supported_payment_methods"
],
"type": "object"
},
"status": {
"enum": [
"not_ready_for_payment",
"ready_for_payment",
"completed",
"canceled"
],
"type": "string"
},
"totals": {
"items": {
"additionalProperties": false,
"properties": {
"amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"display_text": {
"minLength": 1,
"type": "string"
},
"type": {
"enum": [
"items_base_amount",
"items_discount",
"subtotal",
"discount",
"fulfillment",
"tax",
"fee",
"total"
],
"type": "string"
}
},
"required": [
"type",
"display_text",
"amount"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"id",
"payment_provider",
"status",
"currency",
"line_items",
"totals",
"links"
],
"type": "object"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"payment": {
"additionalProperties": false,
"properties": {
"bulk": {
"additionalProperties": false,
"properties": {
"campaign_id": {
"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)$",
"type": "string"
},
"content_mode": {
"enum": [
"text",
"html",
"pdf"
],
"type": "string"
},
"recipient_count": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"status": {
"type": "string"
},
"status_counts": {
"additionalProperties": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"campaign_id",
"recipient_count",
"content_mode",
"status",
"status_counts"
],
"type": "object"
},
"campaign_url": {
"format": "uri",
"type": "string"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"endpoint": {
"format": "uri",
"type": "string"
},
"is_paid": {
"type": "boolean"
},
"mailpiece_type": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"next_action": {
"type": "string"
},
"next_step": {
"type": "string"
},
"order_complete_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"payment": {},
"payment_options": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_status": {
"type": "string"
},
"postcard_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"protocol": {
"enum": [
"mpp",
"x402"
],
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"status": {
"type": "string"
},
"status_url": {
"format": "uri",
"type": "string"
},
"view": {
"const": "machine_order",
"type": "string"
}
},
"required": [
"view",
"protocol",
"order_id",
"request_id",
"endpoint",
"status",
"payment_status",
"is_paid",
"price_usd",
"currency",
"mailpiece_type",
"postcard_size",
"order_complete_url"
],
"type": "object"
},
"payment_protocol": {
"enum": [
"hosted",
"mpp"
],
"type": "string"
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
]
},
"recipient_address_text": {
"type": "string"
},
"recipient_name": {
"type": "string"
},
"sender_address_text": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"view": {
"const": "order_draft",
"type": "string"
}
},
"required": [
"view",
"order_id",
"page_count",
"price_usd",
"checkout_url",
"sender_name",
"sender_address_text",
"recipient_name",
"recipient_address_text"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"bulk": {
"additionalProperties": false,
"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.",
"properties": {
"campaign_name": {
"maxLength": 255,
"type": "string"
},
"content_mode": {
"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.",
"enum": [
"text",
"html",
"pdf"
],
"type": "string"
},
"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.",
"minLength": 1,
"type": "string"
},
"recipients": {
"description": "JSON recipient list, mutually exclusive with csv_content. Each address can include merge_fields for text/HTML templates.",
"items": {
"additionalProperties": false,
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Mailing country code. Defaults to US."
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"merge_fields": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"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": {
"pattern": "^[a-z][a-z0-9_]*$",
"type": "string"
},
"type": "object"
},
"recipient_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Required for US and Canadian recipients. Omit or send null elsewhere."
},
"zip": {
"description": "ZIP/postal code as a string, preserving leading zeros.",
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"city",
"zip"
],
"type": "object"
},
"minItems": 1,
"type": "array"
},
"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"
},
"template_text": {
"description": "Plain-text letter template. {{field}} inserts a merge value; HTML is not allowed.",
"type": "string"
}
},
"required": [
"content_mode"
],
"type": "object"
},
"buyer_email": {
"description": "Buyer email for receipts.",
"format": "email",
"maxLength": 256,
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"type": "string"
},
"buyer_name": {
"description": "Buyer name for receipts.",
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"certified": {
"type": "boolean"
},
"certified_return_receipt": {
"type": "boolean"
},
"color": {
"type": "boolean"
},
"double_sided": {
"type": "boolean"
},
"file_name": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"form": {
"description": "Workflow form payload from postalform.get_form_schema. Provide exactly one of pdf, letter, or form.",
"properties": {
"attachments": {
"items": {
"properties": {
"base64": {
"minLength": 1,
"type": "string"
},
"content_type": {
"minLength": 1,
"type": "string"
},
"file_name": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"id": {
"minLength": 1,
"type": "string"
},
"label": {
"minLength": 1,
"type": "string"
}
},
"required": [
"id",
"base64"
],
"type": "object"
},
"type": "array"
},
"fields": {
"additionalProperties": {},
"default": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
"slug": {
"minLength": 1,
"type": "string"
}
},
"required": [
"slug"
],
"type": "object"
},
"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.",
"properties": {
"body": {
"maxLength": 20000,
"minLength": 1,
"type": "string"
},
"format": {
"enum": [
"text",
"html",
"markdown",
"rtf"
],
"type": "string"
},
"render": {
"properties": {
"font": {
"enum": [
"times",
"helvetica"
],
"type": "string"
},
"font_size": {
"maximum": 14,
"minimum": 9,
"type": "integer"
},
"margin_in": {
"maximum": 1.5,
"minimum": 0.5,
"type": "number"
},
"paper": {
"const": "letter",
"type": "string"
}
},
"type": "object"
},
"signature": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"dataUrl": {
"type": "string"
},
"mode": {
"enum": [
"typed",
"drawn"
],
"type": "string"
},
"printDataUrl": {
"type": "string"
},
"text": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
}
]
},
"title": {
"maxLength": 200,
"type": "string"
}
},
"required": [
"body"
],
"type": "object"
},
"mail_class": {
"enum": [
"standard",
"priority",
"express"
],
"type": "string"
},
"mailpiece_type": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"payment_authorization": {
"description": "MPP retry value after paying with Link CLI/Link MCP. Pass the full Authorization header value, usually \"Payment ...\".",
"minLength": 1,
"type": "string"
},
"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.",
"enum": [
"mpp",
"x402"
],
"type": "string"
},
"payment_signature": {
"description": "x402 retry value after paying the PAYMENT-REQUIRED challenge.",
"minLength": 1,
"type": "string"
},
"pdf": {
"anyOf": [
{
"properties": {
"download_url": {
"format": "uri",
"type": "string"
},
"file_id": {
"type": "string"
}
},
"required": [
"download_url",
"file_id"
],
"type": "object"
},
{
"properties": {
"upload_token": {
"minLength": 1,
"type": "string"
}
},
"required": [
"upload_token"
],
"type": "object"
},
{
"minLength": 1,
"type": "string"
}
],
"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."
},
"postcard_size": {
"enum": [
"4x6",
"6x9",
"11x6"
],
"type": "string"
},
"recipient_address_id": {
"minLength": 1,
"type": "string"
},
"recipient_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"recipient_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"recipient_address_type": {
"enum": [
"Address",
"Manual"
],
"type": "string"
},
"recipient_name": {
"description": "Required for a single recipient. Omit when bulk supplies the recipient list.",
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"request_id": {
"description": "Idempotency key. Reuse the same value and same order fields after a payment challenge.",
"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)$",
"type": "string"
},
"sender_address_id": {
"minLength": 1,
"type": "string"
},
"sender_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"sender_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"sender_address_type": {
"enum": [
"Address",
"Manual"
],
"type": "string"
},
"sender_name": {
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"signature_required": {
"type": "boolean"
}
},
"required": [
"buyer_name",
"buyer_email",
"sender_name"
],
"type": "object"
},
"name": "postalform.create_machine_order",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bulk": {
"additionalProperties": false,
"properties": {
"campaign_id": {
"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)$",
"type": "string"
},
"content_mode": {
"enum": [
"text",
"html",
"pdf"
],
"type": "string"
},
"recipient_count": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"status": {
"type": "string"
},
"status_counts": {
"additionalProperties": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"campaign_id",
"recipient_count",
"content_mode",
"status",
"status_counts"
],
"type": "object"
},
"campaign_url": {
"format": "uri",
"type": "string"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"endpoint": {
"format": "uri",
"type": "string"
},
"is_paid": {
"type": "boolean"
},
"mailpiece_type": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"next_action": {
"type": "string"
},
"next_step": {
"type": "string"
},
"order_complete_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"payment": {},
"payment_options": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_status": {
"type": "string"
},
"postcard_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"protocol": {
"enum": [
"mpp",
"x402"
],
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"status": {
"type": "string"
},
"status_url": {
"format": "uri",
"type": "string"
},
"view": {
"const": "machine_order",
"type": "string"
}
},
"required": [
"view",
"protocol",
"order_id",
"request_id",
"endpoint",
"status",
"payment_status",
"is_paid",
"price_usd",
"currency",
"mailpiece_type",
"postcard_size",
"order_complete_url"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"buyer_email": {
"description": "Required for MPP receipt delivery.",
"format": "email",
"maxLength": 256,
"pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"type": "string"
},
"buyer_name": {
"description": "Receipt name; defaults to sender_name for MPP.",
"maxLength": 256,
"minLength": 1,
"type": "string"
},
"certified": {
"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).",
"type": "boolean"
},
"certified_return_receipt": {
"description": "Add Electronic Return Receipt for US Certified Mail. Ignored for Canada Post Registered Mail and PinGen registered-mail destinations (default: false).",
"type": "boolean"
},
"color": {
"description": "Whether to print in color (default: false).",
"type": "boolean"
},
"double_sided": {
"description": "Whether to print double-sided (default: true).",
"type": "boolean"
},
"file_name": {
"description": "Optional display file name.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"mail_class": {
"description": "Mail service level (standard, priority, express).",
"enum": [
"standard",
"priority",
"express"
],
"type": "string"
},
"payment_protocol": {
"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.",
"enum": [
"hosted",
"mpp"
],
"type": "string"
},
"pdf": {
"anyOf": [
{
"properties": {
"download_url": {
"format": "uri",
"type": "string"
},
"file_id": {
"type": "string"
}
},
"required": [
"download_url",
"file_id"
],
"type": "object"
},
{
"properties": {
"upload_token": {
"minLength": 1,
"type": "string"
}
},
"required": [
"upload_token"
],
"type": "object"
},
{
"minLength": 1,
"type": "string"
}
],
"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."
},
"recipient_address_id": {
"description": "Loqate address id for the recipient (required when recipient_address_type is Address).",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"recipient_address_manual": {
"description": "Recipient manual address fields (required when recipient_address_type is Manual).",
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"recipient_address_text": {
"description": "Human-readable recipient address preview (required when recipient_address_type is Address; optional for Manual).",
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"recipient_address_type": {
"description": "Address suggestion type for the recipient (from postalform.search_addresses). Use Manual to pass a structured address with countryCode when outside the US.",
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"recipient_name": {
"description": "Recipient's name.",
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"request_id": {
"description": "Optional idempotency key. Reuse the same value if retrying the call.",
"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)$",
"type": "string"
},
"sender_address_id": {
"description": "Loqate address id for the sender (required when sender_address_type is Address).",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"sender_address_manual": {
"description": "Sender manual address fields (required when sender_address_type is Manual).",
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"sender_address_text": {
"description": "Human-readable sender address preview (required when sender_address_type is Address; optional for Manual).",
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"sender_address_type": {
"description": "Address suggestion type for the sender (from postalform.search_addresses). Use Manual to pass a structured address with countryCode when outside the US.",
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"sender_name": {
"description": "Sender's name (return address).",
"maxLength": 32,
"minLength": 1,
"type": "string"
}
},
"required": [
"pdf",
"sender_name",
"sender_address_type",
"recipient_name",
"recipient_address_type"
],
"type": "object"
},
"name": "postalform.create_order_draft",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"checkout_session": {
"additionalProperties": false,
"properties": {
"currency": {
"minLength": 1,
"type": "string"
},
"id": {
"minLength": 1,
"type": "string"
},
"line_items": {
"items": {
"additionalProperties": false,
"properties": {
"base_amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"discount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"id": {
"minLength": 1,
"type": "string"
},
"item": {
"additionalProperties": false,
"properties": {
"id": {
"minLength": 1,
"type": "string"
},
"quantity": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"id",
"quantity"
],
"type": "object"
},
"subtotal": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"tax": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"total": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
}
},
"required": [
"id",
"item",
"base_amount",
"discount",
"subtotal",
"tax",
"total"
],
"type": "object"
},
"type": "array"
},
"links": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"terms_of_use",
"privacy_policy",
"seller_shop_policies"
],
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
},
"value": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_mode": {
"enum": [
"test",
"live"
],
"type": "string"
},
"payment_provider": {
"additionalProperties": false,
"properties": {
"merchant_id": {
"minLength": 1,
"type": "string"
},
"provider": {
"enum": [
"stripe",
"adyen"
],
"type": "string"
},
"supported_payment_methods": {
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
}
},
"required": [
"provider",
"supported_payment_methods"
],
"type": "object"
},
"status": {
"enum": [
"not_ready_for_payment",
"ready_for_payment",
"completed",
"canceled"
],
"type": "string"
},
"totals": {
"items": {
"additionalProperties": false,
"properties": {
"amount": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"display_text": {
"minLength": 1,
"type": "string"
},
"type": {
"enum": [
"items_base_amount",
"items_discount",
"subtotal",
"discount",
"fulfillment",
"tax",
"fee",
"total"
],
"type": "string"
}
},
"required": [
"type",
"display_text",
"amount"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"id",
"payment_provider",
"status",
"currency",
"line_items",
"totals",
"links"
],
"type": "object"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
]
},
"payment": {
"additionalProperties": false,
"properties": {
"bulk": {
"additionalProperties": false,
"properties": {
"campaign_id": {
"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)$",
"type": "string"
},
"content_mode": {
"enum": [
"text",
"html",
"pdf"
],
"type": "string"
},
"recipient_count": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"status": {
"type": "string"
},
"status_counts": {
"additionalProperties": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"campaign_id",
"recipient_count",
"content_mode",
"status",
"status_counts"
],
"type": "object"
},
"campaign_url": {
"format": "uri",
"type": "string"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"endpoint": {
"format": "uri",
"type": "string"
},
"is_paid": {
"type": "boolean"
},
"mailpiece_type": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"next_action": {
"type": "string"
},
"next_step": {
"type": "string"
},
"order_complete_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"payment": {},
"payment_options": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_status": {
"type": "string"
},
"postcard_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"protocol": {
"enum": [
"mpp",
"x402"
],
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"status": {
"type": "string"
},
"status_url": {
"format": "uri",
"type": "string"
},
"view": {
"const": "machine_order",
"type": "string"
}
},
"required": [
"view",
"protocol",
"order_id",
"request_id",
"endpoint",
"status",
"payment_status",
"is_paid",
"price_usd",
"currency",
"mailpiece_type",
"postcard_size",
"order_complete_url"
],
"type": "object"
},
"payment_protocol": {
"enum": [
"hosted",
"mpp"
],
"type": "string"
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
]
},
"recipient_address_text": {
"type": "string"
},
"recipient_name": {
"type": "string"
},
"sender_address_text": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"view": {
"const": "order_draft",
"type": "string"
}
},
"required": [
"view",
"order_id",
"page_count",
"price_usd",
"checkout_url",
"sender_name",
"sender_address_text",
"recipient_name",
"recipient_address_text"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"content_length": {
"description": "Optional content length in bytes.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"content_type": {
"description": "Optional content type hint (application/pdf).",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"file_name": {
"description": "Optional original file name.",
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"request_id": {
"description": "Optional idempotency key. Reuse the same value if retrying the call.",
"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)$",
"type": "string"
}
},
"type": "object"
},
"name": "postalform.create_pdf_upload",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"expires_at": {
"type": "string"
},
"max_bytes": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"required_headers": {
"additionalProperties": {
"type": "string"
},
"propertyNames": {
"type": "string"
},
"type": "object"
},
"upload_token": {
"type": "string"
},
"upload_url": {
"format": "uri",
"type": "string"
}
},
"required": [
"upload_url",
"upload_token",
"expires_at",
"max_bytes",
"required_headers"
],
"type": "object"
}
},
{
"description": "Use this when you need a machine-usable schema for one supported single-mailpiece PostalForm workflow (fields, groups, attachments, and dependencies).",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"slug": {
"description": "Workflow slug (e.g. \"8822\").",
"minLength": 1,
"type": "string"
}
},
"required": [
"slug"
],
"type": "object"
},
"name": "postalform.get_form_schema",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"agent_summary": {
"type": "string"
},
"aliases": {
"items": {
"type": "string"
},
"type": "array"
},
"attachments": {
"items": {},
"type": "array"
},
"attachments_max_total_size_mb": {
"exclusiveMinimum": 0,
"type": "number"
},
"bulk_form": {},
"category": {
"type": "string"
},
"certified_mail": {
"enum": [
"required",
"optional",
"none"
],
"type": "string"
},
"checkout_flow": {
"enum": [
"home",
"forms_order"
],
"type": "string"
},
"compliance_policy": {},
"data_collected": {
"items": {
"type": "string"
},
"type": "array"
},
"deadline_helper": {},
"description": {
"type": "string"
},
"fields": {
"items": {},
"type": "array"
},
"form_summary": {
"type": "string"
},
"groups": {
"items": {},
"type": "array"
},
"indexable": {
"type": "boolean"
},
"llms": {
"type": "boolean"
},
"multi_recipient": {},
"name": {
"type": "string"
},
"pricing": {
"additionalProperties": false,
"properties": {
"additiveMailServices": {
"items": {
"enum": [
"certified_return_receipt"
],
"type": "string"
},
"type": "array"
},
"currency": {
"const": "USD",
"type": "string"
},
"description": {
"type": "string"
},
"minimumTotalCents": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
}
},
"required": [
"minimumTotalCents",
"currency",
"description",
"additiveMailServices"
],
"type": "object"
},
"publish_state": {
"type": "string"
},
"published_at": {
"type": "string"
},
"recipient": {
"additionalProperties": false,
"properties": {
"address": {
"additionalProperties": false,
"properties": {
"city": {
"type": "string"
},
"line1": {
"type": "string"
},
"line2": {
"type": "string"
},
"state": {
"type": "string"
},
"zip": {
"type": "string"
}
},
"required": [
"line1",
"city",
"state",
"zip"
],
"type": "object"
},
"mode": {
"enum": [
"user",
"predefined",
"computed"
],
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"mode"
],
"type": "object"
},
"recipient_presets": {},
"recipient_rules": {},
"schema_version": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"slug": {
"type": "string"
},
"topics": {
"items": {
"type": "string"
},
"type": "array"
},
"updated_at": {
"type": "string"
},
"workflow_version": {
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
}
},
"required": [
"schema_version",
"workflow_version",
"slug",
"name",
"llms",
"indexable",
"certified_mail",
"recipient",
"groups",
"fields",
"attachments",
"attachments_max_total_size_mb"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"order_id": {
"description": "PostalForm order id.",
"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)$",
"type": "string"
}
},
"required": [
"order_id"
],
"type": "object"
},
"name": "postalform.get_order_status",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bulk": {
"additionalProperties": false,
"properties": {
"campaign_id": {
"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)$",
"type": "string"
},
"content_mode": {
"enum": [
"text",
"html",
"pdf"
],
"type": "string"
},
"recipient_count": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"status": {
"type": "string"
},
"status_counts": {
"additionalProperties": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"campaign_id",
"recipient_count",
"content_mode",
"status",
"status_counts"
],
"type": "object"
},
"campaign_url": {
"format": "uri",
"type": "string"
},
"carrier": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"checkout_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"current_step": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"delivery_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"delivery_status_detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"electronic_return_receipt": {
"additionalProperties": false,
"properties": {
"document_available": {
"type": "boolean"
},
"emailed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requested": {
"type": "boolean"
},
"status": {
"anyOf": [
{
"enum": [
"manual",
"pending",
"sent",
"failed"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"requested",
"status",
"document_available",
"emailed_at"
],
"type": "object"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"estimated_delivery_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"found": {
"type": "boolean"
},
"is_paid": {
"type": "boolean"
},
"mailing_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mailing_status_normalized": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"next_action": {
"type": "string"
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"payment_options": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_status": {
"type": "string"
},
"signed_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status_url": {
"type": "string"
},
"tracking_events": {
"items": {
"additionalProperties": false,
"properties": {
"location": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"city": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"postalCode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"postalCode",
"city",
"state",
"label"
],
"type": "object"
},
{
"type": "null"
}
]
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"occurredAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"statusDetail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"statusNormalized": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"status",
"statusNormalized",
"statusDetail",
"message",
"occurredAt",
"location"
],
"type": "object"
},
"type": "array"
},
"tracking_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"tracking_updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"view": {
"const": "order_status",
"type": "string"
}
},
"required": [
"view",
"found",
"order_id"
],
"type": "object"
}
},
{
"description": "Use this when you need the published single-mailpiece PostalForm workflow catalog available to agents. Coordinated statutory multi-recipient workflows are excluded.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"cursor": {
"description": "Pagination cursor (opaque string).",
"type": "string"
},
"limit": {
"description": "Max results (default 50).",
"exclusiveMinimum": 0,
"maximum": 200,
"type": "integer"
},
"q": {
"description": "Optional search query (matches slug/name).",
"type": "string"
}
},
"type": "object"
},
"name": "postalform.list_forms",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"forms": {
"items": {
"additionalProperties": false,
"properties": {
"aliases": {
"items": {
"type": "string"
},
"type": "array"
},
"attachments": {
"items": {
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"required": {
"type": "boolean"
}
},
"required": [
"id",
"label",
"required"
],
"type": "object"
},
"type": "array"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"certified_mail": {
"enum": [
"required",
"optional",
"none"
],
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"multi_recipient": {
"type": "boolean"
},
"name": {
"type": "string"
},
"published_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"recipient_mode": {
"enum": [
"user",
"predefined",
"computed"
],
"type": "string"
},
"slug": {
"type": "string"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"slug",
"name"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"forms",
"next_cursor"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"order_id": {
"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)$",
"type": "string"
},
"payment_authorization": {
"description": "Buyer-approved MPP Authorization header, usually Payment ... . Omit to retrieve the challenge.",
"minLength": 1,
"type": "string"
}
},
"required": [
"order_id"
],
"type": "object"
},
"name": "postalform.pay_order",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"bulk": {
"additionalProperties": false,
"properties": {
"campaign_id": {
"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)$",
"type": "string"
},
"content_mode": {
"enum": [
"text",
"html",
"pdf"
],
"type": "string"
},
"recipient_count": {
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"type": "integer"
},
"status": {
"type": "string"
},
"status_counts": {
"additionalProperties": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"propertyNames": {
"type": "string"
},
"type": "object"
}
},
"required": [
"campaign_id",
"recipient_count",
"content_mode",
"status",
"status_counts"
],
"type": "object"
},
"campaign_url": {
"format": "uri",
"type": "string"
},
"checkout_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"endpoint": {
"format": "uri",
"type": "string"
},
"is_paid": {
"type": "boolean"
},
"mailpiece_type": {
"enum": [
"letter",
"postcard"
],
"type": "string"
},
"next_action": {
"type": "string"
},
"next_step": {
"type": "string"
},
"order_complete_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"order_id": {
"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)$",
"type": "string"
},
"page_count": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"payment": {},
"payment_options": {
"items": {
"additionalProperties": false,
"properties": {
"type": {
"type": "string"
},
"url": {
"format": "uri",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
},
"type": "array"
},
"payment_status": {
"type": "string"
},
"postcard_size": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preview_url": {
"anyOf": [
{
"format": "uri",
"type": "string"
},
{
"type": "null"
}
]
},
"price_usd": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"protocol": {
"enum": [
"mpp",
"x402"
],
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"status": {
"type": "string"
},
"status_url": {
"format": "uri",
"type": "string"
},
"view": {
"const": "machine_order",
"type": "string"
}
},
"required": [
"view",
"protocol",
"order_id",
"request_id",
"endpoint",
"status",
"payment_status",
"is_paid",
"price_usd",
"currency",
"mailpiece_type",
"postcard_size",
"order_complete_url"
],
"type": "object"
}
},
{
"description": "Use this when you want a quick health check that the PostalForm MCP server is reachable.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {},
"type": "object"
},
"name": "postalform.ping",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"message": {
"type": "string"
},
"title": {
"type": "string"
},
"view": {
"const": "ping",
"type": "string"
}
},
"required": [
"view",
"title",
"message"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"certified": {
"type": "boolean"
},
"certified_return_receipt": {
"type": "boolean"
},
"color": {
"type": "boolean"
},
"double_sided": {
"type": "boolean"
},
"letter": {
"properties": {
"body": {
"maxLength": 20000,
"minLength": 1,
"type": "string"
},
"render": {
"properties": {
"font": {
"enum": [
"times",
"helvetica"
],
"type": "string"
},
"font_size": {
"maximum": 14,
"minimum": 9,
"type": "integer"
},
"margin_in": {
"maximum": 1.5,
"minimum": 0.5,
"type": "number"
},
"paper": {
"const": "letter",
"type": "string"
}
},
"type": "object"
},
"signature": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"dataUrl": {
"type": "string"
},
"mode": {
"enum": [
"typed",
"drawn"
],
"type": "string"
},
"printDataUrl": {
"type": "string"
},
"text": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
}
]
},
"title": {
"maxLength": 200,
"type": "string"
}
},
"required": [
"body"
],
"type": "object"
},
"mail_class": {
"enum": [
"standard",
"priority",
"express"
],
"type": "string"
},
"recipient_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"recipient_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"recipient_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"recipient_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"recipient_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"sender_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"sender_address_manual": {
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"line2",
"city",
"zip"
],
"type": "object"
},
"sender_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"sender_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"sender_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
}
},
"required": [
"letter",
"sender_name",
"sender_address_type",
"recipient_name",
"recipient_address_type"
],
"type": "object"
},
"name": "postalform.preview_letter_order_draft",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"draft_request": {
"additionalProperties": false,
"properties": {
"certified": {
"type": "boolean"
},
"certified_return_receipt": {
"type": "boolean"
},
"color": {
"type": "boolean"
},
"double_sided": {
"type": "boolean"
},
"letter": {
"additionalProperties": false,
"properties": {
"body": {
"maxLength": 20000,
"minLength": 1,
"type": "string"
},
"render": {
"additionalProperties": false,
"properties": {
"font": {
"enum": [
"times",
"helvetica"
],
"type": "string"
},
"font_size": {
"maximum": 14,
"minimum": 9,
"type": "integer"
},
"margin_in": {
"maximum": 1.5,
"minimum": 0.5,
"type": "number"
},
"paper": {
"const": "letter",
"type": "string"
}
},
"type": "object"
},
"signature": {
"anyOf": [
{
"maxLength": 2000,
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"dataUrl": {
"type": "string"
},
"mode": {
"enum": [
"typed",
"drawn"
],
"type": "string"
},
"printDataUrl": {
"type": "string"
},
"text": {
"maxLength": 2000,
"type": "string"
}
},
"type": "object"
}
]
},
"title": {
"maxLength": 200,
"type": "string"
}
},
"required": [
"body"
],
"type": "object"
},
"mail_class": {
"enum": [
"standard",
"priority",
"express"
],
"type": "string"
},
"recipient_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"recipient_address_manual": {
"additionalProperties": false,
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"city",
"zip"
],
"type": "object"
},
"recipient_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"recipient_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"recipient_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
},
"request_id": {
"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)$",
"type": "string"
},
"sender_address_id": {
"maxLength": 255,
"minLength": 1,
"type": "string"
},
"sender_address_manual": {
"additionalProperties": false,
"properties": {
"city": {
"minLength": 1,
"type": "string"
},
"country": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"countryCode": {
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"line1": {
"minLength": 1,
"type": "string"
},
"line2": {
"minLength": 1,
"type": "string"
},
"state": {
"maxLength": 60,
"minLength": 1,
"type": "string"
},
"zip": {
"maxLength": 20,
"minLength": 1,
"type": "string"
}
},
"required": [
"line1",
"city",
"zip"
],
"type": "object"
},
"sender_address_text": {
"maxLength": 2000,
"minLength": 1,
"type": "string"
},
"sender_address_type": {
"enum": [
"Address",
"Container",
"Manual"
],
"type": "string"
},
"sender_name": {
"maxLength": 32,
"minLength": 1,
"type": "string"
}
},
"required": [
"letter",
"sender_name",
"sender_address_type",
"recipient_name",
"recipient_address_type"
],
"type": "object"
},
"page_count": {
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"price_usd": {
"minimum": 0,
"type": "number"
},
"recipient_address_text": {
"type": "string"
},
"recipient_name": {
"type": "string"
},
"sender_address_text": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"view": {
"const": "letter_order_preview",
"type": "string"
}
},
"required": [
"view",
"page_count",
"price_usd",
"sender_name",
"sender_address_text",
"recipient_name",
"recipient_address_text",
"draft_request"
],
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"container": {
"description": "Loqate container id for drilling into suggestions, if provided",
"type": "string"
},
"country_code": {
"description": "Two-letter country code to filter suggestions. Defaults to US.",
"maxLength": 2,
"minLength": 2,
"type": "string"
},
"query": {
"description": "Partial address text, e.g. \"123 Main St\"",
"minLength": 3,
"type": "string"
},
"target": {
"description": "Which address field is being searched (used for UI context).",
"enum": [
"sender",
"recipient"
],
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "postalform.search_addresses",
"outputSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"query": {
"type": "string"
},
"suggestions": {
"items": {
"additionalProperties": false,
"properties": {
"countryCode": {
"type": "string"
},
"countryName": {
"type": "string"
},
"description": {
"type": "string"
},
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"type": {
"type": "string"
}
},
"required": [
"id",
"text",
"type",
"description"
],
"type": "object"
},
"type": "array"
},
"target": {
"enum": [
"sender",
"recipient"
],
"type": "string"
},
"view": {
"const": "address_suggestions",
"type": "string"
}
},
"required": [
"view",
"query",
"suggestions"
],
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:4886c2975438cf8dbaea15ffb569461d8902cdabcf4d73c9da495a0e25fe1634 | sha256sum