Direct mail API for retail stores
Direct mail API for retail stores: when a shopper joins the loyalty program, your POS webhook or nightly sync makes one API call and a welcome card is printed and mailed. Shoppers with no purchase in 90 days go out monthly as a win-back batch of up to 1,000, a new store's neighborhood gets the opening date, and window posters and bag stickers are ordered with the same API key.
Who builds this
The developer or ops lead at a multi-location retailer who already syncs the point of sale into a customer table, the agencies that run marketing for independent boutiques, garden centers, bike shops, bookstores and gift shops, the app developers building on POS platforms who want mail next to email and SMS, and owners building their own tools with Claude Code or Cursor. They connect loyalty sign-ups, sales and customer profiles to mail, run monthly win-back and birthday batches from purchase history, and reorder posters, counter cards and stickers for each store.
Who to mail
| Who | Why paper works | What to send |
|---|---|---|
| Loyalty members | They gave you an address to earn points, and a card about their rewards or a members-only night is a fair trade for it. | A 6x9 welcome card when they join, and a 5.5x8.5 invite to a members-only shopping night. |
| VIP spenders | Your best customers already know the staff by name, and a piece signed by the owner feels like the store, not a marketing list. | An 11x17 lookbook folded to 8.5x11 when the new season lands, with first pick before it goes on the floor. |
| Lapsed shoppers | Someone who stopped coming in may have unsubscribed from email long ago, but still lives a short drive away. | A 6x11 win-back card naming what they bought last, with an offer that expires. |
| Birthday customers | A birthday card from a local shop is still a pleasant surprise, and it gives them a reason to stop in that week. | A 4x6 card in their birth month with a gift at the register. |
| First-time buyers | A thank-you after the first purchase is what turns one visit into a second. | A 6x9 thank-you card with a code for the next visit. |
| Neighborhood households for a grand opening | People who live near a new store are the ones who will walk in, and a mailer reaches them before the sign goes up. | A 5.5x8.5 card with the opening date, hours and an opening-week offer, to the addresses you have or buy for the surrounding ZIP codes. |
What to mail, and when
| When this happens | Mail this | Price |
|---|---|---|
| A customer makes their first purchase | A thank-you card with a code for the next visit. (6x9 postcard, First-order thank you) | $0.89 |
| A shopper joins the loyalty program | A welcome card with how points work and the first reward. (6x9 postcard) | $0.89 |
| A customer's birthday month starts | A birthday card with a gift at the register that week. (4x6 postcard) | $0.85 |
| A customer's lifetime spend crosses your VIP threshold | A thank-you card signed by the owner with a standing VIP perk. (6x9 postcard) | $0.89 |
| A customer hasn't bought anything in 90 days | A win-back card naming their last purchase, sent once a month as a batch. (6x11 postcard, Win-back) | $0.99 |
| A new season or collection arrives, for your top customers by spend | A lookbook folded to 8.5x11 with four new arrivals and first-pick hours. (11x17 folded mailer, Seasonal lookbook) | $1.39 |
| A new location opens, for households in the ZIP codes around it | A grand opening invite with the date, the hours and an opening-week offer. (5.5x8.5 postcard, Event invite) | $0.89 |
What to print
Printed and picked up free in Phoenix or shipped UPS Ground, ordered with POST /v1/prints.
| Piece | Used for | Price |
|---|---|---|
| 24x36 poster | Window posters for a sale, a new season or the grand opening, from one poster. | $19.20 |
| 12x18 poster or menu board | Counter, fitting-room and endcap posters, one side. | $0.88, from 100 |
| 4x9 rack card | Counter cards for the loyalty program, gift cards, services (alterations, repairs, classes) and events. | $0.26, from 100 |
| 5x7 table card | Register signs with the loyalty sign-up QR code, gift wrapping or this week's event. | $0.29, from 100 |
| 8.5x11 flyer | Flyers for trunk shows, workshops, sidewalk sales and neighborhood boards. | $0.53, from 100 |
| 3x3 vinyl sticker | Bag and box seal stickers and giveaway stickers with the logo, cut square or circle. | $0.64, from 50 |
Systems to connect
- Point of sale: Shopify POS, Square, Lightspeed, Clover. A webhook or a nightly sync. Shopify sends orders/create for in-store sales too (source_name is pos); Square sends customer.created and customer.updated with the address and birthday when set, and loyalty.account.created when someone joins; Lightspeed Retail (X-Series) sends sale.update and customer.update; Clover sends C: (customer) and O: (order) updates. Card payments alone don't carry an address, so mail customers whose profile has one.
- Shopify. Stores that sell online and in person use the same customer and order webhooks for both; the guide covers first-order thank-yous and win-backs.
- Email and SMS marketing: Klaviyo, Mailchimp, HubSpot. If your segments (VIPs, lapsed, birthdays) already live in a marketing tool, export the segment with addresses, or call Mailr from a workflow step where the tool has one.
- Zapier or n8n. Connect a POS trigger, a form or a spreadsheet to Mailr with one HTTP step.
- No software, or something else. Export a spreadsheet of customers with addresses from your POS, one row each, and send it as a batch of up to 1,000.
Code: a loyalty welcome, monthly win-back cards and grand opening prints
// Call this from whatever you have: a POS webhook, a nightly sync or a loyalty sign-up form.
// member is your own customer record: id, name and mailing address.
import { readFileSync } from "node:fs";
const FRONT = readFileSync("mail/loyalty-welcome/front.html", "utf8"); // 6x9, uses {{first_name}} and {{store}}
const BACK = readFileSync("mail/loyalty-welcome/back.html", "utf8");
export async function mailLoyaltyWelcome(member) {
const a = member.address;
if (!a?.line1) return null; // no address on the profile: nothing to mail
const res = await fetch("https://api.mailr.dev/v1/postcards", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `loyalty-welcome-${member.id}`,
},
body: JSON.stringify({
size: "6x9",
front: FRONT,
back: BACK,
to: { name: member.name.slice(0, 40), line1: a.line1, line2: a.line2 || undefined, city: a.city, state: a.state, zip: a.zip },
from: member.homeStore.returnAddress, // each store's own return address
merge: { first_name: member.firstName.slice(0, 14), store: member.homeStore.name },
description: `Loyalty welcome ${member.id}, ${member.homeStore.name}`,
}),
});
const card = await res.json();
if (!res.ok) throw new Error(card.error.message);
return card.id; // save it on the customer so a later sync skips them
}What it costs
Win-back cards to 1,500 lapsed shoppers: 1,500 6x11 postcards at $0.99 each is $1,485.00 on pay as you go, or $1,065.00 on the Agency plan, printing and postage included. Customers with an address on file and no purchase in 90 days, sent as a batch of 1,000 and a batch of 500 with tmpl_winback and each shopper's last purchase in last_product. Test pieces are free. All prices.
Questions
Where do retail customers' mailing addresses come from?
Loyalty and birthday-club sign-ups that ask for one, customer profiles staff fill in at the register, ship-to addresses on online or ship-from-store orders, and special orders. A card payment alone doesn't give you an address.
Can each store send its own mail?
Yes. Put the store's return address in from on each request (or save one default in Settings), and name the store in description so you can split pieces and costs by location.
What do posters, rack cards and stickers cost?
Pay as you go: posters $9.60 (18x24) and $19.20 (24x36) from one, 12x18 posters $0.88 from 100, 4x9 rack cards $0.26 and 5x7 counter cards $0.29 from 100, and vinyl stickers $0.48 to $0.72 (2x2 to 3.5x3.5) from 50. Pickup in Phoenix is free; UPS Ground to the lower 48 is priced by destination.
Can I mail every household near a new store?
Mailr mails the addresses you send. It doesn't sell lists or offer every-door saturation mail, so use your own customers in those ZIP codes or buy a residential list for them, and send it in batches of up to 1,000.
How does our code know what was mailed?
Each create returns an id, and each batch returns a pieces_url. There are no webhooks yet, so poll GET /v1/postcards/{id} for the status and its events, or GET /v1/postcards?batch={batch id} for a whole win-back run.
Does Mailr clean up addresses from the POS?
No. Mailr doesn't verify addresses or run NCOA, and it needs a two-letter state and a 5-digit or ZIP+4 code. Fix typos in the POS or your export before sending; a batch with one bad ZIP code is rejected as a whole, so nothing half-mails.