PostalForm Projects API Reference

One mail API, two modes

Every PostalForm Projects workspace has isolated test and live environments. Test keys (pf_test_…) run the entire flow — uploads, quotes, orders, status timelines, and webhooks — against simulated fulfillment, free of charge. Live keys (pf_live_…) create real mail and spend prepaid credits only after the mailpiece is accepted for fulfillment.

Dashboard: https://projects.postalform.com
API:       https://projects.postalform.com/api/v1

Authenticate every API call with a bearer key. Fulfillment routing is automatic: you choose the mailpiece options (speed, color, proof mail, destination) and PostalForm selects an eligible production path.

Authorization: Bearer pf_test_...
Authorization: Bearer pf_live_...

Send your first letter in five minutes

Get a workspace

stripe projects add postalform/mail

POSTALFORM_TEST_API_KEY=pf_test_...
POSTALFORM_WORKSPACE_ID=pfws_...

Run the flow

1. Create a PDF upload intent, PUT the PDF bytes to the returned URL, and mark the document complete.
2. Create a letter quote with the print, mail class, country, and proof-mail options you want.
3. Create the order with an Idempotency-Key header.
4. Poll the order or listen for signed webhooks as it moves toward delivery.

export POSTALFORM_API_KEY="pf_test_..."
export POSTALFORM_API_BASE="https://projects.postalform.com/api/v1"

# 1. Upload a PDF
curl -s "$POSTALFORM_API_BASE/documents/upload-intent" \
  -H "Authorization: Bearer $POSTALFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type":"application/pdf","byte_size":123456,"page_count":1}'
# → returns document_id + upload_url

curl -s -X PUT "<upload_url>" \
  -H "Content-Type: application/pdf" \
  --data-binary @letter.pdf

curl -s -X POST "$POSTALFORM_API_BASE/documents/<document_id>/complete" \
  -H "Authorization: Bearer $POSTALFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page_count":1}'

# 2. Quote it
curl -s "$POSTALFORM_API_BASE/letters/quotes" \
  -H "Authorization: Bearer $POSTALFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_id":"doc_..."}'
# → returns quote_id + price_cents

# 3. Send it
curl -s "$POSTALFORM_API_BASE/letters" \
  -H "Authorization: Bearer $POSTALFORM_API_KEY" \
  -H "Idempotency-Key: first-letter-2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"quote_...","recipient":{"name":"Ada Lovelace","line1":"1 Analytical Way","city":"San Francisco","state":"CA","postal_code":"94105"}}'

# 4. Watch it move
curl -s "$POSTALFORM_API_BASE/letters/<order_id>" \
  -H "Authorization: Bearer $POSTALFORM_API_KEY"

Prefer zero code first? The dashboard Send page runs this whole flow from a file picker. Use a pf_live_... key only when you intend to send real mail.

Typical test flow

POST /api/v1/documents/upload-intent
PUT  {upload_url}
POST /api/v1/documents/{document_id}/complete
POST /api/v1/letters/quotes
POST /api/v1/letters
GET  /api/v1/letters/{order_id}
GET  /api/v1/letters/{order_id}/document.pdf

Document Uploads

Create an upload intent for a PDF, PUT the bytes to the returned upload URL, then mark the document complete. page_count is optional but recommended because it makes quotes deterministic before the file is inspected.

POST /api/v1/documents/upload-intent
{
  "content_type": "application/pdf",
  "byte_size": 123456,
  "page_count": 4
}

POST /api/v1/documents/{document_id}/complete
{
  "page_count": 4
}

Upload URLs expire — finish the PUT and the complete call promptly after creating the intent. A validated document can back multiple quotes.

Letter Quotes

Quotes calculate the customer price and lock in the mail options for a later order. PostalForm automatically selects an eligible fulfillment path; API clients choose the mailpiece options, not the underlying production network.

POST /api/v1/letters/quotes
{
  "document_id": "doc_...",
  "mail_class": "usps_first_class",
  "color": false,
  "double_sided": true,
  "certified": false,
  "certified_return_receipt": false,
  "signature_required": false,
  "destination_country_code": "US",
  "origin_country_code": "US"
}

