Direct mail API for Smarty
Direct mail API for Smarty users is two calls: Smarty's US Street API checks an address against USPS data and returns it standardized, and Mailr prints and mails to that address. Mailr doesn't verify addresses itself, so this check is what keeps a mistyped or vacant address from being printed and paid for.
What to mail from Smarty
| When this happens | Mail this |
|---|---|
| A customer enters a shipping address at checkout | A thank-you card to the address Smarty confirms; the order is held for review when it can't. (First-order thank you) |
| A list arrives from Apollo, ZoomInfo, a list vendor or an old CRM export | Only the addresses Smarty confirms go to Mailr, 1,000 per batch; the rest land in skipped.csv with the reason. |
| Smarty marks an address vacant (dpv_vacant is Y) | Nothing. The record is held, so you don't pay to print a card nobody collects. |
Set it up
- Keep secret keys on the server. Create a secret key pair (auth-id and auth-token) in your Smarty account and use it from your server. Embedded keys are for browsers: they only allow GET and are throttled.
- Send the address. GET https://us-street.api.smarty.com/street-address with street, secondary, city, state and zipcode checks one address. A POST takes a JSON array of up to 100 (32 KB at most); give each an input_id, which comes back on its match.
- Read the result. An empty array means no match. In analysis, dpv_match_code Y is confirmed; S is confirmed after dropping the apartment or suite you sent; D means the building needs an apartment or suite number that's missing; N is not confirmed. dpv_vacant Y means USPS lists the address as vacant.
- Send the standardized address to Mailr. line1 is delivery_line_1, line2 is delivery_line_2 when there is one, city is components.city_name, state is components.state_abbreviation, and zip is components.zipcode plus plus4_code. Use the order or record id in the Idempotency-Key.
- Hold the rest. Ask the customer for a missing suite number, or leave list rows in skipped.csv to fix. Test the whole path with your Mailr test key, which never prints.
Code: Smarty, then Mailr
// Node 18+, on your server. SMARTY_AUTH_ID, SMARTY_AUTH_TOKEN (Smarty secret keys) and MAILR_API_KEY.
// Check the address with Smarty's US Street API, then mail the standardized address with Mailr.
const SMARTY = "https://us-street.api.smarty.com/street-address";
export async function thankYouCard(order) {
const q = new URLSearchParams({
"auth-id": process.env.SMARTY_AUTH_ID,
"auth-token": process.env.SMARTY_AUTH_TOKEN,
street: order.address.line1,
secondary: order.address.line2 ?? "",
city: order.address.city,
state: order.address.state,
zipcode: order.address.zip,
candidates: "1",
});
const res = await fetch(`${SMARTY}?${q}`);
if (!res.ok) throw new Error(`Smarty ${res.status}`); // 401 bad keys, 402 no subscription, 429 rate limit
const [match] = await res.json(); // [] means USPS data has no match (the default strict mode)
if (!match) return { status: "held", reason: "address not found" };
const { dpv_match_code: dpv, dpv_vacant: vacant } = match.analysis;
if (dpv === "D") return { status: "held", reason: "apartment or suite number missing" };
if (dpv !== "Y" && dpv !== "S") return { status: "held", reason: `not confirmed (${dpv || "no match"})` };
if (vacant === "Y") return { status: "held", reason: "USPS lists the address as vacant" };
const c = match.components;
const res2 = await fetch("https://api.mailr.dev/v1/postcards", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `thank-you-${order.id}`, // a retry within 24 hours returns the same postcard
},
body: JSON.stringify({
size: "6x9",
template: "tmpl_thank_you",
to: {
name: order.name.slice(0, 40),
line1: match.delivery_line_1,
...(match.delivery_line_2 ? { line2: match.delivery_line_2 } : {}),
city: c.city_name,
state: c.state_abbreviation,
zip: c.plus4_code ? `${c.zipcode}-${c.plus4_code}` : c.zipcode,
},
from: { name: "Acme Outdoor", line1: "1 Example Way", city: "Phoenix", state: "AZ", zip: "85004" },
merge: { first_name: order.firstName.slice(0, 14), promo_code: "THANKS15" },
}),
});
const card = await res2.json();
if (res2.status !== 201) return { status: "error", reason: card.error?.message, field: card.error?.field };
return { status: "mailed", id: card.id, rdi: match.metadata.rdi }; // save card.id on the order
}- A POST takes up to 100 addresses and 32 KB; a larger body gets a 413. A 401 means wrong or inactive keys, 402 no active subscription, and 429 too many requests for your plan.
- The default match mode, strict, returns only valid addresses. Send match=invalid to get invalid ones back too, with dpv_match_code N, if you want to report why.
- metadata.rdi says Residential or Commercial, which helps split business mail from consumer mail.
- input_id holds up to 36 characters. The list script matches results by input_index, so longer record ids still line up.
- A confirmed address is a real USPS delivery point, not proof that the person still lives there. Mailr doesn't run NCOA; use a provider that offers NCOALink for people who moved.
What it costs
Each live piece is paid from your Mailr balance, printing and postage included: a 4x6 postcard is $0.85, a 6x9 $0.89 and an 8.5x11 letter $0.95 on pay as you go, less on a plan. Test pieces are free. All prices.
Templates that fit: First-order thank you (6x9).
Questions
Why verify when Mailr prints whatever I send?
Because it does. Mailr doesn't verify addresses, and a live piece is paid from your balance when it's created, deliverable or not.
Which dpv_match_code should I mail?
Y, and S if you accept that the apartment or suite you sent wasn't recognized. Hold D, where a needed apartment or suite number is missing, and N.
Can I call Smarty from the browser?
With an embedded key, for GET requests only, and those are throttled. The Mailr request needs your secret Mailr key, so it always runs on your server.
Does Smarty tell me if someone moved?
The US Street API checks the address against USPS data, not who lives there. Mailr doesn't run NCOA either.
What does it cost to mail?
A 6x9 postcard is $0.89 on pay as you go, printing and postage included, and less on a plan. Test pieces are free and never print.