LettrLabs API Documentation

The end‑to‑end path to send your first order — find a template, create the order, add recipients, and check out.

This walkthrough puts the API calls in the order you actually make them: start from a template, create an order, attach recipients, then confirm and pay. Each step links to the full reference, where you can fire the request live with your own key.

New here? Skim Authentication & API keys first — every call below sends your key in the X-API-KEY header.

1. Get a template ID

Orders are generated from a template you design in the LettrLabs app (handwritten cards, printed mail, and so on). Open the template in the app; its numeric template ID is the templateId you pass when creating an order. There is no public endpoint that lists templates — the ID comes from the app.

2. Create the order

Create the order with POST /v1/order. The only required field is templateId; recipients and mailing options can be set now or added in the next step.

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 }'

Keep the returned order ID — every later step uses it.

3. Add recipients

Attach (or replace) the order's recipients with PUT /v1/order/{id}/recipients. Review what's currently attached with GET /v1/order/{id}/recipients.

curl -X PUT https://app.lettrlabs.com/api/v1/order/ORDER_ID/recipients \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '[ { /* see the reference for the recipient shape */ } ]'

4. Preview a proof (optional)

Before you pay, pull a rendered proof with GET /v1/order/{id}/proof to confirm the mail looks right.

5. Check out

Confirm and pay for the order with POST /v1/order/{id}/checkout. Until you check out, the order is a draft and nothing mails.

curl -X POST https://app.lettrlabs.com/api/v1/order/ORDER_ID/checkout \
  -H "X-API-KEY: your_api_key_here"

After it mails

Track recipient‑level delivery and engagement with Order Recipient Analytics (see the API Reference).
Record outcomes with conversions — see Attributions & Conversions.

Re‑sending POST /v1/order creates a new order every time — there is no automatic de‑duplication. See the idempotency note in Creating an Order before adding retries.

Order of operations