mail_class accepts standard/usps_first_class, priority/usps_priority, and express/usps_express. Priority and Express cannot be combined with certified or registered proof mail.

color controls black-and-white versus color printing. double_sided controls duplex printing when supported. Billing includes an inserted address page for letter mail.

Pricing

Pricing is separate from the one-off PostalForm.com workflow: standard letters start with a $1.80 base fee plus $0.20 per billable black-and-white page or $0.40 per billable color page. Proof-mail add-ons are $8.00 for U.S. Certified Mail, $32.00 for Canada Post Registered Mail, and $3.00 for Electronic Return Receipt where eligible. The quote is always the final price — estimate combinations on the pricing calculator.

Proof mail

Set certified=true for proof-mail services on eligible standard letters. U.S. destinations request USPS Certified Mail. Canadian destinations request Canada Post Registered Mail. Belgium, Switzerland, and France destinations request the available registered-mail option for that destination.

certified_return_receipt=true applies only to eligible U.S. Certified Mail. For Canada Post Registered Mail, the return-receipt flag is ignored because the registered service already includes the available delivery proof.

signature_required=true applies to eligible U.S. Priority and Express letters. Postcards do not support certified, registered, return-receipt, or signature-required options.

International mailing

Letter quotes accept destination_country_code and origin_country_code; both default to US. Supported first-party destination countries are US, CA, AT, BE, CH, DE, FR, GB, IN, LU, and NL.

Fast international mail is available only for destinations with a distinct fast-mail product. If a requested option is unavailable for the destination, the quote request returns a validation error instead of silently changing the requested service.

For international letters, include a sender address. Some destinations require a sender country that is compatible with the selected mailpiece options.

Postcards

Postcards use /api/v1/postcards/quotes and /api/v1/postcards. The uploaded PDF must already be a composed two-page postcard artwork file: page 1 is the front and page 2 is the back.

POST /api/v1/postcards/quotes
{
  "document_id": "doc_...",
  "postcard_size": "4x6",
  "destination_country_code": "US",
  "origin_country_code": "US"
}

postcard_size accepts 4x6, 6x9, or 11x6. Postcards are quoted as first-class, color, double-sided mail and do not support proof-mail add-ons.

Create Orders

Create an order from a quote with an Idempotency-Key header. Reusing the same key with the same quote returns the original order with idempotent_replay=true, so network retries never create duplicate physical mail.

POST /api/v1/letters
Idempotency-Key: unique-order-key
{
  "quote_id": "quote_...",
  "recipient": { "name": "...", "line1": "...", "city": "...", "postal_code": "...", "countryCode": "US" },
  "sender": { "name": "...", "line1": "...", "city": "...", "postal_code": "...", "countryCode": "US" },
  "metadata": { "customer_id": "..." }
}

recipient is required. sender is strongly recommended for all live mail and required for some destinations and mailpiece options. metadata is stored on the order and returned in reads and webhooks.

Order responses

Order reads return the customer-facing mailpiece state, pricing, funds state, metadata, timeline, customer webhook events, and any tracking number that has been received.

GET /api/v1/letters/{order_id}

{
  "id": "ord_123",
  "object": "letter",
  "mailpiece_type": "letter",
  "status": "in_transit",
  "mode": "live",
  "price_cents": 220,
  "currency": "usd",
  "funds_status": "captured",
  "billing_rail": "prepaid_credits",
  "tracking_number": "9405500000000000000001",
  "tracking_status": "in_transit",
  "metadata": { "customer_id": "..." },
  "timeline": [],
  "webhook_events": []
}

Status lifecycle

Status values include queued, document_preparing, document_prepared, submitted, accepted, in_transit, delivered, returned, submission_pending, failed, and canceled.

submission_pending is a safety marker: the fulfillment job entered a window where PostalForm will not blindly retry, because a blind retry could create duplicate physical mail. If a later status follows it, it was transient. If it remains the current status, the order is being reconciled before anything else is mailed.

Customer Webhooks

Use /api/v1/webhook-endpoints (or the dashboard) to register HTTPS endpoints. Customer webhook events are emitted for fulfillment status changes with postalform.{letter|postcard}.{status} event names: accepted, in_transit, delivered, returned, failed, and canceled.

