Developer / API
Direct mail API: send physical mail from code
By Justin Winter · Updated August 23, 2026
One endpoint, POST /v1/orders, prints and mails a real USPS letter — no account, no API key, no monthly platform fee. Pay per piece (First-Class from $1.99), pass sandbox: true for a free instant end-to-end test, and get a signed webhook when the piece is mailed and delivered.
The shape of it
Most direct mail APIs make you create a template object, a campaign object, and an audience object before a single piece of paper moves. This one has one endpoint — pick a language, or run it for real right here:
curl -X POST https://sendpaperplane.com/v1/orders \
-H 'Content-Type: application/json' \
-d '{
"mail_class": "first_class",
"sandbox": true,
"text": "Dear Alex,\n\nThis is a real letter sent through an API.",
"to": {
"name": "Alex Rivera",
"line1": "12 Grove Ave",
"city": "Richmond",
"state": "VA",
"zip": "23221"
},
"from": {
"name": "Jordan Lee",
"line1": "1 Main St",
"city": "Richmond",
"state": "VA",
"zip": "23220"
}
}'Try it — real sandbox request
Fires the request above at this site's live API with sandbox: true. Nothing is charged or mailed.
That single call renders the text into a printable letter, verifies both addresses with USPS, prices it, and either mails it (a real order) or simulates the whole pipeline for free (sandbox: true). There is no separate "create template" step and no campaign object to configure first.
What it costs
No platform fee, no monthly minimum, no per-seat pricing — every price is per piece and all-in, postage included. First-Class starts at $1.99; Certified Mail (with proof of mailing) is $12.99; Certified with an electronic Return Receipt is $14.99. Pay with a Stripe-hosted checkout link on the response, or a prepaid credit code for zero-friction repeat sends.
Automation: webhooks and triggers
Pass a webhook_url on order creation and get a signed POST for every status change — submitted, mailed, delivered, refused, canceled, failed — the same signing scheme (HMAC-SHA256) used across this API's inbound webhooks. That is the building block for triggering a letter from a CRM event, a support ticket, or a scheduled job without a person in the loop; see automating compliance mail from your CRM or support tool for a worked example.
Sending more than one letter
There is no bulk-send endpoint by design — every letter, first or five-hundredth, goes through the same POST /v1/orders. For a spreadsheet of recipients, POST /v1/csv-map proposes a header-to-address mapping and you loop the order endpoint once per row. A bad row fails on its own without stalling the rest of the batch, which a server-side batch job would not give you for free.
Rate limits, for planning an integration
Without a verified account, sends are capped per actor at 15/day and 60/month, with a $50/day and $200/month spend cap — enough to build and demo a real integration, not enough for production marketing volume. Contact support for a higher-volume verified account before launching against a real list.
Related guides
Common questions
Do I need an API key or account to use this?
No. There is no signup and no API key on the public surface — every order carries its own payment, either a Stripe checkout link or a prepaid credit code. This is a deliberate design choice, not a missing feature: it removes the biggest friction point in most direct mail APIs, which is a sales call before you can send a single test piece.
How is this different from a direct mail marketing platform?
Direct mail marketing platforms are built around campaigns — audiences, segments, a send-to-a-list object. This API has one primitive: POST /v1/orders sends one letter to one address. Sending many letters is a client-side loop over that same endpoint (see the mail merge guide), not a separate bulk product. That makes it a better fit for transactional and compliance mail — a single certified notice, a one-off demand letter, a webhook-triggered response — than for a marketing blast.
What does "direct mail automation" look like on this API?
Two pieces: outbound webhooks (pass webhook_url on order creation and get an HMAC-SHA256-signed POST when the order is submitted, mailed, delivered, refused, canceled, or fails) and idempotent, code-driven sends — trigger POST /v1/orders from a CRM event, a support-ticket status change, or a cron job, with no human touching a mail merge document in between. See the compliance-mail automation guide for a concrete CRM-triggered example.
Can I test this without spending money?
Yes — pass sandbox: true on POST /v1/orders. It runs the entire pipeline (address verification, pricing, order creation, status transitions) with nothing actually printed or mailed and nothing charged. It is the recommended way to build an integration before pointing it at a real address.
What happens if USPS cannot deliver to the address I send?
Every address is verified against USPS data before anything prints. An undeliverable address returns a 422 with a clear reason at request time — you never pay for or discover a bounced piece after the fact the way you would mailing blind.