Send letters from your own system

One HTTP request with text and an address, and a printed, franked letter lands on a doormat. No printer, no stamps, no trip to the postbox.

Create a key

The whole integration

This is all of it. The response carries an id you use to read status, and that id also appears on your invoice line.

curl

curl -X POST https://sendletter.eu/api/v1/letters \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Geachte heer, mevrouw,\n\nHierbij zeg ik mijn abonnement op.",
    "subject": "Opzegging",
    "sender":    { "name": "Jan de Vries", "street": "Merelstraat", "number": "64",
                   "postalCode": "8916 AX", "city": "Leeuwarden", "country": "NL" },
    "recipient": { "company": "Voorbeeld BV", "name": "Afdeling Klantenservice",
                   "street": "Hoofdstraat", "number": "1",
                   "postalCode": "1011 AA", "city": "Amsterdam", "country": "NL" },
    "product": "standard",
    "idempotencyKey": "opzegging-2026-07-28"
  }'

Node.js

const res = await fetch("https://sendletter.eu/api/v1/letters", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SENDLETTER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text, sender, recipient, product: "registered",
                         idempotencyKey: invoice.id }),
})
const letter = await res.json()
// letter.id is what you store; poll it or wait for the webhook.

PHP

$ch = curl_init("https://sendletter.eu/api/v1/letters");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("SENDLETTER_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "text" => $body, "sender" => $sender, "recipient" => $recipient,
    "idempotencyKey" => $invoiceId,
  ]),
]);
$letter = json_decode(curl_exec($ch), true);

Python

import os, requests

letter = requests.post(
    "https://sendletter.eu/api/v1/letters",
    headers={"Authorization": f"Bearer {os.environ['SENDLETTER_KEY']}"},
    json={"text": body, "sender": sender, "recipient": recipient,
          "idempotencyKey": invoice_id},
    timeout=30,
).json()

Keys

Every request carries an API key as a bearer token. You create keys in your account and see each one exactly once; we store only a hash. Revoking a key takes effect immediately.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Try it before you post it

A key beginning sk_test_ prices and renders the letter exactly as a live one does, then stops just short of the printer. That lets you exercise the whole integration without anything going out.

Endpoints

POST	/api/v1/letters	Send a letter
GET	/api/v1/letters	List letters, newest first
GET	/api/v1/letters/{id}	One letter, with its timeline
POST	/api/quote	Price, and what that country can be sent(no key)
GET	/api/countries	Destinations and their address rules(no key)
GET	/api/v1/openapi.json	The machine readable spec(no key)

Not every destination sells every product. Ask /api/quote and read availableProducts: there is no registered service to the Netherlands, for instance. That way you can disable an option rather than let it fail at send time.

15 destinations. Registered mail: DE, BE, FR, ES, CH.

Statuses

queued: Accepted and waiting on the print partner.
submitted: Handed over to the printer.
printed: Printed and enveloped.
posted: Handed to the carrier. A response deadline runs from here.
delivered: Confirmed delivered. Registered mail only.
failed: Not sent. `statusDetail` says why, and the payment is returned.

Status callbacks to your systems

A letter changes state a handful of times over several days. Polling is the wrong shape for that: you either ask far too often or hear far too late. Register an endpoint in your account and we will tell you.

POST your-endpoint
X-SendLetter-Event: letter.posted
X-SendLetter-Signature: 9f86d081...

{ "type": "letter.posted",
  "sentAt": "2026-07-28T18:30:00.000Z",
  "letter": { "id": "AbC123", "status": "posted", "trackingCode": null, ... } }

Every callback is signed. Compute HMAC-SHA256 over the raw body with your secret and compare it to the X-SendLetter-Signature header. Do it before you parse the body: parsing and re-serialising changes the bytes, and the signature will never match again.

Node.js

import crypto from "node:crypto"

// The raw body, before any JSON parsing.
const expected = crypto.createHmac("sha256", process.env.WEBHOOK_SECRET)
  .update(rawBody, "utf8").digest("hex")
const sent = req.headers["x-sendletter-signature"]

if (expected.length !== sent.length ||
    !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sent))) {
  return res.status(401).end()
}

Errors

Every error has the same shape: a code to branch on and a message to read. Branch on the code, because the message may change.

{ "error": { "code": "no_route",
             "message": "Registered mail has no route to NL",
             "details": null } }

401	unauthorised	No key, a revoked key, or a malformed header.
400	invalid_request	The body failed validation. `details` names the fields.
402	insufficient_balance	The wallet is short. `details` carries required and available.
409	no_route	That product is not sold to that country. Ask /api/quote first.
413	too_many_pages	Over the sheet limit for that destination.
404	not_found	No such letter on this account.

OpenAPI

The full specification is served live, so it can never describe a version that is not running. Point a generator at it and you have a client in your own language.

/api/v1/openapi.json