Yotru API

Make postcards and letters, add recipients and approve campaigns from your own software. Every recipient is added to an open campaign for that card or letter, and nothing is posted until the campaign is approved and paid for. Mail goes to 34 countries: postcards to CA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS, IT, PT, IE, PL, CZ, SK, HU, RO, BG, HR, SI, GR, CY, MT, EE, LV, LT, LI, letters to all of them.

Authentication

Your first key is made when you open Settings → Integrations → API keys. Your email address has to be confirmed, and you have to be an owner or admin of the account. A key is shown once, so store it straight away. If you lose it, make a new one and revoke the old one.

Authorization: Bearer yk_live_...

The base URL is https://api.yotru.com. There is no test mode: every key is live, but you can freely make cards and add recipients. Only approving costs money.

Quickstart

1. Make a card. Anything you leave out comes from the template or is read from 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"}}'

A letter works the same way. This one goes to Germany, in German, with a printed back page:

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. Look at it. The image is what will be printed.

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

3. Add recipients. The first call opens a campaign; its id is 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. Approve. The answer has a payUrl; the campaign goes to print once that is paid. You can also approve and pay on the campaign page in your dashboard. The next recipients you add open a new campaign.

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

Endpoints

MethodPathWhat it does
POST/v1/cardsMake a card (JSON, or multipart with data and photo)
PATCH/v1/cards/{id}Change a card; only what you send changes. Approved campaigns keep their card
GET/v1/cards/{id}Read a card
GET/v1/cards/{id}/preview/frontThe card or letter as printed; also /back (cards, and letters with backSide)
POST/v1/recipientsAdd up to 1,000 recipients per call
GET/v1/batch?cardId=The campaign filling now for a card
GET/v1/campaigns/{id}Where a campaign stands
POST/v1/campaigns/{id}/approveApprove: returns the payment link

Cards

Every field is optional. The answer has id, printable, issues and problems. A card made in your dashboard works too: copy its id under Cards. Recipients sent with a card id go onto a campaign of their own for that card. A letter is made with the same call and has an id like a card.

FieldValues
nameWhat you call the card
productcard or letter; card if left out. Cards go to CA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS, IT, PT, IE, PL, CZ, SK, HU, RO, BG, HR, SI, GR, CY, MT, EE, LV, LT, LI; letters to every country. A card or letter cannot change into the other later
templateCards: introduction, offer, personal-note, proof, wave, photo, circle, facet, slant, studio, flow. Letters: letter-formal, letter-classic, letter-band, letter-plain
countryCA, US, NL, DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS, IT, PT, IE, PL, CZ, SK, HU, RO, BG, HR, SI, GR, CY, MT, EE, LV, LT, LI; NL if left out. Recipients must live in this country
languageen, nl, fr, de, es, sv, no, da, fi, is, it, pt, pl, cs, sk, hu, ro, bg, hr, sl, el, et, lv, lt; the country's own language if left out
backSideLetters to DE, FR, ES, BE, AT, LU, GB, CH, SE, NO, DK, FI, IS, IT, PT, IE, PL, CZ, SK, HU, RO, BG, HR, SI, GR, CY, MT, EE, LV, LT, LI: true prints a second page on the back, at extra cost per letter
websiteColours and logo are read from it when you do not send them
destinationUrlWhere the QR code goes; the website if left out
brandcompanyName, primaryColor, secondaryColor, logoUrl, font
textCards: greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine. Letters: headline, body, ctaLine (beside the QR code), signOff, backHeadline, backBody
contactwebsite, email, phone

A letter's body is printed as you send it, so start it with the greeting you want, for example Dear {firstName},. Tokens such as {firstName}, {lastName} and {companyName} are filled in per recipient. The answer also has product and language; previewBack is null for a letter with one page.

A card to a country that takes letters only, a language or country we do not know, and backSide outside those countries are refused with a 400 that says which field is wrong. The price is that of the country the card or letter is posted in, see pricing.

Recipients

A recipient needs a person or a company, and a complete address.

FieldValues
Personname, or firstName and lastName; also company, jobTitle
Addressstreet, houseNumber, addition, or addressLine1, addressLine2; also postcode, city, region, country
Otherreference (returned to you), email, phone, website, destinationUrl, customFields, photo

Each recipient comes back as accepted with an id, or refused with a reason: name, address, country, duplicate or photo. A recipient outside the card's country is refused with country; make a card or letter for their country instead. Send an Idempotency-Key header to make a repeated call safe.

Photos

Send photos as files with multipart/form-data and put the JSON in a field called data. At most 25 files of 10 MB per call and 32 MB in total. On a card the field is photo. A recipient with "photo": "anna.jpg" gets that file; without one they get the card's photo. A logo may be a link; a photo may not.

Campaigns and payment

A campaign is open, awaiting_payment, approved, printing or sent. There is no minimum: you pay for the cards on the campaign, and below 100 cards each one costs a little more than at 100, never more in total than 100 cards. Approving also emails the account owner a link to pay, and after payment the invoice.

Limits and errors

LimitPer key
All calls120 a minute
Making or changing cards, and calls with photos300 a day

Errors are JSON with a message: 400 for what you sent, 401 for a missing or wrong key, 404 for something not on your account, 409 when the state does not allow it, 429 when you are over a limit.