Developers · API v1

Send postcards from your code.

Point the Relay API at a campaign and every record you post becomes a printed, tracked piece of mail: you get a per-recipient QR and scan URL back on the spot, and delivery and scan data as it happens.

For developers Non-technical version

Common questions

How many addresses can I send, and how fast?

Up to 500 addresses per request, and up to 100 requests per minute, so as many as 50,000 records a minute. Every address is checked individually; the good ones are accepted and the bad ones come back with a reason, without blocking the rest.

How long does it take to generate QR codes via the API?

The tracked QR link and scan URL come back instantly, in the same response that accepts the record. The QR image file behind the link is generated within a few minutes (batches render at hundreds per minute), and the link never changes.

How long does it take for a QR scan to register?

Effectively real time. The scan is recorded the moment the redirect fires, tied to the exact person who scanned, and shows on the campaign report within seconds. Your system can read the same scan counts back through the API.

Do you verify addresses? What about NCOA?

Address verification: yes, as an option you turn on per campaign. Every address is checked against USPS data, standardized to ZIP+4, and anything that can't be verified is held for your decision before a single piece prints. NCOA (forwarding for people who moved): not today. Our print partner also runs its own deliverability check before printing.

Do I have to print and mail through Relay?

No. Every record gets its tracked QR either way. You can have Relay print and mail full-service, or take the QR files into your own print workflow: scans track identically in both cases.

What do I get back, and how do I match it to my records?

Every response row echoes the recipient's name and address plus its position in your list, so matching is exact even without IDs. Each record carries Relay's mailing ID, a tracking code, the QR image URL, and the scan URL; if you sent your own customer ID it's echoed back and leads every export. Store one of those IDs on your side and you can look up delivery and scans for that person any time.

Something else?

Volume, timelines, a workflow we haven’t described: ask a person.

Talk to us →

What actually happens

Step 1

Your system sends addresses

A list of names and mailing addresses, up to 500 at a time, posted to Relay by your developer or your CRM.

→↓

Step 2

Relay checks every record

Required fields present, state and ZIP shaped right, no duplicate customer IDs within the campaign. Bad records come back with reasons; good ones proceed.

→↓

Step 3

Every person gets their own tracked QR, instantly

The response hands back a QR link and scan URL per record, tied to that exact person and address.

↓

Step 4 · Option A

Relay prints and mails

If the campaign is live with an approved design, pieces print with each person's QR on the artwork and mail automatically. Delivery is tracked through USPS.

Step 4 · Option B

Or you print (QR only)

Skip our printing entirely: download the QR files or use the hosted image URLs in InDesign, Canva, or any print workflow. Scans track the same.

↓

Step 5

Results flow back by themselves

Every scan resolves to the person who scanned. Delivery states update as USPS moves the mail. It all lands on the campaign report, and your system can read it back through the same API.

What each record needs

Full name	Who the piece is addressed to
Street address	Line 1; unit or suite is optional
City
State	Two letters, like MI or VA
ZIP code	5 digits; ZIP+4 accepted

Optional, but bring them if you can

Your customer ID: echoed back on every record, leads every export, and switches on duplicate protection within the campaign.

A destination link: where that person’s QR sends them. Without one, the campaign’s default landing page is used.

Get your API key

Included with every Relay account; rate limits can be raised per key on request.