Creating an Order
Generate a direct‑mail order from a template and send it to your recipients.
An order is a batch of direct mail generated from one of your templates and
addressed to a set of recipients. You create orders with a single call to
POST /v1/order, referencing a template you have already designed in the
LettrLabs app.
Before you start
- A public API key — see Authentication & API keys.
- A template built in the LettrLabs app. Its numeric template ID is what
you pass as
templateId.
Create an order from a template
The only required field is templateId. The full request body — recipients,
mailing options, and template merge fields — is documented, field by field, on
the POST /v1/order reference page, where you can also
fire the request live with your own key.
curl -X POST https://app.lettrlabs.com/api/v1/order \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"templateId": 12345
}'A successful call returns the created order. Keep the returned order ID — you use it to manage recipients, pull proofs, and check out the order.
Work with an order after it's created
Each of these is documented in full under API Reference:
| Action | Endpoint |
|---|---|
| List orders | GET /v1/order |
| Review an order's recipients | GET /v1/order/{id}/recipients |
| Add or update recipients | PUT /v1/order/{id}/recipients |
| Remove recipients | DELETE /v1/order/{id}/recipients |
| Preview a proof | GET /v1/order/{id}/proof |
| Check out (confirm + pay) | POST /v1/order/{id}/checkout |
| Cancel an order | DELETE /v1/order/{id} |
Idempotency
Re‑sending the same POST /v1/order request creates a new order each time —
there is no automatic de‑duplication. If a request times out, fetch
GET /v1/order to check whether the order was created before retrying, so you
don't mail the same batch twice.