Yotru API
Maak kaarten en brieven, voeg ontvangers toe en keur campagnes goed vanuit je eigen software. Elke ontvanger komt op een open campagne voor die kaart of brief, en er wordt niets verstuurd voordat de campagne is goedgekeurd en betaald. Post gaat naar 16 landen: kaarten naar CA, US, NL, DE, GB, brieven naar alle landen.
Authenticatie
Je eerste sleutel wordt gemaakt zodra je Instellingen → Koppelingen → API-keys opent. Je e-mailadres moet bevestigd zijn, en je moet eigenaar of beheerder van het account zijn. Een sleutel zie je één keer, dus bewaar hem meteen. Kwijt? Maak een nieuwe en trek de oude in.
Authorization: Bearer yk_live_...De basis-URL is https://api.yotru.com. Er is geen testmodus: elke sleutel is live, maar kaarten maken en ontvangers toevoegen kan vrij. Alleen goedkeuren kost geld.
Snel starten
1. Maak een kaart. Wat je weglaat, komt uit de template of wordt van website gelezen.
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"}}'Een brief werkt hetzelfde. Deze gaat naar Duitsland, in het Duits, met een bedrukte achterkant:
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. Bekijk hem. De afbeelding is wat er gedrukt wordt.
curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
-H "Authorization: Bearer $YOTRU_KEY" -o front.png3. Voeg ontvangers toe. De eerste call opent een campagne; het id staat 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. Keur goed. Het antwoord bevat een payUrl; na betaling gaat de campagne naar de drukker. Goedkeuren en betalen kan ook op de campagnepagina in je dashboard. De volgende ontvangers die je toevoegt, openen een nieuwe campagne.
curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
-H "Authorization: Bearer $YOTRU_KEY"Endpoints
| Methode | Pad | Wat het doet |
|---|---|---|
| POST | /v1/cards | Maak een kaart (JSON, of multipart met data en photo) |
| PATCH | /v1/cards/{id} | Wijzig een kaart; alleen wat je stuurt verandert. Goedgekeurde campagnes houden hun kaart |
| GET | /v1/cards/{id} | Lees een kaart |
| GET | /v1/cards/{id}/preview/front | De kaart of brief zoals gedrukt; ook /back (kaarten, en brieven met backSide) |
| POST | /v1/recipients | Voeg tot 1.000 ontvangers per call toe |
| GET | /v1/batch?cardId= | De campagne die nu voor een kaart wordt gevuld |
| GET | /v1/campaigns/{id} | Hoe een campagne ervoor staat |
| POST | /v1/campaigns/{id}/approve | Keur goed: geeft de betaallink terug |
Kaarten
Elk veld is optioneel. Het antwoord bevat id, printable, issues en problems. Een kaart die je in je dashboard maakte, werkt ook: kopieer het id onder Kaarten. Ontvangers die je met een kaart-id stuurt, komen op een eigen campagne voor die kaart. Een brief maak je met dezelfde call, en hij krijgt een id zoals een kaart.
| Veld | Waarden |
|---|---|
name | Hoe je de kaart noemt |
product | card of letter; card als je het weglaat. Kaarten gaan naar CA, US, NL, DE, GB, brieven naar elk land. Een kaart wordt later geen brief en andersom |
template | Kaarten: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Brieven: 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 als je het weglaat. Ontvangers moeten in dit land wonen |
language | en, nl, fr, de, es, sv, no, da, fi, is; de taal van het land als je het weglaat |
backSide | Brieven naar DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true drukt een tweede pagina op de achterkant, tegen een meerprijs per brief |
website | Kleuren en logo worden hiervan gelezen als je ze niet meestuurt |
destinationUrl | Waar de QR-code naartoe gaat; de website als je het weglaat |
brand | companyName, primaryColor, secondaryColor, logoUrl, font |
text | Kaarten: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Brieven: headline, body, ctaLine (naast de QR-code), signOff, backHeadline, backBody |
contact | website, email, phone |
De body van een brief wordt gedrukt zoals je hem stuurt, dus begin met de aanhef die je wilt, bijvoorbeeld Beste {firstName},. Tokens zoals {firstName}, {lastName} en {companyName} worden per ontvanger ingevuld. Het antwoord bevat ook product en language; previewBack is null voor een brief van één pagina.
Een kaart naar een land dat alleen brieven krijgt, een taal of land dat we niet kennen, en backSide buiten die landen worden geweigerd met een 400 die zegt welk veld fout is. De prijs is die van het land waar de kaart of brief naartoe gaat, zie de tarieven.
Ontvangers
Een ontvanger heeft een persoon of een bedrijf nodig, en een volledig adres.
| Veld | Waarden |
|---|---|
| Persoon | name, of firstName en lastName; ook company, jobTitle |
| Adres | street, houseNumber, addition, of addressLine1, addressLine2; ook postcode, city, region, country |
| Overig | reference (komt bij je terug), email, phone, website, destinationUrl, customFields, photo |
Elke ontvanger komt terug als accepted met een id, of als refused met een reden: name, address, country, duplicate of photo. Een ontvanger buiten de country van de kaart wordt geweigerd met country; maak dan een kaart of brief voor zijn land. Stuur een Idempotency-Key-header mee, dan is een herhaalde call veilig.
Foto's
Stuur foto's als bestanden met multipart/form-data en zet de JSON in een veld data. Maximaal 25 bestanden van 10 MB per call en 32 MB in totaal. Op een kaart heet het veld photo. Een ontvanger met "photo": "anna.jpg" krijgt dat bestand; zonder krijgt hij de foto van de kaart. Een logo mag een link zijn, een foto niet.
Campagnes en betaling
Een campagne is open, awaiting_payment, approved, printing of sent. Er is geen minimum: je betaalt voor de kaarten op de campagne, en onder de 100 kaarten kost elke kaart de prijs van 100. Bij goedkeuren krijgt de eigenaar van het account ook een mail met een betaallink, en na betaling de factuur.
Limieten en fouten
| Limiet | Per sleutel |
|---|---|
| Alle calls | 120 per minuut |
| Kaarten maken of wijzigen, en calls met foto's | 300 per dag |
Fouten zijn JSON met een message: 400 voor wat je stuurde, 401 voor een ontbrekende of verkeerde sleutel, 404 voor iets dat niet op je account staat, 409 als de stand het niet toelaat, 429 als je over een limiet gaat.