Spedisci lettere dal tuo sistema

Una richiesta HTTP con un testo e un indirizzo, e una lettera stampata e affrancata arriva nella buca. Senza stampante, senza francobolli, senza passare in posta.

Crea una chiave

In una sola chiamata

L'integrazione è tutta qui. La risposta contiene un identificativo con cui leggere lo stato, e lo stesso identificativo compare sulla riga di fattura.

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()

Chiavi

Ogni richiesta porta una chiave API come bearer token. Le chiavi si creano nel tuo account e ciascuna si vede una volta sola; noi conserviamo solo un hash. La revoca ha effetto immediato.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Prima provare, poi spedire

Una chiave che inizia con sk_test_ calcola e compone la lettera esattamente come una reale, poi si ferma appena prima della stampante. Così collaudi tutta l'integrazione senza che parta nulla.

Endpoint

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)

Non tutti i paesi vendono tutti i prodotti. Interroga /api/quote e leggi availableProducts: la raccomandata verso i Paesi Bassi, per esempio, non esiste. Così disattivi un'opzione invece di lasciarla fallire in fase di invio.

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.

Notifiche di stato ai tuoi sistemi

Una lettera cambia stato poche volte, distribuite su più giorni. Il polling non è la forma giusta: o chiedi troppo spesso o lo scopri troppo tardi. Registra un endpoint nel tuo account e ti avvisiamo noi.

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, ... } }

Ogni notifica è firmata. Calcola HMAC-SHA256 sul corpo grezzo con il tuo secret e confrontalo con l'header X-SendLetter-Signature. Fallo prima di analizzare il corpo: analizzarlo e riserializzarlo cambia i byte, e la firma non tornerà mai più.

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()
}

Errori

Ogni errore ha la stessa forma: un codice su cui ramificare e un messaggio da leggere. Ramifica sul codice, perché il messaggio può cambiare.

{ "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

La specifica completa è servita dal vivo, quindi non può mai descrivere una versione che non è in esecuzione. Puntaci un generatore e ottieni un client nel tuo linguaggio.

/api/v1/openapi.json