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.png3. Ü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
| Methode | Pfad | Funktion |
|---|---|---|
| POST | /v1/cards | Brief 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/front | Bild des Briefs oder der Postkarte, genau wie gedruckt. Dazu /back (Postkarten und Briefe mit backSide) |
| POST | /v1/recipients | Bis 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}/approve | Freigeben: 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.
| Feld | Werte |
|---|---|
name | Ihr eigener Name für den Brief oder die Postkarte |
product | card (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 |
template | Postkarten: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Briefe: 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, ohne Angabe NL. Die Empfänger müssen in diesem Land wohnen |
language | en, nl, fr, de, es, sv, no, da, fi, is, ohne Angabe die Landessprache |
backSide | Briefe 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 |
website | Farben und Logo werden von dort gelesen, wenn Sie sie nicht mitsenden |
destinationUrl | Ziel des QR-Codes, ohne Angabe die Website |
brand | companyName, primaryColor, secondaryColor, logoUrl, font |
text | Postkarten: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Briefe: headline, body, ctaLine (neben dem QR-Code), signOff, backHeadline, backBody |
contact | website, 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.
| Feld | Werte |
|---|---|
| Person | name oder firstName und lastName, dazu company, jobTitle |
| Adresse | street, houseNumber, addition oder addressLine1, addressLine2, dazu postcode, city, region, country |
| Sonstiges | reference (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
| Limit | Pro Schlüssel |
|---|---|
| Alle Aufrufe | 120 pro Minute |
| Briefe und Postkarten anlegen oder ändern, Aufrufe mit Fotos | 300 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.