Yotru API

Lag postkort og brev, legg til mottakere og godkjenn kampanjer fra ditt eget system. Hver mottaker legges til i en åpen kampanje for det kortet eller brevet, og ingenting sendes før kampanjen er godkjent og betalt. Post går til 16 land: postkort til CA, US, NL, DE, GB, brev til alle.

Autentisering

Den første nøkkelen din lages når du åpner Innstillinger → Integrasjoner → API-nøkler. E-postadressen din må være bekreftet, og du må være eier eller administrator for kontoen. En nøkkel vises bare én gang, så lagre den med en gang. Mister du den, lager du en ny og trekker tilbake den gamle.

Authorization: Bearer yk_live_...

Basis-URL-en er https://api.yotru.com. Det finnes ingen testmodus: alle nøkler er live, men du kan fritt lage kort og legge til mottakere. Bare godkjenning koster penger.

Hurtigstart

1. Lag et kort. Det du utelater, kommer fra malen eller leses fra 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"}}'

Et brev fungerer på samme måte. Dette går til Tyskland, på tysk, med en trykt side på baksiden:

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. Se på det. Bildet er det som blir trykt.

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

3. Legg til mottakere. Det første kallet åpner en kampanje. ID-en finnes i 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. Godkjenn. Svaret inneholder en payUrl, og kampanjen går til trykk når den er betalt. Du kan også godkjenne og betale på kampanjesiden i dashbordet. De neste mottakerne du legger til, åpner en ny kampanje.

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

Endepunkter

MetodeStiHva det gjør
POST/v1/cardsLag et kort (JSON, eller multipart med data og photo)
PATCH/v1/cards/{id}Endre et kort. Bare det du sender, endres. Godkjente kampanjer beholder kortet sitt
GET/v1/cards/{id}Les et kort
GET/v1/cards/{id}/preview/frontKortet eller brevet slik det blir trykt. Også /back (postkort, og brev med backSide)
POST/v1/recipientsLegg til opptil 1 000 mottakere per kall
GET/v1/batch?cardId=Kampanjen som fylles nå for et kort
GET/v1/campaigns/{id}Status for en kampanje
POST/v1/campaigns/{id}/approveGodkjenn: returnerer betalingslenken

Kort

Alle felt er valgfrie. Svaret inneholder id, printable, issues og problems. Et kort du har laget i dashbordet, fungerer også: kopier ID-en under Brev. Mottakere som sendes med ID-en til et kort, havner i en egen kampanje for det kortet. Et brev lages med det samme kallet og får en ID akkurat som et kort.

FeltVerdier
nameHva du kaller kortet
productcard eller letter; card hvis det utelates. Postkort går til CA, US, NL, DE, GB, brev til alle land. Et postkort kan ikke bli et brev senere, eller omvendt
templatePostkort: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Brev: 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 hvis det utelates. Mottakerne må bo i dette landet
languageen, nl, fr, de, es, sv, no, da, fi, is; landets eget språk hvis det utelates
backSideBrev til DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true trykker en side til på baksiden, mot et tillegg per brev
websiteFarger og logo leses herfra når du ikke sender dem
destinationUrlHvor QR-koden leder; nettsiden hvis det utelates
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textPostkort: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Brev: headline, body, ctaLine (ved siden av QR-koden), signOff, backHeadline, backBody
contactwebsite, email, phone

body i et brev blir trykt nøyaktig slik du sender den, så start med hilsenen du vil ha, for eksempel Hei {firstName},. Tokens som {firstName}, {lastName} og {companyName} fylles inn per mottaker. Svaret inneholder også product og language. previewBack er null for et brev med én side.

Et postkort til et land som bare tar imot brev, et språk eller land vi ikke kjenner, og backSide utenfor de landene avvises med 400 og en melding om hvilket felt som er feil. Prisen er den som gjelder i landet kortet eller brevet sendes fra, se priser.

Mottakere

En mottaker trenger en person eller et firma, og en fullstendig adresse.

FeltVerdier
Personname, eller firstName og lastName; også company, jobTitle
Adressestreet, houseNumber, addition, eller addressLine1, addressLine2; også postcode, city, region, country
Annetreference (sendes tilbake til deg), email, phone, website, destinationUrl, customFields, photo

Hver mottaker kommer tilbake som accepted med en id, eller som refused med en grunn: name, address, country, duplicate eller photo. En mottaker utenfor kortets country avvises med country. Lag i stedet et kort eller brev for mottakerens land. Send en Idempotency-Key-header, så er et gjentatt kall trygt.

Bilder

Send bilder som filer med multipart/form-data, og legg JSON i et felt som heter data. Maks 25 filer på 10 MB per kall og 32 MB totalt. På et kort heter feltet photo. En mottaker med "photo": "anna.jpg" får den filen. Uten får mottakeren kortets bilde. En logo kan være en lenke, et bilde kan ikke det.

Kampanjer og betaling

En kampanje er open, awaiting_payment, approved, printing eller sent. Det finnes ikke noe minimum: du betaler for kortene og brevene i kampanjen. Under 100 stykk koster hvert stykk det samme som ved 100. Når du godkjenner, får kontoeieren også en e-post med en betalingslenke, og etter betalingen fakturaen.

Grenser og feil

GrensePer nøkkel
Alle kall120 i minuttet
Lage eller endre kort, og kall med bilder300 per dag

Feil kommer som JSON med en message: 400 for feil i det du sendte, 401 for manglende eller feil nøkkel, 404 for noe som ikke finnes på kontoen din, 409 når statusen ikke tillater det, 429 når du er over en grense.