Yotru API

Créez des cartes postales et des lettres, ajoutez des destinataires et approuvez des campagnes depuis votre propre logiciel. Chaque destinataire entre dans une campagne ouverte pour cette carte ou cette lettre. Rien ne part à la poste avant que la campagne soit approuvée et payée. Le courrier part dans 16 pays : les cartes postales vers CA, US, NL, DE, GB, les lettres vers les 16.

Authentification

Votre première clé est créée à l'ouverture de Paramètres → Intégrations → Clés d'API. Votre adresse courriel doit être confirmée, et vous devez être propriétaire ou administrateur du compte. Une clé ne s'affiche qu'une fois : enregistrez-la tout de suite. Si vous la perdez, créez-en une nouvelle et révoquez l'ancienne.

Authorization: Bearer yk_live_...

L'URL de base est https://api.yotru.com. Il n'y a pas de mode test : chaque clé est réelle. Vous pouvez toutefois créer des cartes et ajouter des destinataires librement. Seule l'approbation coûte de l'argent.

Démarrage rapide

1. Créez une carte. Ce que vous omettez vient du modèle ou est lu sur 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"}}'

Une lettre fonctionne de la même façon. Celle-ci part en Allemagne, rédigée en allemand, avec une page imprimée au verso :

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. Vérifiez le résultat. L'image montre exactement ce qui sera imprimé.

curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
  -H "Authorization: Bearer $YOTRU_KEY" -o front.png

3. Ajoutez des destinataires. Le premier appel ouvre une campagne. Son identifiant se trouve dans 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. Approuvez. La réponse contient un payUrl. La campagne part à l'impression une fois ce lien payé. Vous pouvez aussi approuver et payer sur la page de la campagne, dans votre tableau de bord. Les destinataires que vous ajoutez ensuite ouvrent une nouvelle campagne.

curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
  -H "Authorization: Bearer $YOTRU_KEY"

Points de terminaison

MéthodeCheminRôle
POST/v1/cardsCréer une carte ou une lettre (JSON, ou multipart avec data et photo)
PATCH/v1/cards/{id}Modifier une carte. Seul ce que vous envoyez change. Les campagnes approuvées gardent leur version
GET/v1/cards/{id}Lire une carte
GET/v1/cards/{id}/preview/frontLa carte ou la lettre telle qu'elle sera imprimée. Aussi /back (cartes, et lettres avec backSide)
POST/v1/recipientsAjouter jusqu'à 1 000 destinataires par appel
GET/v1/batch?cardId=La campagne en cours de remplissage pour une carte
GET/v1/campaigns/{id}L'état d'une campagne
POST/v1/campaigns/{id}/approveApprouver : renvoie le lien de paiement

Cartes

Tous les champs sont facultatifs. La réponse contient id, printable, issues et problems. Une carte créée dans votre tableau de bord fonctionne aussi : copiez son identifiant sous Cartes. Les destinataires envoyés avec un identifiant de carte entrent dans une campagne propre à cette carte. Une lettre se crée avec le même appel et a un identifiant, comme une carte.

ChampValeurs
nameLe nom que vous donnez à la carte
productcard ou letter, card par défaut. Les cartes partent vers CA, US, NL, DE, GB, les lettres vers tous les pays. Une carte ne peut pas devenir une lettre plus tard, ni l'inverse
templateCartes : introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Lettres : 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 par défaut. Les destinataires doivent habiter dans ce pays
languageen, nl, fr, de, es, sv, no, da, fi, is. Par défaut, la langue du pays
backSideLettres vers DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS : true imprime une deuxième page au verso, avec un supplément par lettre
websiteLes couleurs et le logo y sont lus si vous ne les envoyez pas
destinationUrlLa destination du code QR. Par défaut, le site web
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textCartes : greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Lettres : headline, body, ctaLine (à côté du code QR), signOff, backHeadline, backBody
contactwebsite, email, phone

Le body d'une lettre est imprimé tel que vous l'envoyez. Commencez-le donc par la formule d'appel voulue, par exemple Bonjour {firstName},. Les jetons comme {firstName}, {lastName} et {companyName} sont remplis pour chaque destinataire. La réponse contient aussi product et language. Pour une lettre d'une seule page, previewBack vaut null.

Une carte vers un pays qui ne reçoit que des lettres, une langue ou un pays inconnus, et backSide hors de ces pays sont refusés avec un 400 qui indique le champ en cause. Le prix est celui du pays où la carte ou la lettre est postée. Voir les tarifs.

Destinataires

Un destinataire a besoin d'une personne ou d'une entreprise, et d'une adresse complète.

ChampValeurs
Personnename, ou firstName et lastName. Aussi company, jobTitle
Adressestreet, houseNumber, addition, ou addressLine1, addressLine2. Aussi postcode, city, region, country
Autresreference (qui vous est renvoyé), email, phone, website, destinationUrl, customFields, photo

Chaque destinataire revient accepted avec un id, ou refused avec une raison : name, address, country, duplicate ou photo. Un destinataire hors du country de la carte est refusé avec country. Créez plutôt une carte ou une lettre pour son pays. Envoyez un en-tête Idempotency-Key pour qu'un appel répété soit sans risque.

Photos

Envoyez les photos comme fichiers en multipart/form-data et placez le JSON dans un champ nommé data. Au plus 25 fichiers de 10 MB par appel, et 32 MB au total. Sur une carte, le champ s'appelle photo. Un destinataire avec "photo": "anna.jpg" reçoit ce fichier. Sans cela, il reçoit la photo de la carte. Un logo peut être un lien, une photo non.

Campagnes et paiement

Une campagne est open, awaiting_payment, approved, printing ou sent. Il n'y a pas de minimum : vous payez les cartes de la campagne. Sous 100 cartes, chacune coûte le prix unitaire à 100 cartes. L'approbation envoie aussi au propriétaire du compte un courriel avec le lien de paiement, puis la facture une fois le paiement reçu.

Limites et erreurs

LimitePar clé
Tous les appels120 par minute
Création ou modification de cartes, et appels avec photos300 par jour

Les erreurs sont en JSON avec un message : 400 pour un problème dans ce que vous envoyez, 401 pour une clé absente ou invalide, 404 pour un élément absent de votre compte, 409 quand l'état ne le permet pas, 429 quand vous dépassez une limite.