PostalForm MCP

Envía cartas reales desde agentes: PDF → pago → estado.

Ver en postalform.comPrueba este MCPPatrocinado

Documentación

API de correo y servidor MCP remoto para agentes de IA

PostalForm es una API de correo y servidor MCP remoto para convertir PDF, cartas, formularios y resultados de agentes en correo postal físico real. Los desarrolladores pueden crear borradores de correo revisables, sesiones de pago alojadas, pedidos automáticos directos MPP/x402 y consultas de estado de cumplimiento sin construir infraestructura de impresión, sobres, franqueo o entrega al transportista.

Cuando el agente no tiene una billetera de pago compatible

Los pedidos automáticos de PDF, cartas, formularios, postales y lotes ordinarios devuelven un checkout_url, status_url, payment_options y next_action firmados junto con el desafío 402. Las herramientas de borrador MPP también devuelven checkout_url. El documento, el ID del pedido, el número de páginas y el total permanecen iguales independientemente de la opción de pago que elija el comprador. El pago alojado es una alternativa a MPP/x402, no un tipo de credencial MPP. Esta alternativa no se aplica a las API separadas de flores o etiquetas de envío.

  1. Revisa preview_url (o el campaign_url masivo), los destinatarios y el total con el comprador. Conserva un documento subido; no recrees su contenido como una carta para solucionar un problema de carga.
  2. Si el entorno de ejecución puede obtener realmente una credencial compatible aprobada, responde un desafío automático. Una cuenta de Link conectada por sí sola no establece que el entorno pueda acuñar un SPT. Link admite integraciones distintas de tarjeta virtual, SPT y Link Pay Token; usa la capacidad que exponga el entorno.
  3. De lo contrario, presenta el checkout_url devuelto. Abrirlo solo revisa el pedido. Continuar abre Checkout alojado por Stripe y reserva el pago alojado para este pedido; las llamadas automáticas posteriores devuelven la misma opción de pago. No se requiere configuración de billetera ni instalación de CLI para el comprador.
  4. Consulta status_url o postalform.get_order_status. payment_authorized significa que la tarjeta fue autorizada incluso mientras is_paid es falso. payment_processing y settled_pending_webhook también significan esperar, no pagar de nuevo. payment_review_required necesita conciliación de soporte; closed no se puede pagar. Usa los campos de cumplimiento/seguimiento para distinguir entre impresión, envío y entrega.

Los enlaces de Checkout caducan después de 24 horas; consulta el mismo pedido para obtener un enlace nuevo. Los inicios de Checkout concurrentes reutilizan una sesión. Una credencial rechazada antes del pago (por ejemplo, una prueba mal formada o un desafío caducado) deja el mismo pedido pagadero con una credencial corregida o pago alojado. Después de un pago automático interrumpido, reintenta la misma credencial y solicitud o consulta: una credencial o ruta de pago diferente está bloqueada mientras el resultado sea incierto. Una respuesta 402 por sí sola no prueba que un intento anterior fallara; un rechazo posterior no desbloquea un pago incierto. Sigue las opciones de pago y el estado devueltos. Un pago tardío que llegue fuera del Checkout seleccionado se retiene para conciliación y no desencadena otro envío.

¿Sin conexión MCP nativa? Usa los endpoints HTTP de creación y estado en OpenAPI. No cambies a carga por navegador solo porque el entorno no pueda adjuntar un servidor MCP remoto. Consulta la documentación de integración de Link de Stripe para la aprobación y recuperación de credenciales propiedad del agente; PostalForm no acuña credenciales desde la cuenta de Link de un usuario.

Respuesta rápida: ¿pueden los desarrolladores enviar correo postal a través de una API?

Sí. Usa PostalForm Projects cuando tu servidor necesite claves API persistentes, un entorno de prueba gratuito, cotizaciones de precio final, creación de pedidos idempotente y webhooks firmados. Usa las herramientas de borrador MCP remoto y pago alojado cuando una persona deba revisar el PDF, las direcciones, las opciones de envío y el precio antes del pago. Usa flujos de pago automático directo MPP o x402 solo para entornos autónomos con aprobación explícita del propietario, límites de gasto e ID de solicitud idempotentes.

Intención del desarrolladorRuta de PostalFormMejor opción predeterminada
Agregar una API de correo persistente a una aplicaciónUsa la API de correo para desarrolladores de PostalForm ProjectsComienza en modo de prueba gratuito con una clave API de proyecto
Permitir que un agente de IA prepare correo físicoConéctate al endpoint MCP remoto en https://postalform.com/mcpCrea un borrador de pago alojado
Permitir que ChatGPT, Claude, Gemini, Cursor o Codex usen herramientas de correoRegistra PostalForm como un servidor MCP HTTP remoto transmisibleRequiere aprobación para efectos secundarios de correo
Permitir que un entorno autónomo pague por correoUsa postalform.create_machine_order, MPP o x402Límite de gasto aprobado por el propietario más revisión previa
Listar PostalForm en un registro MCP o de agentesUsa la tarjeta del servidor MCP, el manifiesto del registro y esta página de desarrolladorEnvía las URL canónicas alojadas por PostalForm

Resumen listo para directorios

Usa esta tabla al evaluar PostalForm para un registro MCP, directorio de agentes, catálogo de API, revisión de conectores o listado de herramientas de desarrollador.

Campo de directorioValor de PostalForm
Tipo de productoAPI de correo físico y servidor MCP remoto
Endpoint principalhttps://postalform.com/mcp
TransporteMCP HTTP transmisible
Predeterminado revisado por humanosLas herramientas de borrador de pago alojado crean un borrador no pagado y una URL de Checkout para revisión antes del pago
Ruta con capacidad de pagoCada borrador de PDF, carta y formulario puede seleccionar MPP y usar postalform.pay_order después de la aprobación; postalform.create_machine_order también admite x402
URL de descubrimiento sin autenticación/openapi.json, /apis.json, /.well-known/mcp/server.json, /.well-known/mcp/server-card.json, /.well-known/mcp.json, /.well-known/agent-card.json, /.well-known/x402
Mejor destino de listadohttps://postalform.com/developers para catálogos de API/MCP; https://postalform.com/agents para directorios de agentes
Casos de uso principalesEnviar PDF, cartas, documentos generados, formularios de flujo de trabajo, paquetes de disputas, avisos de pago y consultas de estado
Límite de efectos secundariosLa creación de borradores no paga ni envía. El pago requiere Checkout alojado, un token de Stripe o una credencial MPP/x402
Política de aprobación recomendadaRequiere aprobación antes de compartir documentos, direcciones, credenciales de pago o enviar correo real

