PostalForm MCP — MCP Radar

complete_checkout

Pay a prepared 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.

Acceso externo

Esquema de entrada

{'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': 256, '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.'}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['id', 'buyer', 'status', 'currency', 'line_items', 'fulfillment_options', 'totals', 'messages', 'links'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'buyer': {'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}}, 'additionalProperties': False}, 'links': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'enum': ['terms_of_use', 'privacy_policy', 'seller_shop_policies'], 'type': 'string'}, 'value': {'type': 'string', 'format': 'uri'}}, 'additionalProperties': False}}, 'order': {'type': 'object', 'required': ['id', 'checkout_session_id', 'permalink_url'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'permalink_url': {'type': 'string', 'format': 'uri'}, 'checkout_session_id': {'type': 'string', 'minLength': 1}}, 'additionalProperties': False}, 'status': {'enum': ['not_ready_for_payment', 'ready_for_payment', 'completed', 'canceled'], 'type': 'string'}, 'totals': {'type': 'array', 'items': {'type': 'object', 'required': ['type', 'display_text', 'amount'], 'properties': {'type': {'enum': ['items_base_amount', 'items_discount', 'subtotal', 'discount', 'fulfillment', 'tax', 'fee', 'total'], 'type': 'string'}, 'amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'display_text': {'type': 'string', 'minLength': 1}}, 'additionalProperties': False}}, 'currency': {'type': 'string'}, 'messages': {'type': 'array', 'items': {'anyOf': [{'type': 'object', 'required': ['type', 'param', 'content_type', 'content'], 'properties': {'type': {'type': 'string', 'const': 'info'}, 'param': {'type': 'string', 'minLength': 1}, 'content': {'type': 'string', 'minLength': 1}, 'content_type': {'enum': ['plain', 'markdown'], 'type': 'string'}}, 'additionalProperties': False}, {'type': 'object', 'required': ['type', 'code', 'content_type', 'content'], 'properties': {'code': {'enum': ['missing', 'invalid', 'out_of_stock', 'payment_declined', 'requires_sign_in', 'requires_3ds'], 'type': 'string'}, 'type': {'type': 'string', 'const': 'error'}, 'param': {'type': 'string', 'minLength': 1}, 'content': {'type': 'string', 'minLength': 1}, 'content_type': {'enum': ['plain', 'markdown'], 'type': 'string'}}, 'additionalProperties': False}]}}, 'line_items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'item', 'base_amount', 'discount', 'subtotal', 'tax', 'total'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'tax': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'item': {'type': 'object', 'required': ['id', 'quantity'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'quantity': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'discount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'subtotal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'base_amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'additionalProperties': False}}, 'fulfillment_address': {'type': 'object', 'required': ['name', 'line_one', 'city', 'state', 'country', 'postal_code'], 'properties': {'city': {'type': 'string', 'maxLength': 60, 'minLength': 1}, 'name': {'type': 'string', 'maxLength': 256, '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}}, 'additionalProperties': False}, 'fulfillment_options': {'type': 'array', 'items': {'anyOf': [{'type': 'object', 'required': ['type', 'id', 'title', 'subtitle', 'earliest_delivery_time', 'latest_delivery_time', 'subtotal', 'tax', 'total'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'tax': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'type': {'type': 'string', 'const': 'shipping'}, 'title': {'type': 'string', 'minLength': 1}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'carrier': {'type': 'string', 'minLength': 1}, 'subtitle': {'type': 'string', 'minLength': 1}, 'subtotal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'carrier_info': {'type': 'string', 'minLength': 1}, 'latest_delivery_time': {'type': 'string', 'minLength': 1}, 'earliest_delivery_time': {'type': 'string', 'minLength': 1}}, 'additionalProperties': False}, {'type': 'object', 'required': ['type', 'id', 'title', 'subtotal', 'tax', 'total'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'tax': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'type': {'type': 'string', 'const': 'digital'}, 'title': {'type': 'string', 'minLength': 1}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'subtitle': {'type': 'string', 'minLength': 1}, 'subtotal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'additionalProperties': False}]}}, 'fulfillment_option_id': {'type': 'string', 'minLength': 1}}, 'additionalProperties': False}

postalform.create_form_order_draft

Create a mail order draft from a workflow form submission

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.

Acceso externo

Esquema de entrada

{'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': 32, 'minLength': 1}, 'double_sided': {'type': 'boolean'}, 'recipient_name': {'type': 'string', 'maxLength': 32, '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}}}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'order_id', 'page_count', 'price_usd', 'checkout_url', 'sender_name', 'sender_address_text', 'recipient_name', 'recipient_address_text'], 'properties': {'view': {'type': 'string', 'const': 'order_draft'}, 'payment': {'type': 'object', 'required': ['view', 'protocol', 'order_id', 'request_id', 'endpoint', 'status', 'payment_status', 'is_paid', 'price_usd', 'currency', 'mailpiece_type', 'postcard_size', 'order_complete_url'], 'properties': {'bulk': {'type': 'object', 'required': ['campaign_id', 'recipient_count', 'content_mode', 'status', 'status_counts'], 'properties': {'status': {'type': 'string'}, 'campaign_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)$'}, 'content_mode': {'enum': ['text', 'html', 'pdf'], 'type': 'string'}, 'status_counts': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'recipient_count': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'view': {'type': 'string', 'const': 'machine_order'}, 'status': {'type': 'string'}, 'is_paid': {'type': 'boolean'}, 'payment': {}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'endpoint': {'type': 'string', 'format': 'uri'}, '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)$'}, 'protocol': {'enum': ['mpp', 'x402'], 'type': 'string'}, 'next_step': {'type': 'string'}, 'price_usd': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, '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)$'}, 'status_url': {'type': 'string', 'format': 'uri'}, 'next_action': {'type': 'string'}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'campaign_url': {'type': 'string', 'format': 'uri'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'postcard_size': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'mailpiece_type': {'enum': ['letter', 'postcard'], 'type': 'string'}, 'payment_status': {'type': 'string'}, 'payment_options': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'type': 'string'}}, 'additionalProperties': False}}, 'order_complete_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, '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)$'}, 'price_usd': {'anyOf': [{'type': 'number', 'minimum': 0}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}]}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'sender_name': {'type': 'string'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'recipient_name': {'type': 'string'}, 'checkout_session': {'type': 'object', 'required': ['id', 'payment_provider', 'status', 'currency', 'line_items', 'totals', 'links'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'links': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'enum': ['terms_of_use', 'privacy_policy', 'seller_shop_policies'], 'type': 'string'}, 'value': {'type': 'string', 'format': 'uri'}}, 'additionalProperties': False}}, 'status': {'enum': ['not_ready_for_payment', 'ready_for_payment', 'completed', 'canceled'], 'type': 'string'}, 'totals': {'type': 'array', 'items': {'type': 'object', 'required': ['type', 'display_text', 'amount'], 'properties': {'type': {'enum': ['items_base_amount', 'items_discount', 'subtotal', 'discount', 'fulfillment', 'tax', 'fee', 'total'], 'type': 'string'}, 'amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'display_text': {'type': 'string', 'minLength': 1}}, 'additionalProperties': False}}, 'currency': {'type': 'string', 'minLength': 1}, 'line_items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'item', 'base_amount', 'discount', 'subtotal', 'tax', 'total'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'tax': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'item': {'type': 'object', 'required': ['id', 'quantity'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'quantity': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'discount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'subtotal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'base_amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'additionalProperties': False}}, 'payment_mode': {'enum': ['test', 'live'], 'type': 'string'}, 'payment_provider': {'type': 'object', 'required': ['provider', 'supported_payment_methods'], 'properties': {'provider': {'enum': ['stripe', 'adyen'], 'type': 'string'}, 'merchant_id': {'type': 'string', 'minLength': 1}, 'supported_payment_methods': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'payment_protocol': {'enum': ['hosted', 'mpp'], 'type': 'string'}, 'sender_address_text': {'type': 'string'}, 'recipient_address_text': {'type': 'string'}}, 'additionalProperties': False}

postalform.create_letter_order_draft

Create a mail order draft from letter text

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.

Acceso externo

Esquema de entrada

{'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': 32, 'minLength': 1}, 'double_sided': {'type': 'boolean'}, 'recipient_name': {'type': 'string', 'maxLength': 32, '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}}}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'order_id', 'page_count', 'price_usd', 'checkout_url', 'sender_name', 'sender_address_text', 'recipient_name', 'recipient_address_text'], 'properties': {'view': {'type': 'string', 'const': 'order_draft'}, 'payment': {'type': 'object', 'required': ['view', 'protocol', 'order_id', 'request_id', 'endpoint', 'status', 'payment_status', 'is_paid', 'price_usd', 'currency', 'mailpiece_type', 'postcard_size', 'order_complete_url'], 'properties': {'bulk': {'type': 'object', 'required': ['campaign_id', 'recipient_count', 'content_mode', 'status', 'status_counts'], 'properties': {'status': {'type': 'string'}, 'campaign_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)$'}, 'content_mode': {'enum': ['text', 'html', 'pdf'], 'type': 'string'}, 'status_counts': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'recipient_count': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'view': {'type': 'string', 'const': 'machine_order'}, 'status': {'type': 'string'}, 'is_paid': {'type': 'boolean'}, 'payment': {}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'endpoint': {'type': 'string', 'format': 'uri'}, '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)$'}, 'protocol': {'enum': ['mpp', 'x402'], 'type': 'string'}, 'next_step': {'type': 'string'}, 'price_usd': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, '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)$'}, 'status_url': {'type': 'string', 'format': 'uri'}, 'next_action': {'type': 'string'}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'campaign_url': {'type': 'string', 'format': 'uri'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'postcard_size': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'mailpiece_type': {'enum': ['letter', 'postcard'], 'type': 'string'}, 'payment_status': {'type': 'string'}, 'payment_options': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'type': 'string'}}, 'additionalProperties': False}}, 'order_complete_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, '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)$'}, 'price_usd': {'anyOf': [{'type': 'number', 'minimum': 0}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}]}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'sender_name': {'type': 'string'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'recipient_name': {'type': 'string'}, 'checkout_session': {'type': 'object', 'required': ['id', 'payment_provider', 'status', 'currency', 'line_items', 'totals', 'links'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'links': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'enum': ['terms_of_use', 'privacy_policy', 'seller_shop_policies'], 'type': 'string'}, 'value': {'type': 'string', 'format': 'uri'}}, 'additionalProperties': False}}, 'status': {'enum': ['not_ready_for_payment', 'ready_for_payment', 'completed', 'canceled'], 'type': 'string'}, 'totals': {'type': 'array', 'items': {'type': 'object', 'required': ['type', 'display_text', 'amount'], 'properties': {'type': {'enum': ['items_base_amount', 'items_discount', 'subtotal', 'discount', 'fulfillment', 'tax', 'fee', 'total'], 'type': 'string'}, 'amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'display_text': {'type': 'string', 'minLength': 1}}, 'additionalProperties': False}}, 'currency': {'type': 'string', 'minLength': 1}, 'line_items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'item', 'base_amount', 'discount', 'subtotal', 'tax', 'total'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'tax': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'item': {'type': 'object', 'required': ['id', 'quantity'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'quantity': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'discount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'subtotal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'base_amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'additionalProperties': False}}, 'payment_mode': {'enum': ['test', 'live'], 'type': 'string'}, 'payment_provider': {'type': 'object', 'required': ['provider', 'supported_payment_methods'], 'properties': {'provider': {'enum': ['stripe', 'adyen'], 'type': 'string'}, 'merchant_id': {'type': 'string', 'minLength': 1}, 'supported_payment_methods': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'payment_protocol': {'enum': ['hosted', 'mpp'], 'type': 'string'}, 'sender_address_text': {'type': 'string'}, 'recipient_address_text': {'type': 'string'}}, 'additionalProperties': False}

postalform.create_machine_order

Create or pay a 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.

Acceso externo

Esquema de entrada

{'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': 256, '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': 256, '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}}}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'protocol', 'order_id', 'request_id', 'endpoint', 'status', 'payment_status', 'is_paid', 'price_usd', 'currency', 'mailpiece_type', 'postcard_size', 'order_complete_url'], 'properties': {'bulk': {'type': 'object', 'required': ['campaign_id', 'recipient_count', 'content_mode', 'status', 'status_counts'], 'properties': {'status': {'type': 'string'}, 'campaign_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)$'}, 'content_mode': {'enum': ['text', 'html', 'pdf'], 'type': 'string'}, 'status_counts': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'recipient_count': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'view': {'type': 'string', 'const': 'machine_order'}, 'status': {'type': 'string'}, 'is_paid': {'type': 'boolean'}, 'payment': {}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'endpoint': {'type': 'string', 'format': 'uri'}, '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)$'}, 'protocol': {'enum': ['mpp', 'x402'], 'type': 'string'}, 'next_step': {'type': 'string'}, 'price_usd': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, '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)$'}, 'status_url': {'type': 'string', 'format': 'uri'}, 'next_action': {'type': 'string'}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'campaign_url': {'type': 'string', 'format': 'uri'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'postcard_size': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'mailpiece_type': {'enum': ['letter', 'postcard'], 'type': 'string'}, 'payment_status': {'type': 'string'}, 'payment_options': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'type': 'string'}}, 'additionalProperties': False}}, 'order_complete_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}

postalform.create_order_draft

Create a mail 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.

Acceso externo

Esquema de entrada

{'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': 32, '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': 32, '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).'}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'order_id', 'page_count', 'price_usd', 'checkout_url', 'sender_name', 'sender_address_text', 'recipient_name', 'recipient_address_text'], 'properties': {'view': {'type': 'string', 'const': 'order_draft'}, 'payment': {'type': 'object', 'required': ['view', 'protocol', 'order_id', 'request_id', 'endpoint', 'status', 'payment_status', 'is_paid', 'price_usd', 'currency', 'mailpiece_type', 'postcard_size', 'order_complete_url'], 'properties': {'bulk': {'type': 'object', 'required': ['campaign_id', 'recipient_count', 'content_mode', 'status', 'status_counts'], 'properties': {'status': {'type': 'string'}, 'campaign_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)$'}, 'content_mode': {'enum': ['text', 'html', 'pdf'], 'type': 'string'}, 'status_counts': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'recipient_count': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'view': {'type': 'string', 'const': 'machine_order'}, 'status': {'type': 'string'}, 'is_paid': {'type': 'boolean'}, 'payment': {}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'endpoint': {'type': 'string', 'format': 'uri'}, '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)$'}, 'protocol': {'enum': ['mpp', 'x402'], 'type': 'string'}, 'next_step': {'type': 'string'}, 'price_usd': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, '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)$'}, 'status_url': {'type': 'string', 'format': 'uri'}, 'next_action': {'type': 'string'}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'campaign_url': {'type': 'string', 'format': 'uri'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'postcard_size': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'mailpiece_type': {'enum': ['letter', 'postcard'], 'type': 'string'}, 'payment_status': {'type': 'string'}, 'payment_options': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'type': 'string'}}, 'additionalProperties': False}}, 'order_complete_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, '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)$'}, 'price_usd': {'anyOf': [{'type': 'number', 'minimum': 0}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, {'type': 'null'}]}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'sender_name': {'type': 'string'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'recipient_name': {'type': 'string'}, 'checkout_session': {'type': 'object', 'required': ['id', 'payment_provider', 'status', 'currency', 'line_items', 'totals', 'links'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'links': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'enum': ['terms_of_use', 'privacy_policy', 'seller_shop_policies'], 'type': 'string'}, 'value': {'type': 'string', 'format': 'uri'}}, 'additionalProperties': False}}, 'status': {'enum': ['not_ready_for_payment', 'ready_for_payment', 'completed', 'canceled'], 'type': 'string'}, 'totals': {'type': 'array', 'items': {'type': 'object', 'required': ['type', 'display_text', 'amount'], 'properties': {'type': {'enum': ['items_base_amount', 'items_discount', 'subtotal', 'discount', 'fulfillment', 'tax', 'fee', 'total'], 'type': 'string'}, 'amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'display_text': {'type': 'string', 'minLength': 1}}, 'additionalProperties': False}}, 'currency': {'type': 'string', 'minLength': 1}, 'line_items': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'item', 'base_amount', 'discount', 'subtotal', 'tax', 'total'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'tax': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'item': {'type': 'object', 'required': ['id', 'quantity'], 'properties': {'id': {'type': 'string', 'minLength': 1}, 'quantity': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'total': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'discount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'subtotal': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'base_amount': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'additionalProperties': False}}, 'payment_mode': {'enum': ['test', 'live'], 'type': 'string'}, 'payment_provider': {'type': 'object', 'required': ['provider', 'supported_payment_methods'], 'properties': {'provider': {'enum': ['stripe', 'adyen'], 'type': 'string'}, 'merchant_id': {'type': 'string', 'minLength': 1}, 'supported_payment_methods': {'type': 'array', 'items': {'type': 'string', 'minLength': 1}}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'payment_protocol': {'enum': ['hosted', 'mpp'], 'type': 'string'}, 'sender_address_text': {'type': 'string'}, 'recipient_address_text': {'type': 'string'}}, 'additionalProperties': False}

postalform.create_pdf_upload

Create a 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.

Acceso externo

Esquema de entrada

{'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.'}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['upload_url', 'upload_token', 'expires_at', 'max_bytes', 'required_headers'], 'properties': {'max_bytes': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'expires_at': {'type': 'string'}, 'upload_url': {'type': 'string', 'format': 'uri'}, 'upload_token': {'type': 'string'}, 'required_headers': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'string'}}}, 'additionalProperties': False}

