Yotru API
Crea postales y cartas, añade destinatarios y aprueba campañas desde tu propio software. Cada destinatario entra en una campaña abierta para esa postal o carta, y no se envía nada hasta que la campaña está aprobada y pagada. El correo llega a 16 países: las postales a CA, US, NL, DE, GB y las cartas a todos.
Autenticación
Tu primera clave se crea al abrir Ajustes → Integraciones → Claves de API. Tu correo tiene que estar confirmado y tienes que ser propietario o administrador de la cuenta. La clave se muestra una sola vez, así que guárdala enseguida. Si la pierdes, crea una nueva y revoca la antigua.
Authorization: Bearer yk_live_...La URL base es https://api.yotru.com. No hay modo de prueba: todas las claves son de producción, pero crear postales y cartas y añadir destinatarios no cuesta nada. Solo aprobar cuesta dinero.
Inicio rápido
1. Crea una postal. Lo que no envíes sale de la plantilla o se lee de website.
curl -X POST https://api.yotru.com/v1/cards \
-H "Authorization: Bearer $YOTRU_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Autumn offer","country":"NL","website":"https://example.com","text":{"headline":"Hello neighbour"}}'Una carta funciona igual. Esta va a Alemania, en alemán, con una página impresa en el reverso:
curl -X POST https://api.yotru.com/v1/cards \
-H "Authorization: Bearer $YOTRU_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Herbstangebot","product":"letter","country":"DE","website":"https://example.com","backSide":true,"text":{"headline":"Guten Tag","body":"Guten Tag {firstName} {lastName},\n\n..."}}'2. Revísala. La imagen es lo que se imprimirá.
curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
-H "Authorization: Bearer $YOTRU_KEY" -o front.png3. Añade destinatarios. La primera llamada abre una campaña; su ID está en batch.campaignId.
curl -X POST https://api.yotru.com/v1/recipients \
-H "Authorization: Bearer $YOTRU_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: import-2026-11-08" \
-d '{"cardId":"CARD_ID","recipients":[{"reference":"crm-42","name":"Anna de Vries","street":"Kerkstraat","houseNumber":"12","postcode":"1011 AB","city":"Amsterdam","country":"NL"}]}'4. Aprueba. La respuesta trae un payUrl; la campaña pasa a imprenta en cuanto se paga. También puedes aprobar y pagar en la página de la campaña, en tu panel. Los siguientes destinatarios que añadas abren una campaña nueva.
curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
-H "Authorization: Bearer $YOTRU_KEY"Endpoints
| Método | Ruta | Qué hace |
|---|---|---|
| POST | /v1/cards | Crea una postal o carta (JSON, o multipart con data y photo) |
| PATCH | /v1/cards/{id} | Cambia una postal o carta; solo cambia lo que envíes. Las campañas aprobadas conservan su versión |
| GET | /v1/cards/{id} | Lee una postal o carta |
| GET | /v1/cards/{id}/preview/front | La postal o carta tal como se imprime; también /back (postales, y cartas con backSide) |
| POST | /v1/recipients | Añade hasta 1.000 destinatarios por llamada |
| GET | /v1/batch?cardId= | La campaña que se está llenando ahora para una postal o carta |
| GET | /v1/campaigns/{id} | En qué punto está una campaña |
| POST | /v1/campaigns/{id}/approve | Aprueba: devuelve el enlace de pago |
Postales y cartas
Todos los campos son opcionales. La respuesta trae id, printable, issues y problems. Una postal o carta creada en tu panel también sirve: copia su ID en Cartas. Los destinatarios que envías con ese ID van a una campaña propia de esa postal o carta. Una carta se crea con la misma llamada y tiene un ID igual que una postal.
| Campo | Valores |
|---|---|
name | El nombre que le das |
product | card (postal) o letter (carta); card si no lo indicas. Las postales van a CA, US, NL, DE, GB; las cartas, a todos los países. Una postal no puede convertirse después en carta, ni al revés |
template | Postales: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Cartas: letter-formal, letter-classic, letter-band, letter-plain |
country | CA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS; NL si no lo indicas. Los destinatarios tienen que vivir en este país |
language | en, nl, fr, de, es, sv, no, da, fi, is; el idioma del país si no lo indicas |
backSide | Cartas a DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true imprime una segunda página en el reverso, con un coste extra por carta |
website | Los colores y el logo se leen de aquí si no los envías |
destinationUrl | A dónde lleva el código QR; la web si no lo indicas |
brand | companyName, primaryColor, secondaryColor, logoUrl, font |
text | Postales: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Cartas: headline, body, ctaLine (junto al código QR), signOff, backHeadline, backBody |
contact | website, email, phone |
El body de una carta se imprime tal como lo envías, así que empiézalo con el saludo que quieras, por ejemplo Hola {firstName}:. Los tokens como {firstName}, {lastName} y {companyName} se rellenan para cada destinatario. La respuesta también trae product y language; previewBack es null en una carta de una sola página.
Una postal a un país que solo recibe cartas, un idioma o país que no conocemos y backSide fuera de esos países se rechazan con un 400 que indica qué campo falla. El precio es el del país donde se envía la postal o carta; consulta los precios.
Destinatarios
Un destinatario necesita una persona o una empresa, y una dirección completa.
| Campo | Valores |
|---|---|
| Persona | name, o firstName y lastName; también company, jobTitle |
| Dirección | street, houseNumber, addition, o addressLine1, addressLine2; también postcode, city, region, country |
| Otros | reference (te la devolvemos), email, phone, website, destinationUrl, customFields, photo |
Cada destinatario vuelve como accepted con un id, o como refused con un motivo: name, address, country, duplicate o photo. Un destinatario fuera del country de la postal o carta se rechaza con country; en ese caso, crea una postal o carta para su país. Envía una cabecera Idempotency-Key para que repetir una llamada sea seguro.
Fotos
Envía las fotos como archivos con multipart/form-data y pon el JSON en un campo llamado data. Como máximo 25 archivos de 10 MB por llamada y 32 MB en total. En una postal o carta el campo es photo. Un destinatario con "photo": "anna.jpg" recibe ese archivo; sin él, recibe la foto de la postal o carta. Un logo puede ser un enlace; una foto no.
Campañas y pago
Una campaña está en open, awaiting_payment, approved, printing o sent. No hay mínimo: pagas las postales o cartas de la campaña y, por debajo de 100, cada una cuesta el precio por unidad de 100. Al aprobar, el propietario de la cuenta también recibe por correo un enlace para pagar y, después del pago, la factura.
Límites y errores
| Límite | Por clave |
|---|---|
| Todas las llamadas | 120 por minuto |
| Crear o cambiar postales y cartas, y llamadas con fotos | 300 al día |
Los errores son JSON con un message: 400 si falla lo que enviaste, 401 si falta la clave o es incorrecta, 404 si algo no está en tu cuenta, 409 si el estado no lo permite y 429 si superas un límite.