Yotru API

Legen Sie Briefe und Postkarten an, übergeben Sie Empfänger und geben Sie Kampagnen frei, direkt aus Ihrer eigenen Software. Jeder Empfänger kommt in eine offene Kampagne für diesen Brief oder diese Postkarte. Verschickt wird erst, wenn die Kampagne freigegeben und bezahlt ist. Die Post geht in 16 Länder: Postkarten nach CA, US, NL, DE, GB, Briefe in alle 16.

Authentifizierung

Ihr erster Schlüssel entsteht, wenn Sie Einstellungen → Integrationen → API-Schlüssel öffnen. Ihre E-Mail-Adresse muss bestätigt sein, und Sie müssen Inhaber oder Admin des Kontos sein. Ein Schlüssel wird nur einmal angezeigt. Speichern Sie ihn deshalb sofort. Wenn Sie ihn verlieren, erstellen Sie einen neuen und widerrufen den alten.

Authorization: Bearer yk_live_...

Die Basis-URL ist https://api.yotru.com. Einen Testmodus gibt es nicht: Jeder Schlüssel ist live. Briefe und Postkarten anlegen und Empfänger übergeben können Sie trotzdem beliebig oft. Nur die Freigabe kostet Geld.

Schnellstart

1. Legen Sie eine Postkarte an. Was Sie weglassen, kommt aus der Vorlage oder wird von website gelesen.

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"}}'

Ein Brief funktioniert genauso. Dieser geht nach Deutschland, ist auf Deutsch und hat eine bedruckte Rückseite:

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. Prüfen Sie das Ergebnis. Das Bild zeigt genau, was gedruckt wird.

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

3. Übergeben Sie Empfänger. Der erste Aufruf eröffnet eine Kampagne. Ihre ID steht in 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. Geben Sie frei. Die Antwort enthält eine payUrl. Sobald diese bezahlt ist, geht die Kampagne in den Druck. Sie können auch auf der Kampagnenseite in Ihrem Dashboard freigeben und bezahlen. Die nächsten Empfänger, die Sie übergeben, eröffnen eine neue Kampagne.

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

Endpunkte

MethodePfadFunktion
POST/v1/cardsBrief oder Postkarte anlegen (JSON oder multipart mit data und photo)
PATCH/v1/cards/{id}Brief oder Postkarte ändern. Nur was Sie senden, ändert sich. Freigegebene Kampagnen behalten den alten Stand
GET/v1/cards/{id}Brief oder Postkarte abrufen
GET/v1/cards/{id}/preview/frontBild des Briefs oder der Postkarte, genau wie gedruckt. Dazu /back (Postkarten und Briefe mit backSide)
POST/v1/recipientsBis zu 1.000 Empfänger pro Aufruf übergeben
GET/v1/batch?cardId=Die Kampagne, die sich gerade für einen Brief oder eine Postkarte füllt
GET/v1/campaigns/{id}Stand einer Kampagne
POST/v1/campaigns/{id}/approveFreigeben: liefert den Zahlungslink

Briefe und Postkarten

Jedes Feld ist optional. Die Antwort enthält id, printable, issues und problems. Ein Brief oder eine Postkarte aus Ihrem Dashboard funktioniert auch: Kopieren Sie die ID unter Briefe. Empfänger, die Sie mit dieser ID senden, kommen in eine eigene Kampagne für genau diese Sendung. Briefe und Postkarten legen Sie mit demselben Aufruf an, und beide haben eine ID.

FeldWerte
nameIhr eigener Name für den Brief oder die Postkarte
productcard (Postkarte) oder letter (Brief), ohne Angabe card. Postkarten gehen nach CA, US, NL, DE, GB, Briefe in jedes Land. Aus einer Postkarte wird später kein Brief und umgekehrt
templatePostkarten: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Briefe: letter-formal, letter-classic, letter-band, letter-plain
countryCA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS, ohne Angabe NL. Die Empfänger müssen in diesem Land wohnen
languageen, nl, fr, de, es, sv, no, da, fi, is, ohne Angabe die Landessprache
backSideBriefe nach DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true druckt eine zweite Seite auf die Rückseite, gegen Aufpreis pro Brief
websiteFarben und Logo werden von dort gelesen, wenn Sie sie nicht mitsenden
destinationUrlZiel des QR-Codes, ohne Angabe die Website
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textPostkarten: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Briefe: headline, body, ctaLine (neben dem QR-Code), signOff, backHeadline, backBody
contactwebsite, email, phone

Der body eines Briefs wird so gedruckt, wie Sie ihn senden. Beginnen Sie ihn also mit der gewünschten Anrede, zum Beispiel Guten Tag {firstName} {lastName},. Platzhalter wie {firstName}, {lastName} und {companyName} werden pro Empfänger ausgefüllt. Die Antwort enthält außerdem product und language. Bei einem einseitigen Brief ist previewBack null.

Eine Postkarte in ein Land, das nur Briefe annimmt, eine unbekannte Sprache, ein unbekanntes Land und backSide außerhalb dieser Länder lehnen wir mit 400 ab. Die Meldung nennt das fehlerhafte Feld. Es gilt der Preis des Landes, in das der Brief oder die Postkarte geht, siehe Preise.

Empfänger

Ein Empfänger braucht eine Person oder eine Firma und eine vollständige Adresse.

FeldWerte
Personname oder firstName und lastName, dazu company, jobTitle
Adressestreet, houseNumber, addition oder addressLine1, addressLine2, dazu postcode, city, region, country
Sonstigesreference (kommt an Sie zurück), email, phone, website, destinationUrl, customFields, photo

Jeder Empfänger kommt als accepted mit einer id zurück oder als refused mit einem Grund: name, address, country, duplicate oder photo. Ein Empfänger außerhalb des country der Sendung wird mit country abgelehnt. Legen Sie für sein Land einen eigenen Brief oder eine eigene Postkarte an. Mit einem Header Idempotency-Key ist ein wiederholter Aufruf sicher.

Fotos

Senden Sie Fotos als Dateien mit multipart/form-data und das JSON in einem Feld namens data. Pro Aufruf höchstens 25 Dateien zu je 10 MB, zusammen 32 MB. Bei Briefen und Postkarten heißt das Feld photo. Ein Empfänger mit "photo": "anna.jpg" bekommt diese Datei. Ohne Angabe bekommt er das Foto der Sendung. Ein Logo darf ein Link sein, ein Foto nicht.

Kampagnen und Zahlung

Eine Kampagne ist open, awaiting_payment, approved, printing oder sent. Es gibt kein Minimum: Sie zahlen für die Sendungen in der Kampagne. Unter 100 Stück gilt pro Stück der Preis für 100. Bei der Freigabe bekommt der Kontoinhaber außerdem eine E-Mail mit dem Zahlungslink und nach der Zahlung die Rechnung.

Limits und Fehler

LimitPro Schlüssel
Alle Aufrufe120 pro Minute
Briefe und Postkarten anlegen oder ändern, Aufrufe mit Fotos300 pro Tag

Fehler kommen als JSON mit einer message: 400 für Fehler in Ihren Daten, 401 bei fehlendem oder falschem Schlüssel, 404 für etwas, das nicht zu Ihrem Konto gehört, 409, wenn der aktuelle Stand es nicht zulässt, 429, wenn Sie ein Limit überschreiten.