Descripción corta para directorio:

PostalForm is a remote MCP server and physical mail API for creating reviewable print-and-mail drafts from PDFs, letters, and forms, with hosted checkout, fulfillment status, and approved MPP/x402 machine-payment flows.

¿Qué superficie de integración deberías usar?

SuperficieÚsala paraEvítala cuando
API REST de PostalForm ProjectsAplicaciones del lado del servidor que necesitan claves API de proyecto, cumplimiento simulado gratuito, cotizaciones finales, créditos prepagados y webhooks firmadosUna persona debe aprobar cada documento y pago en Checkout alojado
Checkout alojado mediante herramientas de borrador MCPAsistentes orientados al usuario, clientes de chat web, herramientas de soporte y flujos de trabajo donde una persona debe aprobar el pagoEl agente ya ha sido autorizado para pagar de forma autónoma
Sesión de Checkout con token de StripeClientes que pueden obtener un token de pago compartido de Stripe aprobado por el compradorEl cliente no puede usar sesiones de Checkout ni tokens de pago compartidos
API REST raíz de pedidos automáticosIntegraciones MPP/x402 aprobadas que validan, pagan, reintentan y consultan sin un espacio de trabajo de ProjectsEl usuario aún necesita un paso de aprobación visual antes del pago
Pago automático MPPEntornos de agente que ya admiten semántica de desafío/recibo MPP, Tokens de Pago Compartido de Stripe o credenciales MPP de tarjetaFlujos simples orientados al usuario donde el Checkout alojado es más seguro
Pago automático x402Agentes y servicios nativos HTTP que pueden responder desafíos 402 Payment RequiredFlujos de trabajo sin infraestructura de billetera/pago ni controles de gasto
Endpoint MCP de Checkout UCPPlataformas que se integran específicamente con la capacidad de Checkout UCPBorradores de dirección manual, texto de carta o formularios de flujo de trabajo que necesitan herramientas MCP de PostalForm

Las etiquetas de envío de paquetes nacionales son un producto separado solo MPP. Usa POST /api/machine/mpp/shipping-labels/validate para tarifas de transportista en vivo, luego POST /api/machine/mpp/shipping-labels para crear y pagar. La respuesta pagada y la página de finalización exponen una descarga de PDF firmada; el correo de cumplimiento incluye el adjunto PDF y el enlace. Consulta la guía de etiquetas de envío MPP.

Descubrimiento MCP remoto

Usa estas URL canónicas al listar PostalForm en directorios MCP, catálogos de conectores o registros de agentes:

El servidor MCP alojado es mejor para clientes que pueden conectarse a un endpoint MCP HTTP remoto transmisible. Usa postalform.create_order_draft, postalform.create_letter_order_draft y postalform.create_form_order_draft para preparar un pedido para revisión del comprador, seguido de complete_checkout con un token de pago de Stripe compatible o pago a través de la URL de Checkout alojado. Para MPP, esas mismas herramientas de borrador aceptan payment_protocol: "mpp" y buyer_email; usa postalform.pay_order para pagar el pedido preparado después de la aprobación. postalform.create_machine_order también admite MPP y x402.

Para el patrón de diseño detrás de esta división, consulta hacer que el correo físico sea invocable desde agentes de IA.

ChatGPT, Gemini y otros clientes MCP

PostalForm está listo para clientes que puedan conectarse a servidores MCP remotos a través de HTTP transmisible. El mismo endpoint es utilizado por flujos estilo conector personalizado de ChatGPT, herramientas MCP de OpenAI Responses API, sesiones MCP del SDK de Gemini, Gemini CLI, Claude, Claude Code, Codex, Cursor, Windsurf, Cline, Replit, OpenClaw, Hermes, n8n, LangChain y clientes MCP similares.

Para integraciones con ChatGPT o OpenAI Responses API, configura PostalForm como un servidor MCP remoto:

{
  "type": "mcp",
  "server_label": "postalform",
  "server_description": "Create real PostalForm mail drafts, hosted checkout sessions, machine-payment mail orders, and order status lookups.",
  "server_url": "https://postalform.com/mcp",
  "require_approval": "always"
}

Para Gemini CLI, agrega PostalForm como un servidor MCP HTTP:

gemini mcp add --transport http postalform https://postalform.com/mcp

Para los SDK de Gemini, crea una sesión de cliente MCP contra el endpoint de PostalForm y pasa las herramientas de la sesión a la integración de llamada de herramientas de Gemini. Deja que el usuario revise el PDF, las direcciones, el precio y las opciones de envío antes de pagar. Un cliente compatible puede entonces usar complete_checkout con un token de Stripe aprobado por el comprador; de lo contrario, presenta el pago alojado.

UCP (Protocolo Universal de Comercio)

PostalForm también admite la capacidad de Pago UCP para plataformas que se integran mediante el enlace MCP de UCP.

Las sesiones de pago UCP se precian dinámicamente según el número de páginas del PDF y las opciones de impresión. PostalForm espera el PDF y los datos de dirección en metadata.postalform (el pdf puede ser { download_url, file_id }, { upload_token }, una URL de datos o una URL HTTPS pública). Las llamadas de herramientas UCP deben incluir un perfil de plataforma en _meta.ucp.profile.

Nota: UCP actualmente admite pagos basados en PDF con IDs de dirección Loqate (*_address_type="Address") únicamente. Para direcciones manuales, texto de carta y formularios de flujo de trabajo, usa las herramientas MCP de PostalForm en /mcp.

Ejemplo de create_checkout de UCP:

{
  "name": "create_checkout",
  "arguments": {
    "_meta": {
      "ucp": {
        "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
      }
    },
    "currency": "USD",
    "line_items": [{ "item": { "id": "postalform_mail_pdf_bw_double" }, "quantity": 1 }],
    "payment": {},
    "metadata": {
      "postalform": {
        "pdf": {
          "download_url": "https://example.oaiusercontent.com/file.pdf",
          "file_id": "file_abc123"
        },
        "file_name": "letter.pdf",
        "sender_name": "Sender Example",
        "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
        "sender_address_type": "Address",
        "sender_address_text": "123 Sender St, Springfield, IL 62701",
        "recipient_name": "Recipient Example",
        "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG",
        "recipient_address_type": "Address",
        "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
        "double_sided": true,
        "color": false
      }
    }
  }
}

