Direct mail API for DataZapp
Direct mail API for DataZapp files: download a list you built in DataZapp, such as homeowners or absentee owners, or the results of a Reverse Email Append on your own customers, and a short script sends the rows to Mailr, which prints and mails a postcard to each, 1,000 per request.
What to mail from DataZapp
| When this happens | Mail this |
|---|---|
| You download an absentee owner list from Real Estate Data > Property Owners | Your own 6x11 postcard to each owner at their mailing address, not the rental. |
| A Reverse Email Append comes back on customers you only had emails for | A win-back card to each matched address. (Win-back) |
| A new customer signs up with only an email, and your app calls DataZapp's reverse email API | A thank-you card when DataZapp finds a postal match. (First-order thank you) |
Set it up
- Build the list or run the append. In DataZapp's self-service platform, build a list and download it (for absentee owners: Real Estate Data > Property Owners, campaign type Postal, then the absentee filter), or upload your email list for Reverse Email/HEM Append, which returns a name, mailing address, city, state and ZIP for each email it matches.
- Point the script at the mailing address. Absentee owner records carry both the property address and the owner's mailing address. Set COLUMNS in datazapp_csv.py to the mailing address columns of your file, so the card reaches the owner and not the tenant.
- Clean an older file first. Mailr doesn't verify addresses or run NCOA. DataZapp's address hygiene does USPS CASS standardization and NCOALink with a 48-month lookback, with a 50,000-record minimum.
- Run it with a test key. Add your design from blank/6x11 in the Mailr kit (/downloads/mailr-kit.zip), set MAILR_API_KEY to your mlr_test_ key and run python datazapp_csv.py list.csv. Each address is mailed once even if the file lists it twice, rows Mailr would reject go to skipped.csv, and the rest go out 1,000 per request.
- Go live. Swap in your mlr_live_ key and run it again. Rows already in mailed.csv are skipped, so a rerun after a stop only sends what's left.
Scripts: DataZapp to Mailr
"""Mail a DataZapp download (a list you built, or Reverse Email Append results): python datazapp_csv.py list.csv
Match COLUMNS to the first row of your file. For absentee owners, point them at the owner's mailing address,
not the property address.
"""
import csv, hashlib, sys
from pathlib import Path
from mailr_batch import address, already_mailed, report, send
COLUMNS = {"first": "First Name", "last": "Last Name", "line1": "Mailing Address", "line2": "Mailing Address 2",
"city": "Mailing City", "state": "Mailing State", "zip": "Mailing Zip"}
DESIGN = {
"kind": "postcard",
"size": "6x11",
"front": Path("mail/spring-offer/front.html").read_text(), # from blank/6x11 in the Mailr kit
"back": Path("mail/spring-offer/back.html").read_text(), # uses {{first_name}}
"from": {"name": "Desert Roof Co", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004"},
}
done, rows, skipped, seen = already_mailed(), [], [], set()
with open(sys.argv[1], newline="", encoding="utf-8-sig") as f:
for r in csv.DictReader(f):
c = {k: (r.get(col) or "").strip() for k, col in COLUMNS.items()}
name = f"{c['first']} {c['last']}".strip() or "Current Resident"
to, why = address(name, c["line1"], c["city"], c["state"], c["zip"], c["line2"])
# A list row has no id of its own, so the record id is a hash of the address: one card per address.
a = to or c
rid = hashlib.sha256(f"{a['line1']}|{a.get('line2', '')}|{a['zip'][:5]}".upper().encode()).hexdigest()[:24]
if rid in done or rid in seen:
continue # mailed on an earlier run, or a duplicate row in this file
seen.add(rid)
if why:
skipped.append([rid, f"{c['line1']} {c['zip']}", why])
continue
rows.append((rid, to, {"first_name": (c["first"] or "Neighbor")[:14]}))
report(skipped)
send("datazapp-spring", DESIGN, rows)- DataZapp's API takes an HTTP POST with JSON, and the key goes in the body as ApiKey, not in a header. The endpoint URL comes from your account manager once API access is turned on, and API use is prepaid.
- Reverse email results carry FirstName, LastName, Address, City, State and ZIP (ZIP or ZIP+4), and DataZapp charges for matches only. Mailr takes ZIP+4 as is.
- A list row has no id of its own, so the script uses a hash of the address as the record id. The same household on next month's list is skipped as long as you keep mailed.csv.
- Rows with no name go out to Current Resident, and the card's {{first_name}} falls back to Neighbor.
- How you may use a list or appended data, including how many times you may mail it, is set by DataZapp's terms, not Mailr's.
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: Win-back (6x11), First-order thank you (6x9).
Questions
Does Mailr sell DataZapp lists?
No. Mailr doesn't sell lists or look up addresses. You buy the list or the append from DataZapp, and Mailr prints and mails to the addresses in it.
Which address do I mail for an absentee owner?
The owner's mailing address. The property address of a rental reaches the tenant, and a vacant property's reaches no one.
Can I send the win-back template to appended customers?
Yes. Set DESIGN to kind postcard, size 6x11, template tmpl_winback, your from address and a shared promo_code, and give each row first_name and last_product (14 and 22 characters at most). Use your customer id as the record id instead of the address hash.
Should I run NCOA first?
For a list you've had a while, yes. Mailr doesn't run NCOA; DataZapp's hygiene service does, and so do other providers.
What does it cost to mail?
One price per piece with printing and postage included: a 6x9 postcard is $0.89 on pay as you go and less on a plan, and the pricing page lists every size. Test pieces are free and never print.