Sending Physical Mail From Your App: A Practical API Guide

A print-and-mail API turns an HTTP request into a physical letter: you POST the recipient, the sender, and the content, and a printer somewhere produces paper that enters the postal system. It is worth reaching for in the specific cases where email does not do the job.

When paper beats email

• The email bounced. Postal addresses decay far more slowly than email addresses. For win-back and collections, mail reaches people your list has lost.
• The rules require paper. Plenty of statutory and regulatory notices still specify mail, and a spam folder is not a defence.
• You need to be read. A letter competes with four other envelopes; an email competes with three hundred messages.

What it is not good for is anything time-critical. Domestic delivery now runs three to seven business days. If it has to arrive tomorrow, mail is the wrong channel regardless of how good the API is.

What a request looks like

The shape is consistent across providers: authenticate with a key, describe the two addresses, supply the content, get back an id. Ours takes structured fields, raw HTML, or a base64 PDF:

curl -X POST https://sendletter.app/api/v1/send \
  -H "Authorization: Bearer sl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "draft",
    "letter_size": "standard",
    "from": {
      "name": "Acme Inc.",
      "line1": "100 Queen St W",
      "city": "Toronto",
      "province": "ON",
      "postal_code": "M5H 2N2",
      "country": "CA"
    },
    "to": {
      "name": "Jane Doe",
      "line1": "1 Rue Sainte-Catherine",
      "city": "Montreal",
      "province": "QC",
      "postal_code": "H2X 1K4",
      "country": "CA"
    },
    "letter": {
      "salutation": "Dear Ms. Doe,",
      "body": "Your subscription renews on 1 September.",
      "closing": "Sincerely,",
      "signature": "Acme Billing"
    }
  }'

Four things that bite first-timers

1. Retries send real paper. This is the big one. A retried API call that fails halfway can produce two physical letters, and you cannot recall the second. Generate an idempotency key per logical letter and store the returned id before you retry anything.

2. Addresses fail late. A bad email bounces in seconds. A bad postal address fails days later, silently, and often without telling you. Validate the postal code format up front — Canadian codes are letter-digit-letter digit-letter-digit — and always set a return address so undeliverable mail comes back instead of being destroyed.

3. Page count changes the price and the envelope. A tri-fold envelope holds a handful of sheets; past that you are into a flat envelope at a higher rate. If your content is user-generated, its length is now a billing input. Count pages before you send, not after.

4. Cost per piece is the whole cost model. There is no free tier in physics. Postage and printing put a hard floor under every letter, so unit economics matter in a way they never do for email. Check whether a provider adds a platform fee or monthly minimum on top of the per-piece price.

Picking a provider

Be honest about which lane you are in. If you are running bulk direct-mail campaigns with audience segmentation, address verification at scale, and per-campaign analytics, the established platforms — Lob and PostGrid among them — are built for exactly that and you should use one.

For the full request and response schema, error codes, and the other two content modes, see the API reference.