Quickstart

Updated 9/17/2026

Quickstart

Send your first test letter in about five minutes.

1. Get a test API key

Sign up, then go to Dashboard → Settings → API keys → New key, and create one with mode test. Copy the la_test_... value — it's shown once.

2. Pick a shop

Every print shop (provider) has an id. You use it as shopId when ordering. You can also copy it from Dashboard → Providers.
bash
curl https://letterapi.uk/api/v1/shops
json
{ "shops": [{ "id": "3f7e2b10-4c9a-4e1a-9b7e-2a8b6c1d0f33", "name": "Camden Print Co", "city": "London", "postcode": "NW1 1AA", "acceptsPickup": true, "acceptsPost": true }] }

3. Upload your PDF

The order needs a publicly accessible link to your PDF, because the print shop opens it directly. Uploading it here gives you exactly that.
bash
curl -X POST https://letterapi.uk/api/v1/files \
  -H "Authorization: Bearer la_test_xxxxxxxxxxxxxxxx" \
  -F "file=@letter.pdf;type=application/pdf"
json
{ "filePath": "https://.../print-jobs/5e2f.../1736850300000-9c1b....pdf", "pageCount": 1, "sizeBytes": 20481 }

4. Check the order

The quote takes the same body as creating the order. It checks your credit and the To and From addresses, and returns the price, without charging anything.
bash
curl -X POST https://letterapi.uk/api/v1/orders/quote \
  -H "Authorization: Bearer la_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "shopId": "3f7e2b10-4c9a-4e1a-9b7e-2a8b6c1d0f33",
    "fulfillmentType": "post",
    "postageClass": "second",
    "filePath": "https://.../print-jobs/5e2f.../1736850300000-9c1b....pdf",
    "filePageCount": 1,
    "paperSize": "A4",
    "colorMode": "bw",
    "sides": "single",
    "copies": 1,
    "finishing": "none",
    "recipientName": "Jane Doe",
    "recipientAddress": { "line1": "221B Baker Street", "city": "London", "postcode": "NW1 6XE" },
    "returnName": "Acme Ltd",
    "returnAddress": { "line1": "10 Downing Court", "city": "Leeds", "postcode": "LS1 1AA" }
  }'
The quote also confirms the print shop can open your PDF. When the response has "canCreate": true, send the same body to create the order. See Creating orders for every field and error.

5. Create the order

bash
curl -X POST https://letterapi.uk/api/v1/orders \
  -H "Authorization: Bearer la_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ...the same body you quoted... }'
Because this is a test-mode key, the order is created and paid instantly: no real card, no real credit deduction, no real letter printed.
json
{ "id": "8a1c...", "orderNumber": "LA-2026-100482", "status": "paid", "isTest": true, "...": "..." }

6. Watch it move through the lifecycle

bash
curl https://letterapi.uk/api/v1/orders/8a1c... \
  -H "Authorization: Bearer la_test_xxxxxxxxxxxxxxxx"
status progresses paid → sent_to_shop → printing → printed → mailing → posted as the (simulated, in test mode) print shop workflow advances.

7. Subscribe to webhooks instead of polling

bash
curl -X PUT "https://letterapi.uk/api/v1/account/webhooks?mode=test" \
  -H "Authorization: Bearer la_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.example.com/webhooks/letterapi" }'
Save the returned secret — you'll need it to verify incoming events. See Webhooks for the payload shape and signature verification.

Next steps

When you're ready to send real mail, create a live key and repeat the same requests — the API surface doesn't change, only the mode.
LetterAPIPrint and post letters in the UK, from one letter to thousands.
© 2026 LetterAPI. All rights reserved.