Plain letter API reference

PostalForm uses the same workflow definition for this API reference and its guided browser form. Fetch the live schema, collect the active required fields and attachments, and validate the completed request. Review the generated PDF, resolved recipient, mailing service and price with the owner before authorizing payment.

Send a top-level form instead of pdf or letter; those three document sources are mutually exclusive. Workflow forms are letters, not postcards. The machine envelope requires buyer, sender and recipient fields. For predefined or computed recipients, the server binds the final recipient to the workflow rules. Inspect the resolved recipient returned by validation; do not substitute a convenient office address.

The template below is structural, not ready to submit: replace every placeholder, complete the active fields, omit unused optional attachments, and use the field options and visibility rules in the schema. Empty strings and unchecked checkboxes are not user answers. Never infer a signature, legal eligibility, factual declaration or consent from a default value.

{
  "request_id": "<new UUID; preserve on retry>",
  "buyer_name": "<buyer name>",
  "buyer_email": "<buyer email>",
  "sender_name": "<sender name>",
  "sender_address_type": "Manual",
  "sender_address_manual": {
    "line1": "<street address>",
    "city": "<city>",
    "state": "<state or region>",
    "zip": "<postal code>",
    "countryCode": "US"
  },
  "recipient_name": "<confirmed recipient name>",
  "recipient_address_type": "Manual",
  "recipient_address_manual": {
    "line1": "<street address>",
    "city": "<city>",
    "state": "<state or region>",
    "zip": "<postal code>",
    "countryCode": "US"
  },
  "mail_class": "standard",
  "double_sided": true,
  "color": false,
  "certified": false,
  "form": {
    "slug": "plain-letter",
    "fields": {
      "letter_body": "",
      "letter_signature": "",
      "handwritten_note": false,
      "handwritten_message": "",
      "handwritten_style": "",
      "handwritten_seed": "",
      "handwritten_custom_card": false,
      "handwritten_custom_card_name": "",
      "handwritten_front_image_url": "",
      "handwritten_front_full_bleed": false,
      "handwritten_front_image_zoom": "",
      "handwritten_back_image_url": "",
      "handwritten_inside_image_url": "",
      "handwritten_back_full_bleed": false,
      "handwritten_back_image_zoom": ""
    },
    "attachments": [
      {
        "id": "supporting_attachments",
        "file_name": "<filename>",
        "base64": "<base64 file content>"
      }
    ]
  }
}

Compound fields use nested objects keyed by subfield ID. Evaluate group and field visibility before deciding which fields are active. Conditional requirements, validation rules, recipient rules, attachment formats and compliance policies are preserved in the complete schema below.

