Yotru API

Make postcards, add recipients and approve campaigns from your own software. Every recipient is added to an open campaign for that card, and nothing is posted until the campaign is approved and paid for.

Authentication

Your first key is made when you open Settings → API. 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"}}'

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

Method	Path	What it does
POST	`/v1/cards`	Make 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/front`	The card as printed; also /back
POST	`/v1/recipients`	Add 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}/approve`	Approve: 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.

Field	Values
`name`	What you call the card
`template`	introduction, offer, personal-note, proof, wave, photo, circle, arc, facet, slant
`country`	NL, CA or US
`language`	nl or en
`website`	Colours and logo are read from it when you do not send them
`destinationUrl`	Where the QR code goes; the website if left out
`brand`	companyName, primaryColor, secondaryColor, logoUrl, font
`text`	greeting, headline, subhead, bullets, offer, salutation, body, backBullets, signOff, ctaLine, backCtaLine
`contact`	website, email, phone

Recipients

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

Field	Values
Person	name, or firstName and lastName; also company, jobTitle
Address	street, houseNumber, addition, or addressLine1, addressLine2; also postcode, city, region, country
Other	reference (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. 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 the 100-card price per card. Approving also emails the account owner a link to pay, and after payment the invoice.

Limits and errors

Limit	Per key
All calls	120 a minute
Making or changing cards, and calls with photos	300 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.