Direct mail API for developers and growth teams. Read the docs →

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 happensMail 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 appA batch for that client's list, with the client's return address in from.
You export a lead list from SalesgenieThe same postcard to every row of the CSV.

Set it up

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

The code on this page is written against the Mailr API as it works today. Test it with your test key first; nothing prints until you use a live key.
DATA AXLE

Mail from Data Axle today

Get a free test key, send one postcard to yourself and watch it move through every status.

  • Postcards, flats and folded mailers
  • A proof before anything prints
  • Free test mode: nothing prints, nothing charges
  • A status for every piece

Get the price sheet by email

Every postcard, letter, mailer and print product on every plan, postage included.

We’ll email you the price sheet. By continuing you agree to the Terms and Privacy Policy.

Download the template kit?

mailr-kit.zip · about 310 KB · 65 text files

Only HTML, JSON and Markdown files. No programs, scripts or macros, nothing that installs or runs.