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.png

3. 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étodoRutaQué hace
POST/v1/cardsCrea 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/frontLa postal o carta tal como se imprime; también /back (postales, y cartas con backSide)
POST/v1/recipientsAñ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}/approveAprueba: 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.

CampoValores
nameEl nombre que le das
productcard (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
templatePostales: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Cartas: letter-formal, letter-classic, letter-band, letter-plain
countryCA, 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
languageen, nl, fr, de, es, sv, no, da, fi, is; el idioma del país si no lo indicas
backSideCartas 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
websiteLos colores y el logo se leen de aquí si no los envías
destinationUrlA dónde lleva el código QR; la web si no lo indicas
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textPostales: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Cartas: headline, body, ctaLine (junto al código QR), signOff, backHeadline, backBody
contactwebsite, 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.

CampoValores
Personaname, o firstName y lastName; también company, jobTitle
Direcciónstreet, houseNumber, addition, o addressLine1, addressLine2; también postcode, city, region, country
Otrosreference (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ímitePor clave
Todas las llamadas120 por minuto
Crear o cambiar postales y cartas, y llamadas con fotos300 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.