postalform.get_form_schema

Get form schema

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

Solo lectura Idempotente

Esquema de entrada

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

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['schema_version', 'workflow_version', 'slug', 'name', 'llms', 'indexable', 'certified_mail', 'recipient', 'groups', 'fields', 'attachments', 'attachments_max_total_size_mb'], 'properties': {'llms': {'type': 'boolean'}, 'name': {'type': 'string'}, 'slug': {'type': 'string'}, 'fields': {'type': 'array', 'items': {}}, 'groups': {'type': 'array', 'items': {}}, 'topics': {'type': 'array', 'items': {'type': 'string'}}, 'aliases': {'type': 'array', 'items': {'type': 'string'}}, 'pricing': {'type': 'object', 'required': ['minimumTotalCents', 'currency', 'description', 'additiveMailServices'], 'properties': {'currency': {'type': 'string', 'const': 'USD'}, 'description': {'type': 'string'}, 'minimumTotalCents': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}, 'additiveMailServices': {'type': 'array', 'items': {'enum': ['certified_return_receipt'], 'type': 'string'}}}, 'additionalProperties': False}, 'category': {'type': 'string'}, 'bulk_form': {}, 'indexable': {'type': 'boolean'}, 'recipient': {'type': 'object', 'required': ['mode'], 'properties': {'mode': {'enum': ['user', 'predefined', 'computed'], 'type': 'string'}, 'name': {'type': 'string'}, 'address': {'type': 'object', 'required': ['line1', 'city', 'state', 'zip'], 'properties': {'zip': {'type': 'string'}, 'city': {'type': 'string'}, 'line1': {'type': 'string'}, 'line2': {'type': 'string'}, 'state': {'type': 'string'}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'updated_at': {'type': 'string'}, 'attachments': {'type': 'array', 'items': {}}, 'description': {'type': 'string'}, 'form_summary': {'type': 'string'}, 'published_at': {'type': 'string'}, 'agent_summary': {'type': 'string'}, 'checkout_flow': {'enum': ['home', 'forms_order'], 'type': 'string'}, 'publish_state': {'type': 'string'}, 'certified_mail': {'enum': ['required', 'optional', 'none'], 'type': 'string'}, 'data_collected': {'type': 'array', 'items': {'type': 'string'}}, 'schema_version': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'deadline_helper': {}, 'multi_recipient': {}, 'recipient_rules': {}, 'workflow_version': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': -9007199254740991}, 'compliance_policy': {}, 'recipient_presets': {}, 'attachments_max_total_size_mb': {'type': 'number', 'exclusiveMinimum': 0}}, 'additionalProperties': False}

postalform.get_order_status

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.

Solo lectura Idempotente

Esquema de entrada

{'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.'}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'found', 'order_id'], 'properties': {'bulk': {'type': 'object', 'required': ['campaign_id', 'recipient_count', 'content_mode', 'status', 'status_counts'], 'properties': {'status': {'type': 'string'}, 'campaign_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)$'}, 'content_mode': {'enum': ['text', 'html', 'pdf'], 'type': 'string'}, 'status_counts': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'recipient_count': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'view': {'type': 'string', 'const': 'order_status'}, 'error': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'found': {'type': 'boolean'}, 'carrier': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'is_paid': {'type': 'boolean'}, '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)$'}, 'signed_by': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'status_url': {'type': 'string'}, 'next_action': {'type': 'string'}, 'campaign_url': {'type': 'string', 'format': 'uri'}, 'checkout_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'current_step': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'mailing_status': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'payment_status': {'type': 'string'}, 'delivery_status': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'payment_options': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'type': 'string'}}, 'additionalProperties': False}}, 'tracking_events': {'type': 'array', 'items': {'type': 'object', 'required': ['status', 'statusNormalized', 'statusDetail', 'message', 'occurredAt', 'location'], 'properties': {'status': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'message': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'location': {'anyOf': [{'type': 'object', 'required': ['postalCode', 'city', 'state', 'label'], 'properties': {'city': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'label': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'state': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'postalCode': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}, {'type': 'null'}]}, 'occurredAt': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'statusDetail': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'statusNormalized': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}}, 'tracking_number': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'tracking_updated_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'estimated_delivery_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'delivery_status_detail': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'electronic_return_receipt': {'type': 'object', 'required': ['requested', 'status', 'document_available', 'emailed_at'], 'properties': {'status': {'anyOf': [{'enum': ['manual', 'pending', 'sent', 'failed'], 'type': 'string'}, {'type': 'null'}]}, 'requested': {'type': 'boolean'}, 'emailed_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'document_available': {'type': 'boolean'}}, 'additionalProperties': False}, 'mailing_status_normalized': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}

postalform.list_forms

List available forms

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

Solo lectura Idempotente

Esquema de entrada

{'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).'}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['forms', 'next_cursor'], 'properties': {'forms': {'type': 'array', 'items': {'type': 'object', 'required': ['slug', 'name'], 'properties': {'name': {'type': 'string'}, 'slug': {'type': 'string'}, 'aliases': {'type': 'array', 'items': {'type': 'string'}}, 'category': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'updated_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'attachments': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'label', 'required'], 'properties': {'id': {'type': 'string'}, 'label': {'type': 'string'}, 'required': {'type': 'boolean'}}, 'additionalProperties': False}}, 'description': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'published_at': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'certified_mail': {'enum': ['required', 'optional', 'none'], 'type': 'string'}, 'recipient_mode': {'enum': ['user', 'predefined', 'computed'], 'type': 'string'}, 'multi_recipient': {'type': 'boolean'}}, 'additionalProperties': False}}, 'next_cursor': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}

postalform.pay_order

Pay a prepared order with MPP

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.

Acceso externo

Esquema de entrada

{'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.'}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'protocol', 'order_id', 'request_id', 'endpoint', 'status', 'payment_status', 'is_paid', 'price_usd', 'currency', 'mailpiece_type', 'postcard_size', 'order_complete_url'], 'properties': {'bulk': {'type': 'object', 'required': ['campaign_id', 'recipient_count', 'content_mode', 'status', 'status_counts'], 'properties': {'status': {'type': 'string'}, 'campaign_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)$'}, 'content_mode': {'enum': ['text', 'html', 'pdf'], 'type': 'string'}, 'status_counts': {'type': 'object', 'propertyNames': {'type': 'string'}, 'additionalProperties': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}}, 'recipient_count': {'type': 'integer', 'maximum': 9007199254740991, 'exclusiveMinimum': 0}}, 'additionalProperties': False}, 'view': {'type': 'string', 'const': 'machine_order'}, 'status': {'type': 'string'}, 'is_paid': {'type': 'boolean'}, 'payment': {}, 'currency': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'endpoint': {'type': 'string', 'format': 'uri'}, '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)$'}, 'protocol': {'enum': ['mpp', 'x402'], 'type': 'string'}, 'next_step': {'type': 'string'}, 'price_usd': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, 'page_count': {'anyOf': [{'type': 'number'}, {'type': 'null'}]}, '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)$'}, 'status_url': {'type': 'string', 'format': 'uri'}, 'next_action': {'type': 'string'}, 'preview_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'campaign_url': {'type': 'string', 'format': 'uri'}, 'checkout_url': {'anyOf': [{'type': 'string', 'format': 'uri'}, {'type': 'null'}]}, 'postcard_size': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}, 'mailpiece_type': {'enum': ['letter', 'postcard'], 'type': 'string'}, 'payment_status': {'type': 'string'}, 'payment_options': {'type': 'array', 'items': {'type': 'object', 'required': ['type'], 'properties': {'url': {'type': 'string', 'format': 'uri'}, 'type': {'type': 'string'}}, 'additionalProperties': False}}, 'order_complete_url': {'anyOf': [{'type': 'string'}, {'type': 'null'}]}}, 'additionalProperties': False}

postalform.ping

Ping PostalForm

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

Solo lectura Idempotente

Esquema de entrada

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

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'title', 'message'], 'properties': {'view': {'type': 'string', 'const': 'ping'}, 'title': {'type': 'string'}, 'message': {'type': 'string'}}, 'additionalProperties': False}

