Envíe cartas desde su propio sistema

Una petición HTTP con un texto y una dirección, y una carta impresa y franqueada llega al buzón. Sin impresora, sin sellos, sin ir a correos.

Crear una clave

En una sola llamada

Esta es la integración entera. La respuesta trae un identificador con el que consulta el estado, y ese mismo identificador aparece en su línea de factura.

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

Claves

Cada petición lleva una clave API como token bearer. Las claves se crean en su cuenta y cada una se muestra una sola vez; nosotros solo guardamos un hash. Revocar una clave surte efecto de inmediato.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Probar antes de enviar

Una clave que empieza por sk_test_ tarifica y compone la carta igual que una real, y se detiene justo antes de la impresora. Así prueba toda la integración sin que salga nada.

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)

No todos los países venden todos los productos. Consulte /api/quote y lea availableProducts: el certificado a los Países Bajos no existe, por ejemplo. Así puede desactivar una opción en lugar de dejar que falle al enviar.

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.

Avisos de estado a sus sistemas

Una carta cambia de estado unas pocas veces a lo largo de varios días. Consultar en bucle no encaja: o pregunta demasiado a menudo o se entera demasiado tarde. Registre un endpoint en su cuenta y le avisamos.

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

Cada aviso va firmado. Calcule HMAC-SHA256 sobre el cuerpo sin modificar con su secreto y compárelo con la cabecera X-SendLetter-Signature. Hágalo antes de analizar el cuerpo: analizarlo y volver a serializarlo cambia los bytes, y la firma ya no coincidirá nunca.

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

Errores

Todo error tiene la misma forma: un código sobre el que ramificar y un mensaje que leer. Ramifique sobre el código, porque el mensaje puede cambiar.

{ "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 especificación completa se sirve en vivo, así que nunca puede describir una versión que no esté funcionando. Apunte ahí un generador y tendrá un cliente en su propio lenguaje.

/api/v1/openapi.json