Pagos automáticos (x402)

PostalForm admite pagos automáticos basados en x402 para la creación directa de pedidos por API. Los endpoints de pago automático están diseñados para entornos de ejecución de agentes que pueden no tener un inicio de sesión o una clave API de PostalForm: la llamada de creación no pagada devuelve un desafío de pago, y el reintento pagado autoriza el pedido. Los payloads de cartas pueden ser texto sin formato, HTML, Markdown o RTF y pueden incluir firmas mecanografiadas o dibujadas; PostalForm renderiza el PDF en el servidor y puede devolver una URL de vista previa firmada antes del pago.

Para una descripción general amigable para rastreadores del flujo de correo físico x402, campos de directorio y valores predeterminados de seguridad, consulta API de correo físico x402.

  • Endpoint de crear/pagar: POST https://postalform.com/api/machine/orders
  • Endpoint de validar/cotizar (sin efectos secundarios de pago): POST https://postalform.com/api/machine/orders/validate
  • Endpoint de estado: GET https://postalform.com/api/machine/orders/:id
  • Flujo: la solicitud no pagada devuelve 402 + PAYMENT-REQUIRED, el cliente paga y reintenta con PAYMENT-SIGNATURE, el servidor devuelve 202 + PAYMENT-RESPONSE; settled_pending_webhook significa que Stripe aún está verificando el acuerdo, así que consulta el endpoint de estado en lugar de pagar nuevamente
  • El cuerpo de 402 repite el desafío decodificado como payment.payment_required. /api/machine/* permite solicitudes de navegador de origen cruzado y expone PAYMENT-REQUIRED, PAYMENT-RESPONSE y WWW-Authenticate. Solo se acepta x402 v2 (PAYMENT-SIGNATURE), no el encabezado v1 X-PAYMENT

Campos de solicitud requeridos para POST /api/machine/orders:

  • request_id (UUID)
  • buyer_name
  • buyer_email (requerido; se establece en Stripe PaymentIntent como receipt_email)
  • exactamente una fuente de documento:
    • pdf (formato canónico recomendado: { "upload_token": "..." }; también acepta { download_url, file_id }, URL de datos o URL HTTPS pública)
    • letter (cadena sin formato u objeto con format establecido en text, html, markdown o rtf; signature opcional como cadena o { mode: "typed" | "drawn", text?, dataUrl?, printDataUrl? }; PostalForm renderiza el PDF en el servidor)
    • form (payload de formulario de flujo de trabajo de una sola pieza descubierto a través de los endpoints de esquema de formularios automáticos; los campos de firma aceptan payloads de firma mecanografiada o dibujada cuando están presentes; los flujos de trabajo estatutarios de múltiples destinatarios están excluidos y siguen siendo solo web)
  • nombres y direcciones de remitente/destinatario (Loqate: *_address_type="Address" + *_address_id + *_address_text, o Manual: *_address_type="Manual" + *_address_manual con { line1, line2?, city, state?, zip, countryCode? }; countryCode por defecto es US; ambos modos de dirección aceptan solo los códigos de país admitidos para pago US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU y NL)

Opciones comunes:

  • double_sided (por defecto true)
  • color (por defecto false)
  • mail_class (standard, priority, express)
  • certified (por defecto false)
  • certified_return_receipt (por defecto false; agrega un acuse de recibo para Correo Certificado de EE. UU.; se ignora para correo registrado PinGen)
  • return_receipt_format (electronic por defecto, o physical para la tarjeta verde PS Form 3811 enviada por correo; requiere certified_return_receipt=true)
  • restricted_delivery (por defecto false; solicita Entrega Restringida de USPS solo para destinatario y requiere certified_return_receipt=true)
  • err_delivery (manual por defecto, o email para que PostalForm adquiera y envíe por correo electrónico el recibo electrónico firmado)
  • err_email (anulación opcional para entrega automática; por defecto es buyer_email cuando se omite)
  • signature_required (por defecto false; solicita firma en entrega de USPS; se ignora para postales o cuando mail_class="standard")
  • mailpiece_type (letter o postcard; por defecto letter)
  • postcard_size (4x6, 6x9, 11x6; requerido cuando mailpiece_type="postcard")

Los pedidos automáticos de postales usan los mismos endpoints y flujo de pago. Para postales, envía pdf como el PDF de postal compuesto final y establece mailpiece_type: "postcard" más postcard_size.

Requisitos del PDF de postal:

  • Usa un PDF de 2 páginas.
  • La página 1 es el lado del diseño.
  • La página 2 es el lado del envío. Puedes colocar diseño del reverso o un mensaje sin dirección allí, pero no coloques nombres de remitente/destinatario, direcciones de remite o entrega, indicios o datos de código de barras en el PDF. PostalForm completa el bloque de envío automáticamente.
  • Coincide con el lienzo de sangrado exacto para el tamaño seleccionado. La especificación canónica y las plantillas están en directrices de PDF de postales:
  • Las postales internacionales enrutadas por Lob requieren postcard_size="4x6" y una dirección de remite/devolución de EE. UU. PostalForm enruta postales internacionales más grandes o postales internacionales con direcciones de remite fuera de EE. UU. a PostGrid antes del envío al proveedor.

PostalForm normaliza las opciones de impresión de postales en el servidor a correo estándar, color completo, a doble cara y sin complementos de certificado/firma.

Endpoint MCP

  • https://postalform.com/mcp
  • Métodos: POST/GET/DELETE con el transporte HTTP transmisible
  • Sesiones: inicializa una vez, luego incluye el encabezado mcp-session-id en todas las solicitudes posteriores
  • Autenticación: no se requiere autenticación hoy (contacta a support@postalform.com para la lista de permitidos)
  • Transporte: payloads JSON-RPC sobre POST

Inicio rápido de integración

  1. Apunta tu cliente MCP a /mcp e inicializa una sesión.
  2. Elige direcciones: usa IDs de Loqate mediante postalform.search_addresses, o usa direcciones manuales con *_address_type="Manual" + *_address_manual (countryCode por defecto es US).
  3. Crea un borrador:
    • Texto de carta: postalform.create_letter_order_draft.
    • Formularios de flujo de trabajo: postalform.list_forms -> postalform.get_form_schema -> postalform.create_form_order_draft.
    • Carga de PDF: postalform.create_order_draft (parámetros de archivo, upload_token, URL de datos o URL HTTPS pública).
  4. Elige la ruta de pago:
    • Clientes compatibles con token de Stripe: obtén la aprobación del comprador y llama a complete_checkout con checkout_session.id, detalles del comprador y el token. De lo contrario, envía al comprador a checkout_url.
    • Clientes compatibles con MPP: elige payment_protocol: "mpp" y proporciona buyer_email al crear cualquier borrador. Revisa preview_url y price_usd, responde un desafío MPP, luego llama a postalform.pay_order solo con order_id y payment_authorization. create_machine_order sigue disponible para MPP y x402.
  5. Consulta el estado del pedido a medida que avanza el cumplimiento.
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const transport = new StreamableHTTPClientTransport(new URL('https://postalform.com/mcp'))
const client = new Client({ name: 'my-agent', version: '1.0.0' })

await client.connect(transport)
await client.listTools()

const draft = await client.callTool({
  name: 'postalform.create_letter_order_draft',
  arguments: {
    letter: {
      title: 'Demand for payment',
      body: 'Hello...\\n\\nThis is my letter body.\\n\\nSincerely,\\n',
      signature: 'Sender Example',
    },
    sender_name: 'Sender Example',
    sender_address_type: 'Manual',
    sender_address_manual: {
      line1: '123 Sender St',
      city: 'Springfield',
      state: 'IL',
      zip: '62701',
    },
    recipient_name: 'Recipient Example',
    recipient_address_type: 'Manual',
    recipient_address_manual: {
      line1: '456 Recipient Ave',
      city: 'Springfield',
      state: 'IL',
      zip: '62701',
    },
  },
})

console.log(draft.structuredContent?.checkout_url)

Pago y pago en línea

Pago externo (cualquier cliente MCP)

  • Usa checkout_url de postalform.create_order_draft para enviar a los clientes a la página de pago alojada de PostalForm.
  • Mejor opción predeterminada para clientes MCP de chat en navegador o cualquier flujo donde una persona deba revisar y pagar.
  • Abre la URL en un navegador (o window.openai.openExternal dentro de ChatGPT).
  • Consulta postalform.get_order_status para confirmar el pago y el cumplimiento.

Pago con token de Stripe (clientes agente compatibles)

  • Las herramientas de borrador devuelven un checkout_session de ACP que contiene el ID de pedido preparado y el total.
  • Después de que el comprador apruebe el pedido y el total, llama a complete_checkout con checkout_session_id, detalles del comprador y un Token de Pago Compartido de Stripe compatible (spt_..., provider=stripe). No se necesita reenviar el documento o la dirección.
  • PostalForm confirma el PaymentIntent existente. Los reintentos verifican su estado actual y reutilizan el mismo intent; las confirmaciones usan una clave de idempotencia estable de Stripe. Si no existe un intent, se guarda un intent no confirmado antes de cualquier intento de pago.
  • Reintenta una llamada interrumpida con el mismo ID de pago y token. Un resultado incierto es not_ready_for_payment con un mensaje informativo, no un rechazo confirmado. No crees otro pedido ni obtengas un token de reemplazo mientras el resultado sea incierto.
  • completed significa que el pago ha sido aceptado, incluida una autorización pendiente de captura. Sigue postalform.get_order_status para el pago y el cumplimiento; la finalización del pago no prueba el envío o la entrega. Los pagos en procesamiento devuelven not_ready_for_payment; la autenticación adicional devuelve requires_3ds; los pagos cancelados devuelven canceled. Un rechazo confirmado se puede reintentar con un token recién autorizado en el mismo intent.
  • Se debe verificar el soporte del cliente: estas herramientas no establecen que un asistente particular proporcione el token requerido o el formato de adjunto.
  • Los widgets de ChatGPT pueden usar window.openai.requestCheckout(checkout_session) cuando esté disponible. Los clientes sin pago con token compatible deben presentar checkout_url.

Pago automático directo (clientes MCP agénticos)

  • Para pagar un borrador preparado a través de MPP, establece payment_protocol: "mpp" y buyer_email en la creación y usa postalform.pay_order después de la aprobación. Usa postalform.create_machine_order para la interfaz combinada de pedidos automáticos MPP/x402.
  • Primero llámalo con payment_protocol="mpp" o "x402" y sin credencial de pago.
  • Para MPP, paga un desafío WWW-Authenticate: Payment ... devuelto con Link CLI, el servidor MCP de Link, Tempo o un cliente de tarjeta-MPP como mpp-card/client de Visa, luego reintenta los mismos argumentos de herramienta con payment_authorization.
  • Para x402, paga el desafío PAYMENT-REQUIRED devuelto con una billetera/cliente compatible con x402, luego reintenta los mismos argumentos de herramienta con payment_signature.
  • Reutiliza el mismo request_id y los campos de pedido al reintentar.

Herramientas

  • postalform.list_forms: Lista los flujos de trabajo de envío de una sola pieza compatibles disponibles para los agentes. Los flujos de trabajo coordinados de múltiples destinatarios según la ley siguen siendo solo web.
  • postalform.get_form_schema: Obtiene el esquema de un flujo de trabajo de envío de una sola pieza compatible (campos, dependencias, adjuntos). El esquema de máquina limita los archivos adjuntos en línea e informa attachments_max_total_size_mb (actualmente 12 MB combinados después de la decodificación base64). Puede incluir metadatos checkout_flow (home o forms_order) para el enrutamiento web de PostalForm; los clientes/agentes MCP pueden tratar esto como informativo.
  • postalform.create_letter_order_draft: Crea un borrador de pedido a partir de texto de carta (el servidor genera un PDF).
  • postalform.create_form_order_draft: Crea un borrador de pedido a partir de un envío JSON de flujo de trabajo de una sola pieza compatible; el servidor completa un formulario, genera una carta o ensambla los documentos de paquete requeridos según el esquema descubierto. Los adjuntos de flujo de trabajo en línea están limitados a 12 MB combinados después de la decodificación base64, incluso cuando el flujo de carga del navegador permite archivos más grandes.
  • postalform.create_pdf_upload: Crea una URL de carga de PDF de corta duración + upload_token para agentes que no pueden pasar parámetros de archivo. Cargue el PDF y luego llame a postalform.create_order_draft con pdf: { upload_token: "..." }.
  • postalform.search_addresses: Busca sugerencias de direcciones postales. Entrada: query (mínimo 3 caracteres), country_code opcional (por defecto US), container opcional (para profundizar en resultados de tipo Contenedor), target opcional. Salida: sugerencias de direcciones con ids/texto/tipo/país. Si el tipo es Contenedor, llame a la búsqueda nuevamente con container=id para obtener resultados de Dirección para borradores de pedidos.
  • postalform.create_order_draft: Crea un borrador de pedido y recibe una URL de pago. Entrada: pdf (objeto de archivo { download_url, file_id }, o { upload_token } de postalform.create_pdf_upload, o una URL data:application/pdf;base64,..., o una URL pública de descarga HTTPS), nombres de remitente/destinatario, y direcciones Loqate (*_address_type="Address" + *_address_id) o direcciones manuales (*_address_type="Manual" + *_address_manual, con countryCode opcional). Salida: order_id, price_usd, checkout_url, checkout_session.
  • postalform.create_machine_order: Crea y paga un solo PDF, carta, formulario de flujo de trabajo o campaña de cartas masivas usando MPP directo o x402. Para envíos masivos, envíe exactamente uno de bulk.csv_content o bulk.recipients (objetos de dirección JSON con merge_fields opcional), bulk.content_mode (pdf, text o html), y el pdf o bulk.template_text/bulk.template_html de nivel superior compartido correspondiente; omita los campos de destinatario de nivel superior, letter, form y las opciones de postal. Salida: detalles del desafío payment_required en la primera llamada, luego detalles pagados/liquidados después de reintentar con payment_authorization (MPP) o payment_signature (x402). El envío masivo también devuelve campaign_url, bulk.recipient_count, bulk.content_mode y price_usd combinado para revisión del comprador. Un reintento de criptopago pagado puede devolver brevemente settled_pending_webhook; consulte el estado y no pague nuevamente. Consulte el ejemplo de destinatario JSON.
  • postalform.pay_order: Obtiene un desafío o paga un borrador MPP existente de una sola pieza o una campaña masiva ordinaria por order_id. No se necesita reenvío de documentos o CSV. Al cambiar desde create_machine_order, omita payment_authorization primero para obtener el desafío de este endpoint, luego respóndalo con la credencial aprobada. Revise la vista previa del PDF único o el panel de la campaña masiva y el precio completo antes del pago.
  • complete_checkout: Paga una sesión de pago preparada con un token de pago de Stripe aprobado por el comprador. Entrada: checkout_session_id (order*id), buyer (first_name, last_name opcional, email), payment_data.token (token de pago compartido de Stripe, spt*...), provider=stripe. Salida: respuesta de la sesión de pago con estado y enlace permanente del pedido.
  • postalform.get_order_status: Obtiene los últimos detalles del estado del pedido. Entrada: order_id. Salida: found, is_paid, current_step, error, más el estado postal público almacenado, evidencia de seguimiento del transportista y disponibilidad de recibo electrónico de retorno (consulte el ejemplo de estado a continuación). Los pedidos masivos además devuelven campaign_url y bulk con ID de campaña, recuento de destinatarios, modo de contenido, estado de campaña y recuentos por estado en bulk.status_counts. Use el panel para destinatarios individuales; el estado de pago agregado no prueba la entrega.
  • postalform.ping: Verificación de salud del servidor MCP. Entrada: ninguna. Salida: carga útil de ping para verificaciones de conectividad.

Ejemplos de carga útil de herramientas

postalform.list_forms

Solicitud:

{
  "name": "postalform.list_forms",
  "arguments": { "q": "IRS", "limit": 10 }
}

postalform.get_form_schema

Solicitud:

{
  "name": "postalform.get_form_schema",
  "arguments": { "slug": "1099-nec" }
}

Nota: la respuesta puede incluir checkout_flow. Esto son metadatos de flujo de trabajo para el enrutamiento de pago web de PostalForm y no cambia la secuenciación de llamadas de herramientas MCP.

postalform.search_addresses

Solicitud:

{
  "name": "postalform.search_addresses",
  "arguments": {
    "target": "recipient",
    "query": "123 Main St"
  }
}

Respuesta:

{
  "structuredContent": {
    "view": "address_suggestions",
    "target": "recipient",
    "query": "123 Main St",
    "suggestions": [
      {
        "id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
        "text": "123 Main St, Springfield, IL 62701",
        "type": "Address",
        "description": ""
      }
    ]
  }
}

postalform.create_letter_order_draft

Solicitud:

{
  "name": "postalform.create_letter_order_draft",
  "arguments": {
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "letter": {
      "title": "Payment demand letter",
      "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n",
      "signature": "Sender Example"
    },
    "sender_name": "Sender Example",
    "sender_address_type": "Manual",
    "sender_address_manual": {
      "line1": "123 Sender St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    },
    "recipient_name": "Recipient Example",
    "recipient_address_type": "Manual",
    "recipient_address_manual": {
      "line1": "456 Recipient Ave",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    }
  }
}

postalform.create_form_order_draft

Solicitud:

{
  "name": "postalform.create_form_order_draft",
  "arguments": {
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "slug": "1099-nec",
    "fields": {
      "calendar_year": "2025",
      "payer_name": "Sender Example LLC",
      "payer_street_address": "123 Sender St",
      "payer_city_state_zip_phone": "Springfield, IL 62701, 217-555-0100",
      "payer_tin": "12-3456789",
      "recipient_tin": "123-45-6789",
      "recipient_name": "Contractor Example",
      "recipient_street_address": "456 Recipient Ave",
      "recipient_city_state_zip": "Springfield, IL 62701",
      "box_1_nonemployee_compensation": "1250.00"
    },
    "sender_name": "Sender Example",
    "sender_address_type": "Address",
    "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
    "sender_address_text": "123 Sender St, Springfield, IL 62701",
    "recipient_name": "Contractor Example",
    "recipient_address_type": "Manual",
    "recipient_address_manual": {
      "line1": "456 Recipient Ave",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    }
  }
}

postalform.create_pdf_upload

Solicitud:

{
  "name": "postalform.create_pdf_upload",
  "arguments": {
    "file_name": "letter.pdf",
    "content_type": "application/pdf",
    "content_length": 1234567
  }
}

Respuesta:

{
  "structuredContent": {
    "upload_url": "https://postalform.com/api/mcp/pdf-uploads/pfu_...",
    "upload_token": "pfu_...",
    "expires_at": "2026-01-17T12:00:00Z",
    "max_bytes": 104857600,
    "required_headers": {}
  }
}

Cargue el PDF con multipart/form-data usando el campo file (los alias pdf y pdfFile también se aceptan), luego pase upload_token a postalform.create_order_draft o postalform.create_machine_order. Deje que el codificador multipart del cliente HTTP genere el encabezado Content-Type, incluido su límite; no establezca un encabezado Content-Type: multipart/form-data simple cuando use FormData o curl -F.

postalform.create_order_draft

Nota: pdf acepta un objeto de archivo, un upload_token o una URL de datos base64 (data:application/pdf;base64,...). Una URL de descarga puede usar cualquier host HTTPS público, incluidas las URL de adjuntos firmados de Muse u otros clientes; debe funcionar sin encabezados de autenticación adicionales. Cada redirección también debe usar HTTPS y resolverse a direcciones públicas. Las direcciones privadas/internas están bloqueadas; las descargas están limitadas a 100 MB, cinco redirecciones y 20 segundos. Solicitud:

{
  "name": "postalform.create_order_draft",
  "arguments": {
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "pdf": { "upload_token": "pfu_..." },
    "file_name": "letter.pdf",
    "sender_name": "Sender Example",
    "sender_address_id": "US|LP|Pz0_Qj4_bGJg|16074807|13_ENG",
    "sender_address_type": "Address",
    "sender_address_text": "123 Sender St, Springfield, IL 62701",
    "recipient_name": "Recipient Example",
    "recipient_address_id": "US|LP|Pz0_Qj4_bGJg|199825276|99_ENG",
    "recipient_address_type": "Address",
    "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
    "double_sided": true,
    "color": false
  }
}

Respuesta:

{
  "structuredContent": {
    "view": "order_draft",
    "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "page_count": 2,
    "price_usd": 2.99,
    "checkout_url": "https://postalform.com/payment?orderId=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "sender_name": "Sender Example",
    "sender_address_text": "123 Sender St, Springfield, IL 62701",
    "recipient_name": "Recipient Example",
    "recipient_address_text": "456 Recipient Ave, Springfield, IL 62701",
    "checkout_session": {
      "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
      "payment_provider": {
        "provider": "stripe",
        "merchant_id": "profile_123",
        "supported_payment_methods": ["card", "apple_pay", "google_pay"]
      },
      "status": "ready_for_payment",
      "currency": "usd",
      "line_items": [
        {
          "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
          "item": { "id": "postalform_mail_pdf", "quantity": 1 },
          "base_amount": 299,
          "discount": 0,
          "subtotal": 299,
          "tax": 0,
          "total": 299
        }
      ],
      "totals": [
        { "type": "items_base_amount", "display_text": "Items", "amount": 299 },
        { "type": "subtotal", "display_text": "Subtotal", "amount": 299 },
        { "type": "tax", "display_text": "Tax", "amount": 0 },
        { "type": "total", "display_text": "Total", "amount": 299 }
      ],
      "links": [
        { "type": "terms_of_use", "value": "https://postalform.com/terms" },
        { "type": "privacy_policy", "value": "https://postalform.com/privacy" }
      ],
      "payment_mode": "test"
    }
  }
}

MPP para cualquier borrador

postalform.create_order_draft, postalform.create_letter_order_draft y postalform.create_form_order_draft aceptan:

{
  "payment_protocol": "mpp",
  "buyer_email": "buyer@example.com",
  "buyer_name": "Buyer Example"
}

Incluya esos campos junto con los argumentos normales de PDF, carta o formulario y un request_id estable. buyer_email es obligatorio para MPP; buyer_name por defecto es el remitente. La respuesta tiene payment_protocol: "mpp", un respaldo checkout_url del mismo pedido, preview_url, price_usd y payment que contiene el estado del pedido, el endpoint de pago y los desafíos MPP (payment.payment.www_authenticate). La creación del borrador no envía ningún pago. Omitir payment_protocol conserva el pago alojado y complete_checkout.

Después de la revisión y aprobación del comprador, responda un desafío devuelto y pague el mismo pedido preparado:

{
  "name": "postalform.pay_order",
  "arguments": {
    "order_id": "11111111-1111-4111-8111-111111111111",
    "payment_authorization": "Payment <credential>"
  }
}

Omita payment_authorization para actualizar el desafío. Link CLI u otro cliente HTTP MPP puede hacer POST de {} a https://postalform.com/api/machine/mpp/orders/{order_id}/pay. Una llamada no pagada devuelve HTTP 402 con WWW-Authenticate; reintente esa misma URL y cuerpo con Authorization: Payment .... El pago exitoso devuelve el estado del pedido y Payment-Receipt. Reutilice el mismo ID de pedido y credencial después de una respuesta interrumpida. Los reintentos de paid y settled_pending_webhook no envían otro pago; consulte el estado en su lugar. El documento y las direcciones nunca se reenvían. El protocolo de solicitud original sigue siendo parte del contrato de idempotencia. Los pedidos MPP/x402 pueden seleccionar su pago alojado devuelto antes de enviar una credencial de pago; un borrador existente solo alojado no se puede convertir a MPP llamando a pay_order.

postalform.create_machine_order

Primera llamada para un desafío de pago MPP/Link:

{
  "name": "postalform.create_machine_order",
  "arguments": {
    "payment_protocol": "mpp",
    "request_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "buyer_name": "Agent Owner",
    "buyer_email": "owner@example.com",
    "letter": {
      "title": "Payment demand letter",
      "body": "Hello,\\n\\nThis is the letter body.\\n\\nSincerely,\\n"
    },
    "sender_name": "Sender Example",
    "sender_address_type": "Manual",
    "sender_address_manual": {
      "line1": "123 Sender St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    },
    "recipient_name": "Recipient Example",
    "recipient_address_type": "Manual",
    "recipient_address_manual": {
      "line1": "456 Recipient Ave",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701"
    }
  }
}

Forma de la respuesta:

{
  "structuredContent": {
    "view": "machine_order",
    "protocol": "mpp",
    "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "status": "payment_required",
    "payment": {
      "www_authenticate": ["Payment ..."],
      "retry_header": "Authorization",
      "retry_header_value": "Payment ..."
    }
  }
}

Después de que Link CLI o Link MCP devuelva la credencial MPP pagada, reintente los mismos argumentos con:

{
  "payment_authorization": "Payment ..."
}

Para x402, establezca payment_protocol en x402; la primera respuesta contiene payment.payment_required_header y el reintento usa payment_signature.

complete_checkout

Solicitud:

{
  "name": "complete_checkout",
  "arguments": {
    "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "buyer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    },
    "payment_data": {
      "token": "spt_test_123",
      "provider": "stripe"
    }
  }
}

Respuesta:

{
  "structuredContent": {
    "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "buyer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com"
    },
    "status": "completed",
    "currency": "usd",
    "line_items": [
      {
        "id": "line_item_8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
        "item": { "id": "postalform_mail_pdf", "quantity": 1 },
        "base_amount": 299,
        "discount": 0,
        "subtotal": 299,
        "tax": 0,
        "total": 299
      }
    ],
    "fulfillment_options": [
      {
        "type": "shipping",
        "id": "postalform_standard",
        "title": "First Class mail",
        "subtitle": "Mailed via postal carrier",
        "carrier": "Postal carrier",
        "carrier_info": "PostalForm print-and-mail provider",
        "earliest_delivery_time": "2026-07-01T00:00:00.000Z",
        "latest_delivery_time": "2026-07-06T00:00:00.000Z",
        "subtotal": 0,
        "tax": 0,
        "total": 0
      }
    ],
    "fulfillment_option_id": "postalform_standard",
    "totals": [
      { "type": "items_base_amount", "display_text": "Items", "amount": 299 },
      { "type": "subtotal", "display_text": "Subtotal", "amount": 299 },
      { "type": "tax", "display_text": "Tax", "amount": 0 },
      { "type": "total", "display_text": "Total", "amount": 299 }
    ],
    "order": {
      "id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
      "checkout_session_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
      "permalink_url": "https://postalform.com/order/complete?order_id=8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b"
    },
    "messages": [],
    "links": [
      { "type": "terms_of_use", "value": "https://postalform.com/terms" },
      { "type": "privacy_policy", "value": "https://postalform.com/privacy" }
    ]
  }
}

postalform.get_order_status

Respuesta:

{
  "structuredContent": {
    "view": "order_status",
    "found": true,
    "order_id": "8c1a1b58-2c8f-4f4f-9c46-2c1ac32d7a1b",
    "is_paid": true,
    "current_step": "letter_created",
    "mailing_status": "processed",
    "mailing_status_normalized": "processed_for_delivery",
    "tracking_number": "9400000000000000000000",
    "carrier": "USPS",
    "delivery_status": "delivered",
    "delivery_status_detail": "Delivered to authorized agent",
    "signed_by": "Authorized agent",
    "tracking_events": [],
    "estimated_delivery_at": null,
    "tracking_updated_at": "2026-09-05T12:00:00Z",
    "electronic_return_receipt": {
      "requested": true,
      "status": "manual",
      "document_available": false,
      "emailed_at": null
    }
  }
}

Las lecturas de estado usan la misma evidencia postal pública almacenada que la página de finalización del pedido. mailing_status / mailing_status_normalized describen el cumplimiento; delivery_status y tracking_events informan la evidencia disponible del transportista. Un paso interno como letter_created, o un número de seguimiento solo, no prueba la aceptación o entrega del transportista. Los campos faltantes son null, los eventos faltantes son [] y los pedidos desconocidos devuelven found=false sin campos postales. Estos campos también admiten transportistas no estadounidenses; no asuma que cada número de seguimiento pertenece a USPS.

tracking_events contiene como máximo los últimos 50 eventos almacenados, con status, statusNormalized, statusDetail, message, occurredAt y location (postalCode, city, state, label). Los eventos se sanean como la página de finalización. tracking_updated_at es la última marca de tiempo del webhook del proveedor registrada, no una garantía de una consulta reciente al transportista. Las estimaciones pueden cambiar.

electronic_return_receipt.requested significa que se seleccionó un recibo electrónico. Su status es manual, pending, sent o failed (o null cuando no se solicitó); sent y emailed_at se refieren a PostalForm enviando el recibo por correo electrónico. document_available significa que PostalForm tiene un documento de recibo almacenado. Un valor falso no prueba que USPS no haya emitido un recibo, especialmente con recuperación manual. Los recibos físicos de retorno no cuentan como recibos electrónicos. Esta herramienta no descarga/adquiere recibos ni expone sus rutas de almacenamiento, y la consulta nunca cobra, paga o inicia el envío.

Ejemplo de respuesta de error

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "recipient_address_manual is required when recipient_address_type is Manual."
    }
  ]
}

Notas de integración

  • Idempotencia: use request_id en las herramientas de creación de borradores (postalform.create_order_draft, postalform.create_letter_order_draft, postalform.create_form_order_draft) y en postalform.create_machine_order. Reutilice el mismo valor y los mismos campos de pedido en los reintentos. El servidor devolverá el borrador/pedido existente.
  • Errores: las llamadas a herramientas que fallan la validación devuelven isError=true con un mensaje legible. Para el pago con token, complete_checkout también puede devolver mensajes ACP con códigos de error como payment_declined o requires_3ds.
  • Respaldo de pago instantáneo: si window.openai.requestCheckout no está disponible o checkout_session.payment_provider carece de merchant_id, use checkout_url en su lugar.
  • Pasos de estado del pedido: payment_received, receiver_address_verified, sender_address_verified, pdf_normalized, letter_created, email_sent, canceled, refunded, abandoned.

Límites y requisitos

  • Todos los pedidos se imprimen desde PDFs. Para postalform.create_order_draft usted proporciona el PDF. Para postalform.create_letter_order_draft y postalform.create_form_order_draft, PostalForm genera el PDF en el servidor. Los PDFs se sanitizan antes de imprimirse.
  • Los form.attachments en línea son JSON en base64 y pueden totalizar como máximo 12 MB después de decodificarse. Siga los valores de allowed_types, max_files y max_size_mb (con tope de máquina) de cada adjunto según el esquema del flujo de trabajo.
  • Para un flujo de trabajo con recipient.mode="user", el nombre/dirección del destinatario de nivel superior controla el sobre. Manténgalo alineado con los campos de rol de dirección del destinatario en form.fields; esos campos no anulan la dirección de orden de máquina de nivel superior.
  • Máximo 199 páginas y 100 MB por archivo.
  • download_url acepta cualquier host HTTPS público y parámetros de consulta firmados, sin lista de permitidos del proveedor. La URL y cada redirección deben resolverse a direcciones públicas y funcionar sin encabezados de autenticación adicionales. Si el cliente no puede exponer una URL descargable, use postalform.create_pdf_upload para una upload_token o una URL de data:application/pdf;base64,.... Para cartas generadas, pase el texto directamente a postalform.create_letter_order_draft; no se necesita carga.
  • Los países de las direcciones se establecen por defecto en US cuando se omiten. Use los IDs de dirección de Loqate devueltos por postalform.search_addresses (el prefijo del ID incluye el país), o use entrada manual de dirección con *_address_type="Manual" y *_address_manual.countryCode. Los pedidos de máquina aplican la misma lista de países que el selector de direcciones del checkout: US, CA, AT, BE, CH, DE, ES, FR, GB, IN, LU y NL; los códigos no admitidos o inválidos se rechazan. Los CSV masivos aceptan la misma lista a través de country, country_code o countrycode.
  • Las sugerencias de dirección pueden incluir type="Container" (edificios/complejos). Llame a postalform.search_addresses nuevamente con container=<id> y una consulta refinada (suite, unidad, apartado postal) para obtener resultados de type="Address". Solo type="Address" (no Container) es válido para borradores de pedidos basados en Loqate.

Seguridad, permisos y límites de velocidad de MCP

Trate PostalForm como una herramienta de acción en el mundo real porque puede crear borradores de correo y, en flujos de pago de máquina, realizar pedidos de correo pagados después de un desafío de pago aprobado por el propietario. En clientes de chat, configure el servidor con require_approval: "always" y requiera revisión humana antes de enviar documentos, direcciones o credenciales de pago del usuario.

Herramienta o flujoAlcanceEfectos secundarios y límites
postalform.list_forms y postalform.get_form_schemaLee el catálogo de formularios publicados y los metadatos del esquemaSin pedido, carga de archivo, pago o efecto secundario de correo
postalform.search_addressesBusca sugerencias de dirección para campos de remitente o destinatarioLlama al proveedor de búsqueda de direcciones y tiene límite de velocidad por IP. Los valores predeterminados son 120 búsquedas por minuto y 3,000 por día. No crea un pedido ni un pago
postalform.create_pdf_uploadCrea una URL de carga de corta duración para un PDFSolo token de carga. El archivo aún debe adjuntarse a una llamada de borrador posterior. Las cargas están limitadas por los límites documentados de páginas y tamaño de archivo
postalform.create_order_draftCrea un borrador PDF para checkout alojado o MPPCrea un borrador no pagado, devolviendo checkout alojado o un desafío MPP. No se imprime ni se envía correo antes del pago
postalform.create_letter_order_draftRenderiza texto de carta en un borrador para checkout alojado o MPPCrea un borrador no pagado, devolviendo checkout alojado o un desafío MPP. No se imprime ni se envía correo antes del pago
postalform.create_form_order_draftCompleta un formulario de flujo de trabajo para checkout alojado o MPPCrea un borrador no pagado, devolviendo checkout alojado o un desafío MPP. No se imprime ni se envía correo antes del pago
postalform.pay_orderDevuelve un desafío MPP o paga un pedido MPP preparadoPase solo order_id y el payment_authorization aprobado por el comprador; reutilice ese ID en reintentos.
postalform.create_machine_orderCrea o paga un pedido de máquina directo MPP/x402Úselo solo en tiempos de ejecución autónomos autorizados con controles de gasto. La llamada no pagada devuelve un desafío de pago; el reintento pagado debe incluir la autorización MPP o la firma de pago x402
complete_checkoutPaga un checkout preparado con un token de Stripe compatibleÚselo solo después de que el comprador confirme el checkout con un token de pago compartido de Stripe
postalform.get_order_status y postalform.pingLee el estado del pedido o el estado de saludSin creación de pedido, pago o efecto secundario de correo

Las herramientas de creación de borradores y las herramientas de pedido de máquina directo también están limitadas por la limitación de pedidos no pagados. El límite predeterminado de creación de pedidos no pagados es de 10 intentos por hora por IP de cliente. En los límites de velocidad, las herramientas MCP devuelven una respuesta de error y las llamadas de envoltura HTTP pueden devolver 429.

Los escáneres de seguridad deben tratar el checkout alojado como la ruta segura predeterminada: la herramienta puede crear un borrador, pero el cliente aún revisa el PDF, las direcciones, el precio y las opciones de envío antes del pago. El pago directo de máquina debe permanecer detrás de la aprobación explícita del propietario, límites de gasto, valores idempotentes de request_id y un paso de revisión de vista previa cuando preview_url esté presente.

Fuentes de protocolo y plataforma

Preguntas frecuentes

  • ¿Es PostalForm una API de correo? Sí. PostalForm expone endpoints REST de pedidos de máquina, un catálogo OpenAPI y un servidor MCP remoto para crear borradores de correo físico, cotizaciones, pedidos de pago de máquina y consultas de estado de cumplimiento.
  • ¿Puede un servidor MCP enviar correo postal real? Sí, pero PostalForm separa la creación de borradores del envío pagado. Las herramientas de borrador preparan pedidos no pagados para checkout alojado o pago MPP opcional por ID de pedido. Los pagos requieren aprobación del comprador y la credencial adecuada.
  • ¿Cuál es el valor predeterminado más seguro para ChatGPT, Claude, Gemini, Cursor o Codex? Use el endpoint MCP remoto en https://postalform.com/mcp,, configure la aprobación para efectos secundarios de correo, cree un borrador de checkout alojado y deje que el usuario revise el PDF, las direcciones, el precio y las opciones antes del pago.
  • ¿Puede un agente pagar correo con x402 o MPP? Sí. PostalForm admite flujos de pago de máquina directo para tiempos de ejecución autónomos autorizados. La llamada no pagada devuelve un desafío de pago, y el reintento pagado debe incluir la firma de pago x402 o la autorización MPP.
  • ¿Necesito una clave de API de PostalForm? No para el endpoint MCP público actual o el flujo de pago de máquina. Algunos despliegues de alto volumen, sensibles a abuso o con lista de permitidos pueden requerir coordinación con support@postalform.com.
  • ¿Puedo cargar PDFs a través de la API o MCP? Sí. Use la herramienta de carga de PDF para crear un token de carga de corta duración, pase una URL de descarga HTTPS pública, use una URL de adjunto de ChatGPT o proporcione una URL de datos donde sea compatible.
  • ¿Cómo mantengo seguros los efectos secundarios del correo? Trate el correo físico como una acción del mundo real. Use checkout alojado por defecto, requiera aprobación humana, establezca límites de gasto, reutilice IDs de solicitud de idempotencia y revise las URLs de vista previa antes del pago cuando estén presentes.