Signing secrets are endpoint-scoped, start with whsec_, and are shown once when the endpoint is created or rotated — list calls never expose them. One endpoint can receive both test and live events.

PostalForm-Signature: t=1777592400,v1=<hmac_sha256_hex>

{
  "id": "evt_123",
  "type": "postalform.letter.in_transit",
  "data": {
    "object": {
      "id": "ord_123",
      "object": "letter",
      "status": "in_transit",
      "mode": "live",
      "price_cents": 220,
      "currency": "usd",
      "funds_status": "captured",
      "billing_rail": "prepaid_credits",
      "metadata": {}
    }
  },
  "mailpiece": {
    "status": "in_transit",
    "tracking_number": "9405500000000000000001",
    "tracking_status": "In Transit"
  }
}

Verify signatures

The signed payload is {timestamp}.{raw_json_body}, HMAC-SHA256 with your endpoint secret — the same shape as Stripe-style webhooks. Verify before trusting any delivery:

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyPostalFormWebhook(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((part) => part.trim().split('=')))
  const timestamp = Number(parts.t)
  if (!Number.isFinite(timestamp) || Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300)
    return false

  const expected = createHmac('sha256', secret).update(timestamp + '.' + rawBody).digest('hex')
  const received = parts.v1 ?? ''
  return (
    received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  )
}

Delivery and retries

Respond with a 2xx quickly. Failed deliveries retry up to six times with increasing backoff (about 1 minute, 5 minutes, 30 minutes, 2 hours, 12 hours, then 24 hours). Replay any event on demand with POST /api/v1/webhook-events/{event_id}/replay, and inspect every delivery attempt from the dashboard.

Credits And Live Mail

Live mail spends prepaid credits: funds are reserved when an order is created and captured when fulfillment accepts the mailpiece. Top-ups are the only card charge that happens before mail is sent.

GET  /api/v1/credits/balance
POST /api/v1/credits/checkout-session
GET  /api/v1/credits/payment-methods
POST /api/v1/credits/payment-methods/setup-session
GET  /api/v1/credits/auto-refill
POST /api/v1/credits/auto-refill
GET  /api/v1/credits/ledger

Go-live checklist

1. Finish your integration in test mode — the API surface is identical.
2. Add prepaid credits from the dashboard Credits page or POST /api/v1/credits/checkout-session.
3. Optionally save a payment method and configure auto-refill so live sends never fail on balance.
4. Rotate a live key from the dashboard or POST /api/v1/api-keys/rotate with {"mode":"live"}.
5. Send one live letter to yourself and watch the webhook events arrive.

Live keys stay disabled until the workspace is live-enabled through billing setup, so a leaked test integration can never mail anything real.

Errors And Rate Limits

Errors return a machine-readable code, with a 4xx status for request problems and 5xx for PostalForm-side failures.

{ "error": "idempotency_key_required" }

Each API key is limited to 120 requests per 60 seconds. Batch large jobs client-side and honor retry_after_seconds on 429 responses. Validation failures (an ineligible option combination, an expired quote, a malformed address) return a descriptive error code instead of silently changing the request.

Generated Schema And SDKs

The hosted OpenAPI YAML is the customer API source of truth for SDK generation. It documents request bodies, response properties, enums, authentication, and webhook payloads.

GET /openapi.json
GET /openapi.public.json
GET /openapi.yaml
GET /openapi.public.yaml

Generated TypeScript (@postalform/projects-sdk) and Python (postalform-projects-sdk) clients are built from this schema. Until they are published to npm and PyPI, generate your own client from /openapi.public.yaml with any OpenAPI generator, or call the API directly — every endpoint works with plain HTTP.

Building with agents? GET /llm-context.txt serves a compact machine-readable summary of provisioning and this API.

Endpoint Reference

This table is generated from the public OpenAPI schema served by /openapi.json and /openapi.yaml.

Configuration Reference

These request-body tables come from the same OpenAPI schema used for SDK generation.

Response Fields

These response tables explain the IDs, prices, state fields, timeline entries, and tracking fields returned by order and credit reads.

Webhook And Key Fields

Webhook payloads use customer-facing order states. Store webhook signing secrets when they are created or rotated because they are returned once.