{
  "schema_version": 1,
  "workflow_version": 1,
  "slug": "plain-letter",
  "name": "Plain letter",
  "description": "Write a letter online, preview the generated PDF, add an optional signature or attachments, and mail it as physical postal mail.",
  "agent_summary": "Use this workflow to generate a dynamically paginated plain-letter PDF from typed letter content, preview it, and mail it as physical postal mail.",
  "form_summary": "Use the plain letter workflow when you need to write a letter in a browser and have it mailed as physical postal mail without printing, stamps, or envelopes. PostalForm turns typed text into a print-ready PDF, lets you add an optional signature or attachments, shows the exact preview, then collects sender and recipient addresses before checkout.",
  "data_collected": [
    "Letter body text and formatting",
    "Handwritten card message and card artwork URLs when handwritten mode is selected",
    "Signature line (optional)",
    "Supporting attachments (optional)"
  ],
  "topics": [
    "Letters",
    "General correspondence",
    "Personal letters",
    "Mail a letter online",
    "Letter writing"
  ],
  "category": "plain_letter",
  "publish_state": "published",
  "llms": true,
  "indexable": true,
  "certified_mail": "optional",
  "recipient": {
    "mode": "user"
  },
  "checkout_flow": "home",
  "published_at": "2026-02-21",
  "updated_at": "2026-05-31",
  "groups": [
    {
      "id": "step-1-letter",
      "label": "Letter content",
      "description": "Write your letter below. You’ll preview the exact printed PDF before you pay, then we print and mail it for you.",
      "depends_on": []
    }
  ],
  "fields": [
    {
      "id": "letter_body",
      "label": "Letter body",
      "type": "textarea",
      "required": true,
      "meta_class": "letter_body",
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_note",
        "operator": "falsy"
      },
      "depends_on": [
        "handwritten_note"
      ],
      "validation": {
        "maxLength": 20000
      },
      "compound": null
    },
    {
      "id": "letter_signature",
      "label": "Signature (optional)",
      "type": "signature",
      "required": false,
      "meta_class": "letter_signature",
      "ui_width": "half",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_note",
        "operator": "falsy"
      },
      "depends_on": [
        "handwritten_note"
      ],
      "validation": {
        "maxLength": 2000
      },
      "compound": null
    },
    {
      "id": "handwritten_note",
      "label": "Optional: send as a real handwritten card (+$5)",
      "type": "checkbox",
      "required": false,
      "meta_class": "toggle",
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "depends_on": [],
      "compound": null
    },
    {
      "id": "handwritten_message",
      "label": "Handwritten message",
      "type": "textarea",
      "required": true,
      "meta_class": null,
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_note",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_note"
      ],
      "validation": {
        "maxLength": 400
      },
      "compound": null
    },
    {
      "id": "handwritten_style",
      "label": "Choose your handwriting",
      "type": "select",
      "required": true,
      "meta_class": null,
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_note",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_note"
      ],
      "compound": null
    },
    {
      "id": "handwritten_seed",
      "label": "Handwriting variation",
      "type": "text",
      "required": false,
      "meta_class": "handwriting_seed",
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_note",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_note"
      ],
      "compound": null
    },
    {
      "id": "handwritten_custom_card",
      "label": "Use custom card artwork",
      "type": "checkbox",
      "required": false,
      "meta_class": "toggle",
      "ui_width": "half",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_note",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_note"
      ],
      "compound": null
    },
    {
      "id": "handwritten_custom_card_name",
      "label": "Custom card name",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "validation": {
        "maxLength": 120
      },
      "compound": null
    },
    {
      "id": "handwritten_front_image_url",
      "label": "Front image URL",
      "type": "text",
      "required": true,
      "meta_class": null,
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "validation": {
        "maxLength": 1000,
        "pattern": "^https?://.+"
      },
      "compound": null
    },
    {
      "id": "handwritten_front_full_bleed",
      "label": "Front image full bleed",
      "type": "checkbox",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "compound": null
    },
    {
      "id": "handwritten_front_image_zoom",
      "label": "Front image zoom",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "validation": {
        "maxLength": 4,
        "pattern": "^\\d+(\\.\\d{1,2})?$"
      },
      "compound": null
    },
    {
      "id": "handwritten_back_image_url",
      "label": "Back image URL (optional)",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "validation": {
        "maxLength": 1000,
        "pattern": "^https?://.*"
      },
      "compound": null
    },
    {
      "id": "handwritten_inside_image_url",
      "label": "Inside image URL (optional)",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "full",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "validation": {
        "maxLength": 1000,
        "pattern": "^https?://.*"
      },
      "compound": null
    },
    {
      "id": "handwritten_back_full_bleed",
      "label": "Back image full bleed",
      "type": "checkbox",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "compound": null
    },
    {
      "id": "handwritten_back_image_zoom",
      "label": "Back image zoom",
      "type": "text",
      "required": false,
      "meta_class": null,
      "ui_width": "half",
      "group_id": "step-1-letter",
      "choice_group": null,
      "choice_label": null,
      "visibility": {
        "fieldId": "handwritten_custom_card",
        "operator": "truthy"
      },
      "depends_on": [
        "handwritten_custom_card"
      ],
      "validation": {
        "maxLength": 4,
        "pattern": "^\\d+(\\.\\d{1,2})?$"
      },
      "compound": null
    }
  ],
  "attachments": [
    {
      "id": "supporting_attachments",
      "label": "Supporting attachments (optional)",
      "required": false,
      "instructions": "Upload supporting files to append behind your letter. PDF, images, DOCX, HTML, Markdown, RTF, and text files can be converted for the print preview.",
      "allowed_types": [
        "pdf",
        "jpg",
        "jpeg",
        "png",
        "txt",
        "text",
        "md",
        "markdown",
        "mdown",
        "mkd",
        "html",
        "htm",
        "rtf",
        "rtx"
      ],
      "max_files": 10,
      "max_size_mb": 12
    }
  ],
  "attachments_max_total_size_mb": 12,
  "machine_submission": {
    "payload_property": "form",
    "create_paths": {
      "x402": "/api/machine/orders",
      "mpp": "/api/machine/mpp/orders"
    }
  }
}

Validation does not mail the document. For a human checkout, use MCP postalform.create_form_order_draft and present the returned preview, total and checkout URL. Machine API clients must handle the returned MPP or x402 challenge only within owner-approved spending authority. Preserve request_id and the exact payload for retries; changing the content requires a new request ID. After an uncertain payment, retrieve order status before creating another order. Provider handoff is not USPS delivery.