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

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

MethodePadWat het doet
POST/v1/cardsMaak 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/frontDe kaart of brief zoals gedrukt; ook /back (kaarten, en brieven met backSide)
POST/v1/recipientsVoeg 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}/approveKeur 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.

VeldWaarden
nameHoe je de kaart noemt
productcard 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
templateKaarten: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Brieven: 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 als je het weglaat. Ontvangers moeten in dit land wonen
languageen, nl, fr, de, es, sv, no, da, fi, is; de taal van het land als je het weglaat
backSideBrieven 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
websiteKleuren en logo worden hiervan gelezen als je ze niet meestuurt
destinationUrlWaar de QR-code naartoe gaat; de website als je het weglaat
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textKaarten: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Brieven: headline, body, ctaLine (naast de QR-code), signOff, backHeadline, backBody
contactwebsite, 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.

VeldWaarden
Persoonname, of firstName en lastName; ook company, jobTitle
Adresstreet, houseNumber, addition, of addressLine1, addressLine2; ook postcode, city, region, country
Overigreference (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

LimietPer sleutel
Alle calls120 per minuut
Kaarten maken of wijzigen, en calls met foto's300 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.