Yotru API
Skapa vykort och brev, lägg till mottagare och godkänn kampanjer från ditt eget system. Varje mottagare läggs till i en öppen kampanj för det kortet eller brevet, och ingenting skickas förrän kampanjen är godkänd och betald. Post går till 16 länder: vykort till CA, US, NL, DE, GB, brev till alla.
Autentisering
Din första nyckel skapas när du öppnar Inställningar → Integrationer → API-nycklar. Din e-postadress måste vara bekräftad, och du måste vara ägare eller administratör för kontot. En nyckel visas bara en gång, så spara den direkt. Tappar du bort den skapar du en ny och återkallar den gamla.
Authorization: Bearer yk_live_...Bas-URL:en är https://api.yotru.com. Det finns inget testläge: alla nycklar är skarpa, men du kan fritt skapa kort och lägga till mottagare. Bara godkännandet kostar pengar.
Snabbstart
1. Skapa ett kort. Det du utelämnar kommer från mallen eller läses från 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"}}'Ett brev fungerar på samma sätt. Det här går till Tyskland, på tyska, med en tryckt sida på baksidan:
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. Titta på det. Bilden är det som trycks.
curl https://api.yotru.com/v1/cards/CARD_ID/preview/front \
-H "Authorization: Bearer $YOTRU_KEY" -o front.png3. Lägg till mottagare. Det första anropet öppnar en kampanj. Dess ID finns 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. Godkänn. Svaret innehåller en payUrl, och kampanjen går till tryck när den är betald. Du kan också godkänna och betala på kampanjsidan i instrumentpanelen. Nästa mottagare du lägger till öppnar en ny kampanj.
curl -X POST https://api.yotru.com/v1/campaigns/CAMPAIGN_ID/approve \
-H "Authorization: Bearer $YOTRU_KEY"Endpoints
| Metod | Sökväg | Vad den gör |
|---|---|---|
| POST | /v1/cards | Skapa ett kort (JSON, eller multipart med data och photo) |
| PATCH | /v1/cards/{id} | Ändra ett kort. Bara det du skickar ändras. Godkända kampanjer behåller sitt kort |
| GET | /v1/cards/{id} | Läs ett kort |
| GET | /v1/cards/{id}/preview/front | Kortet eller brevet som det trycks. Även /back (vykort, och brev med backSide) |
| POST | /v1/recipients | Lägg till upp till 1 000 mottagare per anrop |
| GET | /v1/batch?cardId= | Kampanjen som fylls just nu för ett kort |
| GET | /v1/campaigns/{id} | Status för en kampanj |
| POST | /v1/campaigns/{id}/approve | Godkänn: returnerar betalningslänken |
Kort
Alla fält är valfria. Svaret innehåller id, printable, issues och problems. Ett kort som du har skapat i instrumentpanelen fungerar också: kopiera dess ID under Brev. Mottagare som skickas med ett korts ID hamnar i en egen kampanj för det kortet. Ett brev skapas med samma anrop och får ett ID precis som ett kort.
| Fält | Värden |
|---|---|
name | Vad du kallar kortet |
product | card eller letter; card om det utelämnas. Vykort går till CA, US, NL, DE, GB, brev till alla länder. Ett vykort kan inte bli ett brev senare, och tvärtom |
template | Vykort: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio. Brev: 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 om det utelämnas. Mottagarna måste bo i det här landet |
language | en, nl, fr, de, es, sv, no, da, fi, is; landets eget språk om det utelämnas |
backSide | Brev till DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS: true trycker en andra sida på baksidan, mot en extra kostnad per brev |
website | Färger och logga läses härifrån när du inte skickar dem |
destinationUrl | Vart QR-koden leder; webbplatsen om det utelämnas |
brand | companyName, primaryColor, secondaryColor, logoUrl, font |
text | Vykort: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Brev: headline, body, ctaLine (bredvid QR-koden), signOff, backHeadline, backBody |
contact | website, email, phone |
Ett brevs body trycks precis som du skickar den, så börja med den hälsning du vill ha, till exempel Hej {firstName},. Token som {firstName}, {lastName} och {companyName} fylls i per mottagare. Svaret innehåller också product och language. previewBack är null för ett brev med en sida.
Ett vykort till ett land som bara tar emot brev, ett språk eller land som vi inte känner till, och backSide utanför de länderna avvisas med 400 och ett meddelande om vilket fält som är fel. Priset är det som gäller i landet där kortet eller brevet postas, se priser.
Mottagare
En mottagare behöver en person eller ett företag, och en fullständig adress.
| Fält | Värden |
|---|---|
| Person | name, eller firstName och lastName; även company, jobTitle |
| Adress | street, houseNumber, addition, eller addressLine1, addressLine2; även postcode, city, region, country |
| Övrigt | reference (skickas tillbaka till dig), email, phone, website, destinationUrl, customFields, photo |
Varje mottagare kommer tillbaka som accepted med ett id, eller som refused med ett skäl: name, address, country, duplicate eller photo. En mottagare utanför kortets country avvisas med country. Skapa i stället ett kort eller brev för mottagarens land. Skicka en Idempotency-Key-header så blir ett upprepat anrop säkert.
Foton
Skicka foton som filer med multipart/form-data och lägg JSON i ett fält som heter data. Högst 25 filer på 10 MB per anrop och 32 MB totalt. På ett kort heter fältet photo. En mottagare med "photo": "anna.jpg" får den filen. Utan det får mottagaren kortets foto. En logga får vara en länk, ett foto får inte det.
Kampanjer och betalning
En kampanj är open, awaiting_payment, approved, printing eller sent. Det finns inget minimum: du betalar för korten och breven i kampanjen. Under 100 stycken kostar varje styck samma som vid 100. När du godkänner får kontots ägare också ett mejl med en betalningslänk, och efter betalningen fakturan.
Gränser och fel
| Gräns | Per nyckel |
|---|---|
| Alla anrop | 120 per minut |
| Skapa eller ändra kort, och anrop med foton | 300 per dag |
Fel returneras som JSON med ett message: 400 för fel i det du skickade, 401 för en saknad eller felaktig nyckel, 404 för något som inte finns på ditt konto, 409 när statusen inte tillåter det, 429 när du har passerat en gräns.