postalform.preview_letter_order_draft

Preview a mail order draft from letter text

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.

Solo lectura

Esquema de entrada

{'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': 32, 'minLength': 1}, 'double_sided': {'type': 'boolean'}, 'recipient_name': {'type': 'string', 'maxLength': 32, '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}}}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'page_count', 'price_usd', 'sender_name', 'sender_address_text', 'recipient_name', 'recipient_address_text', 'draft_request'], 'properties': {'view': {'type': 'string', 'const': 'letter_order_preview'}, 'price_usd': {'type': 'number', 'minimum': 0}, 'page_count': {'type': 'integer', 'maximum': 9007199254740991, 'minimum': 0}, 'sender_name': {'type': 'string'}, 'draft_request': {'type': 'object', '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}}, 'additionalProperties': False}, 'signature': {'anyOf': [{'type': 'string', 'maxLength': 2000}, {'type': 'object', 'properties': {'mode': {'enum': ['typed', 'drawn'], 'type': 'string'}, 'text': {'type': 'string', 'maxLength': 2000}, 'dataUrl': {'type': 'string'}, 'printDataUrl': {'type': 'string'}}, 'additionalProperties': False}]}}, 'additionalProperties': False}, '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': 32, 'minLength': 1}, 'double_sided': {'type': 'boolean'}, 'recipient_name': {'type': 'string', 'maxLength': 32, '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', '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}}, 'additionalProperties': False}, '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', '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}}, 'additionalProperties': False}}, 'additionalProperties': False}, 'recipient_name': {'type': 'string'}, 'sender_address_text': {'type': 'string'}, 'recipient_address_text': {'type': 'string'}}, 'additionalProperties': False}

postalform.search_addresses

Search mailing 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.

Solo lectura Idempotente

Esquema de entrada

{'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.'}}}

Esquema de salida

{'type': 'object', '$schema': 'http://json-schema.org/draft-07/schema#', 'required': ['view', 'query', 'suggestions'], 'properties': {'view': {'type': 'string', 'const': 'address_suggestions'}, 'query': {'type': 'string'}, 'target': {'enum': ['sender', 'recipient'], 'type': 'string'}, 'suggestions': {'type': 'array', 'items': {'type': 'object', 'required': ['id', 'text', 'type', 'description'], 'properties': {'id': {'type': 'string'}, 'text': {'type': 'string'}, 'type': {'type': 'string'}, 'countryCode': {'type': 'string'}, 'countryName': {'type': 'string'}, 'description': {'type': 'string'}}, 'additionalProperties': False}}}, 'additionalProperties': False}

PostalForm

Qué hace este MCP

Herramientas

Cambios recientes en herramientas

Servidores MCP similares

AgentLot Marketplace

Digital Manager Guru

Pagar.me

roastify-mcp

bitroad

Singularity Layer MCP

agentic-commerce

agentcard