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

Direct mail API for building permits and public records

Direct mail API for building permits and public records: a daily job pulls new permits, property sales, business licenses and liquor applications from city and county data, keeps the records that fit, and sends each one a postcard or letter through the Mailr API, once.

Who mails from public records

  • Contractors and home services. A new pool, addition or remodel permit tells a solar, security, landscaping, AV or cleaning company exactly who is building.
  • Suppliers to restaurants and bars. A liquor license application or a commercial build-out permit names a place before it opens: linens, POS, signage, AV, insurance and staffing all want that list.
  • Real estate and lending. County recorder data shows new owners and recent sales.
  • B2B services. New business licenses and state filings are a daily list of companies that need accounting, payroll, insurance and a website.

Where the records are

RecordWhere it’s publishedWhat it usually has
Building permitsCity open-data portals (often Socrata or ArcGIS), and the city’s permit search with a CSV exportProject description, valuation, contractor, parcel; sometimes the owner and owner mailing address
Parcels and ownersCounty assessor parcel dataOwner name and owner mailing address by parcel number
Property salesCounty recorder or assessorBuyer, sale date and price
New business licensesCity license data and state business filingsBusiness name, address, start date
Liquor license applicationsCity council agendas and state liquor departments, often as PDFsBusiness and owner entity, location, sometimes contact details
Contractor licensesState licensing boardsCompany, license class, address

In Arizona, for example, Mesa publishes building permits on Socrata and updates them daily, including permits filed but not yet issued, and Phoenix’s issued-permit search exports the owner, the owner’s address, the contractor and the valuation as a CSV. Every city is different, so map each source’s fields once.

Pull, filter, mail

  1. Pick sources. One dataset per city or county, through its official API or export.
  2. Pull daily. Ask only for records since the last run.
  3. Find the mailing address. Use the owner address on the record, or join the parcel number to the assessor’s data. Skip records without one.
  4. Filter. Keep the permit types, values and areas you serve.
  5. Clean the address. Standardize it (for example with Smarty); Mailr checks the format but doesn’t verify against USPS.
  6. Mail once. Send the day’s records as one batch of up to 1,000, with an Idempotency-Key, and store each record’s id.
# Pull yesterday's building permits from a city's Socrata open-data portal and mail each owner once.
# Socrata endpoints look like https://<portal>/resource/<dataset-id>.json and take SoQL query parameters.
import os, requests, datetime

PORTAL = "https://data.example-city.gov/resource/abcd-1234.json"   # the city's permits dataset
since = (datetime.date.today() - datetime.timedelta(days=1)).isoformat()

rows = requests.get(PORTAL, params={
    "$where": f"issued_date >= '{since}T00:00:00' AND valuation > 50000",
    "$order": "issued_date",
    "$limit": 1000,
}, timeout=60).json()

recipients = []
for r in rows:
    # Field names differ by city: map them once per source. Skip rows without a mailing address.
    if not r.get("owner_mailing_address"):
        continue
    recipients.append({
        "to": {"name": r["owner_name"][:40], "line1": r["owner_mailing_address"],
               "city": r["owner_city"], "state": r["owner_state"], "zip": r["owner_zip"][:5]},
        "merge": {"first_name": "Neighbor", "project": r.get("work_description", "")[:28]},
    })

if recipients:
    res = requests.post("https://api.mailr.dev/v1/batches",
        headers={"Authorization": f"Bearer {os.environ['MAILR_API_KEY']}",
                 # One key per source and day: re-running the job never mails twice.
                 "Idempotency-Key": f"permits-example-city-{since}"},
        json={"kind": "postcard", "size": "6x9", "front": FRONT_HTML, "back": BACK_HTML,
              "recipients": recipients[:1000]},
        timeout=60)
    res.raise_for_status()
    print(res.json()["id"], len(recipients), "postcards")

Traps we hit

  • Not every feed has an address. A city’s map layer may carry the project and coordinates but no owner; its permit search may carry the owner. They can even use different permit numbers, so don’t assume a join by number.
  • Feeds move. When a city switches permit systems, its open-data volume can drop overnight. Count records per day and alert when a source goes quiet.
  • “New” isn’t always new. Many liquor license applications are an ownership change at a place that has been open for years. Check before you send “congratulations on opening”.
  • The name on the record may be an agent. Applications are often filed by a licensing agent or an LLC, not the person who runs the place. Mail the business at its address.
  • Bot checks mean “not this way”. When a portal puts a CAPTCHA in front of its search, use its download, its API or a report from the agency instead of working around it.

What to send

  • New residential permit: a 6x9 card from the trade that comes next (“Building a pool? Here’s your fence, lighting and cleaning”).
  • Commercial build-out or liquor application: an 8.5x11 letter to the business at its new address, timed for when they buy.
  • New owner: a welcome card with your service and a code.
  • New business license: a letter offering what a new company needs in its first month.

Questions

Do building permits include the owner's mailing address?

Some do and many don't. A city's permit search or export may list the owner and the owner's mailing address; its open-data map layer may list only the project, the contractor and a parcel number. When there's a parcel number, the county assessor's parcel data usually has the owner's name and mailing address.

How fresh is the data?

Many city portals update daily, and some include permits that are filed but not yet issued. Run the pull once a day and mail only records you haven't seen before.

Does Mailr pull the records for me?

No. Mailr prints and mails what you send it. Your job pulls the records, decides who gets mail and sends the batch.

How do I avoid mailing the same record twice?

Store each record's id after you mail it, and send an Idempotency-Key built from the source and the record (or the source and the day for a daily batch). A re-run then returns the first response instead of mailing again.

What does it cost?

A 6x9 postcard is $0.89 on pay as you go, printing and postage included, so 400 new permits a month is $356.00. Plans lower the price per piece.

Can I use any public record I find?

Use the records through the source's official API, download or export, and follow its terms of use. Some portals put a bot check in front of their search; that's a sign to use their download or ask the agency for a report instead.

Ready to try it on your own data? Get a free test key, run the job against it, and nothing prints until you switch to live.

START SENDING

Put your first postcard in the mail

Create a key, send a test to yourself, and check the proof before anything prints.

  • 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.