Send a physical letter from code in 5 minutes

Use the API when your product needs to generate a mailing draft, preview the packet, collect human review and payment, then follow the mail lifecycle. Use test mode while developing: it creates a watermarked preview PDF, fake quote, and fake tracking events without charging or submitting to a print provider.

• Decide whether your first draft is plain text, a PDF URL, or a guided form workflow.
• Generate a stable Idempotency-Key for every create request.
• Keep hosted checkout as the default path for production mail unless you are deliberately using a machine-payment flow.
• Store the returned order or draft ID so retries and status checks do not create duplicate mail.

curl -X POST https://www.postalform.com/v1/test/mail_drafts \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c9f7b7a-9e7d-4a85-96d8-b2d2336a6b1f" \
  -d '{
    "letter_text": "Hello from PostalForm test mode.",
    "sender": {
      "name": "Avery Sender"
    },
    "recipient": {
      "name": "Riley Recipient"
    }
  }'

The response includes a preview_pdf_url, a fake zero-dollar quote, and fake tracking events. The preview PDF is watermarked TEST MODE.

curl -X POST https://www.postalform.com/v1/test/mail_drafts \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 48a26971-efde-42ef-bb3f-f1d29b4b398c" \
  -d '{
    "pdf_url": "https://example.com/packet.pdf",
    "mail_class": "certified"
  }'

Production draft creation should still route to a human review and hosted checkout step before PostalForm submits anything to a provider.

curl -X POST https://www.postalform.com/v1/test/form_drafts \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 08f54053-0d06-4d4a-b6c5-3391ac45fbbf" \
  -d '{
    "workflow_slug": "debt-validation-packets",
    "answers": {
      "collector_name": "Example Debt Collector"
    }
  }'

Use this shape for packet workflows where the user answers questions and PostalForm generates a reviewable PDF before checkout.

curl https://www.postalform.com/v1/test/orders/test_mail_example

Test status responses include fake lifecycle events. Production status checks return the real mail order state after checkout and provider submission.

Send Idempotency-Key: <uuid> on create requests. Agents, queue workers, and retrying integrations should reuse the same key for the same intended mailing so network retries do not duplicate a draft or a real order.

• Generates a watermarked preview PDF.
• Returns a fake quote and fake tracking events.
• Never submits to a print provider.
• Never charges real money.
• Keeps the response shape close to production integrations.

Production integrations should be ready to receive lifecycle events such as mail.order.created, mail.order.paid, mail.order.submitted, mail.order.provider_accepted, mail.order.provider_rejected, mail.order.mailed, mail.order.tracking_updated, mail.order.delivery_attempted, mail.order.delivered, mail.order.failed, and mail.order.refunded.

• Missing idempotency key: generate and persist one before creating a draft.
• Real-mail side effects: keep hosted checkout in the loop unless the customer explicitly opted into a machine-payment path.
• Duplicate retries: reuse the same idempotency key for the same intended mailing.
• Unverified recipient data: validate addresses before production checkout.