Direct mail API for Data Axle
Direct mail API for Data Axle records: the Scan API returns every place (business) or person that matches a filter, with street, city, state and ZIP, and a short script sends them to Mailr, which prints and mails a postcard to each, 1,000 per request. A list exported from Salesgenie works the same way.
What to mail from Data Axle
| When this happens | Mail this |
|---|---|
| A monthly job scans Places for a business category in your territory (sic_code_ids and zip filters) | Your own 6x9 postcard to each business, addressed to its primary contact when Data Axle has one. |
| An agency client picks ZIP codes and a business category in your app | A batch for that client's list, with the client's return address in from. |
| You export a lead list from Salesgenie | The same postcard to every row of the CSV. |
Set it up
- Get a token. Create one on the tokens page of your Data Axle Platform account settings. It doesn't expire, and every request sends it in the X-AUTH-TOKEN header. If your account has more than one contract, add contract to each request.
- Write the filter and check the count. Use the Filter DSL: relations such as equals, in and between, joined by and or or connectives. Run it through the Search API with limit 0 first; the response has the count and no records.
- Scan the records. POST /v1/places/scan (or /v1/people/scan) with the filter returns a scroll_id. GET /v1/places/scan/{scroll_id} then returns up to 200 records a page until a page comes back empty. Ask for each page within 60 seconds or the scroll_id expires.
- Pick the address. A place has a location address (street, suite, city, state, zip, zip_four) and, when it gets mail somewhere else, a mailing_address (a PO or RR box) with its own city, state and ZIP. The script mails the mailing address when there is one. A person has street, city, state and postal_code, with mailing_street filled in when the address is a PO box.
- Mail with a test key, then live. Add your design from blank/6x9 in the Mailr kit (/downloads/mailr-kit.zip), run the script with your mlr_test_ key, check skipped.csv and the dashboard, then switch to your mlr_live_ key. Records already in mailed.csv are skipped next time.
Scripts: Data Axle to Mailr
"""Mail every business that matches a Data Axle filter: DATA_AXLE_TOKEN=... python places_scan.py
The token comes from your Data Axle Platform account settings and doesn't expire.
"""
import os
from pathlib import Path
import requests
from mailr_batch import address, already_mailed, report, send
AXLE = "https://api.data-axle.com/v1"
H = {"X-AUTH-TOKEN": os.environ["DATA_AXLE_TOKEN"]}
FILTER = {"connective": "and", "propositions": [
{"relation": "in", "attribute": "sic_code_ids", "value": ["551102", "551103"]}, # new and used car dealers
{"relation": "in", "attribute": "zip", "value": ["85004", "85016", "85281", "85251"]},
]}
# 1. Start a scan, then page through it 200 records at a time.
scan = requests.post(f"{AXLE}/places/scan", headers=H, json={"filter": FILTER, "limit": 5000}, timeout=60)
scan.raise_for_status()
print(scan.json()["count"], "places match")
places = []
while True:
page = requests.get(f"{AXLE}/places/scan/{scan.json()['scroll_id']}", headers=H, timeout=60)
page.raise_for_status() # ask for each page within 60 seconds or the scroll_id expires
if not page.json():
break
places += page.json()
# 2. One postcard per place: to the mailing address when the place has one (a PO box), else the location.
DESIGN = {
"kind": "postcard",
"size": "6x9",
"front": Path("mail/dealer-card/front.html").read_text(), # from blank/6x9 in the Mailr kit
"back": Path("mail/dealer-card/back.html").read_text(), # uses {{first_name}} and {{company}}
"from": {"name": "Northwind", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004"},
}
done, rows, skipped = already_mailed(), [], []
for p in places:
if p["id"] in done:
continue
contact = p.get("primary_contact") or {}
person = f"{contact.get('first_name') or ''} {contact.get('last_name') or ''}".strip()
if p.get("mailing_address"):
line1, line2, city, state = p["mailing_address"], "", p.get("mailing_address_city"), p.get("mailing_address_state")
zip5, zip4 = p.get("mailing_address_zip") or "", p.get("mailing_address_zip_four")
else:
line1, line2, city, state = p.get("street"), p.get("suite") or "", p.get("city"), p.get("state")
zip5, zip4 = p.get("zip") or "", p.get("zip_four")
to, why = address(person or p["name"], line1, city, state, f"{zip5}-{zip4}" if zip4 else zip5, line2,
company=p["name"] if person else "")
if why:
skipped.append([p["id"], why])
continue
rows.append((p["id"], to, {"first_name": (contact.get("first_name") or "there")[:14], "company": p["name"][:24]}))
report(skipped)
send("axle-dealers-q1", DESIGN, rows)- The Search API returns up to 400 records a request and stops at an offset of 4,000. The Scan API is the way to pull every record that matches.
- Data Axle's SIC codes have six digits: 551102 is new car dealers and 551103 used car dealers, both under the government's 5511. Look codes up in the Lookup Tables.
- State comes back as a two-letter code, and zip and zip_four are separate fields; the script joins them into ZIP+4.
- A batch is all or nothing, so the script checks each address before sending and one bad record can't stop the other 999.
- Salesgenie exports CSV or Excel. Column names depend on your export, so match COLUMNS to its header row.
- Your Data Axle contract, not Mailr, sets how you may use the records for mail.
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.
Questions
Places or People?
Places are businesses and People are consumers. The scan works the same way on both: change /places/ to /people/ and read person_id, first_name, last_name, street, city, state and postal_code.
Why mail the mailing address instead of the location?
Data Axle collects a mailing address when a place receives mail somewhere other than its physical location, usually a PO box, so that's where its mail goes. Without one, the script uses the location address.
Does Mailr sell Data Axle data?
No. You license the data from Data Axle; Mailr prints and mails to the addresses you send and doesn't look any up.
Is there a Mailr app in Data Axle?
No. The script calls Data Axle's API and Mailr's REST API with your own keys. Mailr has no webhooks yet; list a batch's pieces with GET /v1/postcards?batch={id}.
What does it cost?
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.