PostalForm

Create or pay a machine order

postalform.create_machine_order

Create a single PDF, letter, workflow-form order, or bulk letter campaign and pay through MPP or x402 after buyer approval. For bulk, provide exactly one of bulk.csv_content or bulk.recipients (JSON address objects with optional merge_fields), plus a shared PDF or text/HTML template. Omit top-level recipient fields and review campaign_url, recipient count and total. Bulk MPP orders can also use postalform.pay_order after fetching its challenge. The unpaid response also includes checkout_url and status_url for this same order. Without an available compatible wallet, give the buyer checkout_url and poll status_url; never recreate the order to change payment paths. Single-recipient clients with a Stripe shared payment token can instead use a draft tool followed by complete_checkout; other clients should present the hosted checkout URL.

Input Schema

Name	Required	Description
`pdf`	No	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`	No	Bulk letter campaign: exactly one of csv_content or recipients (JSON list), plus shared PDF or text/HTML template. Omit single-recipient fields, letter, form, and postcard options. color and double_sided apply to every mailpiece.
`form`	No	Workflow form payload from postalform.get_form_schema. Provide exactly one of pdf, letter, or form.
`color`	No
`letter`	No	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`	No
`file_name`	No
`buyer_name`	Yes	Buyer name for receipts.
`mail_class`	No
`request_id`	No	Idempotency key. Reuse the same value and same order fields after a payment challenge.
`buyer_email`	Yes	Buyer email for receipts.
`sender_name`	Yes
`double_sided`	No
`postcard_size`	No
`mailpiece_type`	No
`recipient_name`	No	Required for a single recipient. Omit when bulk supplies the recipient list.
`payment_protocol`	No	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`	No	x402 retry value after paying the PAYMENT-REQUIRED challenge.
`sender_address_id`	No
`signature_required`	No
`sender_address_text`	No
`sender_address_type`	No
`recipient_address_id`	No
`payment_authorization`	No	MPP retry value after paying with Link CLI/Link MCP. Pass the full Authorization header value, usually "Payment ...".
`sender_address_manual`	No
`recipient_address_text`	No
`recipient_address_type`	No
`certified_return_receipt`	No
`recipient_address_manual`	No

Output Schema

Name	Required	Description	Default
`bulk`	No
`view`	Yes
`status`	Yes
`is_paid`	Yes
`paid_at`	Yes
`payment`	No
`currency`	Yes
`endpoint`	Yes
`order_id`	Yes
`protocol`	Yes
`next_step`	No
`price_usd`	Yes
`page_count`	No
`request_id`	Yes
`status_url`	No
`next_action`	No
`preview_url`	No
`campaign_url`	No
`checkout_url`	No
`postcard_size`	Yes
`mailpiece_type`	Yes
`payment_status`	Yes
`payment_options`	No
`order_complete_url`	Yes
`payment_status_label`	Yes
`payment_status_description`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedNov 5, 2026

addedOutput schema / properties / paid_at

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

addedOutput schema / properties / payment_status_description
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / payment_status_label
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "view",
-  "protocol",
-  "order_id",
-  "request_id",
-  "endpoint",
-  "status",
-  "payment_status",
-  "is_paid",
-  "price_usd",
-  "currency",
-  "mailpiece_type",
-  "postcard_size",
-  "order_complete_url"
-]New value: +[
+  "view",
+  "protocol",
+  "order_id",
+  "request_id",
+  "endpoint",
+  "status",
+  "payment_status",
+  "payment_status_label",
+  "payment_status_description",
+  "paid_at",
+  "is_paid",
+  "price_usd",
+  "currency",
+  "mailpiece_type",
+  "postcard_size",
+  "order_complete_url"
+]

Changed2 schema fields changedOct 15, 2026
- changedInput schema / properties / recipient_name / maxLength
```
Previous value: -256New value: +255
```
- changedInput schema / properties / sender_name / maxLength
```
Previous value: -256New value: +255
```
First observedSep 27, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description must add process context. It does: buyer approval precedes payment, the unpaid response carries checkout_url and status_url, bulk MPP can complete via pay_order after a challenge, and campaign_url/recipient count/total should be reviewed before paying. It does not spell out what a failed or declined payment leaves behind, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is front-loaded with purpose, then bulk mechanics, then payment routing, and almost every sentence carries a decision rule. It is dense but slightly overpacked, and it restates constraints (exactly one of recipients/csv_content) that also appear in the schema's bulk description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 29-parameter order-creation tool with an output schema, the description covers the decisions an agent actually needs: which content mode, how bulk differs from single, how payment handshakes and retries work, and what to do when no wallet is available. The remaining undescribed parameters are optional fulfillment options that the schema already enumerates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 38% across 29 parameters, so the description must carry meaning, and it does explain the mutually exclusive bulk.recipients vs bulk.csv_content choice, merge_fields template semantics, and omitting top-level recipient fields in bulk mode. However, many parameters remain unexplained in both places — color, double_sided, certified, certified_return_receipt, mail_class, postcard_size, mailpiece_type, signature_required, and the sender/recipient address_* family — so compensation is partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb (Create ... and pay) with an enumerated resource set (single PDF, letter, workflow-form order, bulk letter campaign) and names the payment protocols. It also distinguishes itself from siblings by naming postalform.pay_order and the draft-then-complete_checkout path, so an agent can tell which tool to reach for.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit branch routing: bulk requires exactly one of bulk.csv_content or bulk.recipients plus a shared PDF or template; single-recipient Stripe-SPT clients should use a draft tool plus complete_checkout; clients without a compatible wallet should hand over checkout_url and poll status_url rather than recreating the order. It also states a negative rule (never recreate the order to change payment paths), which is exactly the kind of exclusion that prevents wrong calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All PostalForm tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?