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

Direct mail API for ZoomInfo

Direct mail API for ZoomInfo data runs on the work address: Enrich Contacts returns the street, city, state and zipCode where each person works, plus their company's primary address, and Mailr prints and mails a postcard to each contact, 1,000 per request.

What to mail from ZoomInfo

When this happensMail this
Your team picks the buyers at target accounts (person ids from Search Contacts or your own records)Your own 6x9 postcard to each of them at their work address.
A scheduled job picks up person ids added since the last runCards for the new ids only; mailed.csv skips the ones already sent.
You choose the accounts to invite to a dinner or field eventAn event invite to each buyer at the office. (Event invite)

Set it up

  1. Create a ZoomInfo app. Enterprise customers create one in the ZoomInfo Developer Portal with Create App; GTM.ai self-serve customers create it from the Developer tab. Choose the Client Credentials Flow, pick the integration user the calls are made as, and add the api:data:contact scope. Keep the client ID and secret on your server.
  2. Collect person ids. Find the people with Search Contacts, or use ZoomInfo ids you already store, and put one per line in person_ids.txt. ZoomInfo's best practice is to search first and then enrich by id, so the right records come back.
  3. Enrich and mail. zoominfo_api.py gets a token, enriches 25 ids per request with the fields in FIELDS, uses the work address when it has a street and ZIP and the company's primary address when it doesn't, and sends the rows to Mailr 1,000 per request with an Idempotency-Key built from the person ids.
  4. Check it with a test key. Run it with MAILR_API_KEY set to your mlr_test_ key. Contacts without a US address go to skipped.csv; the rest are in mailed.csv with their piece ids, and in your Mailr dashboard. Then switch to your mlr_live_ key.
  5. Or start from an export. If you export from ZoomInfo instead, match COLUMNS in zoominfo_csv.py to the header row of your file, since the headers depend on the fields you include.

Scripts: ZoomInfo to Mailr

"""Enrich ZoomInfo contacts by person id and mail each one at work: python zoominfo_api.py person_ids.txt
ZI_CLIENT_ID and ZI_CLIENT_SECRET come from a Developer Portal app with the api:data:contact scope.
Each record returned uses a ZoomInfo credit unless it's already under management.
"""
import os, sys, time
from pathlib import Path
import requests
from mailr_batch import address, already_mailed, report, send

ZI = "https://api.zoominfo.com/gtm"
token = requests.post(f"{ZI}/oauth/v1/token", data={"grant_type": "client_credentials"}, timeout=30,
                      auth=(os.environ["ZI_CLIENT_ID"], os.environ["ZI_CLIENT_SECRET"]))
token.raise_for_status()
H = {"Authorization": f"Bearer {token.json()['access_token']}", "Accept": "application/json"}
FIELDS = ["firstName", "lastName", "jobTitle", "street", "city", "state", "zipCode", "country",
          "companyName", "companyStreet", "companyCity", "companyState", "companyZipCode", "companyCountry"]


def enrich(person_ids):
    body = {"data": {"type": "ContactEnrich", "attributes": {
        "outputFields": FIELDS, "matchPersonInput": [{"personId": int(p)} for p in person_ids]}}}
    while True:
        r = requests.post(f"{ZI}/data/v1/contacts/enrich", headers=H, json=body, timeout=60)
        if r.status_code not in (429, 500, 504):
            r.raise_for_status()
            return [d for d in r.json()["data"] if d["type"] == "Contact"]  # NoMatch records aren't charged
        time.sleep(int(r.headers.get("Retry-After", "5")))


done = already_mailed()
ids = [line.strip() for line in open(sys.argv[1]) if line.strip() and line.strip() not in done]
DESIGN = {
    "kind": "postcard",
    "size": "6x9",
    "front": Path("mail/abm-card/front.html").read_text(),  # from blank/6x9 in the Mailr kit
    "back": Path("mail/abm-card/back.html").read_text(),    # uses {{first_name}} and {{company}}
    "from": {"name": "Northwind", "line1": "1 Example Way", "city": "Phoenix", "state": "AZ", "zip": "85004"},
}
rows, skipped = [], []
for i in range(0, len(ids), 25):  # Enrich Contacts takes up to 25 per request
    for d in enrich(ids[i:i + 25]):
        a, co = d["attributes"], d["attributes"].get("company") or {}
        # The contact's work address first, then the company's primary address.
        place = a if a.get("street") and a.get("zipCode") else co
        if place.get("country") not in ("United States", "USA", "US"):
            skipped.append([d["id"], "no US address"])  # Mailr mails US addresses only
            continue
        first, company = a.get("firstName") or "", co.get("name") or ""
        to, why = address(f"{first} {a.get('lastName') or ''}", place.get("street"), place.get("city"),
                          place.get("state"), place.get("zipCode"), company=company)
        if why:
            skipped.append([d["id"], why])
            continue
        rows.append((d["id"], to, {"first_name": first[:14], "company": company[:24]}))

report(skipped)
send("zoominfo-abm-q1", DESIGN, rows)
  • street, city, state and zipCode are the contact's work address. companyStreet, companyCity, companyState and companyZipCode come back under company and are the company's primary address.
  • Enrich Contacts takes up to 25 records per request. Each record returned uses a credit unless it's already under management; no match and errors aren't charged.
  • The API allows 25 requests per second by default, per tenant, with hourly and daily limits on top. A 429 carries Retry-After in seconds; the script waits it out, and also retries 500 and 504.
  • Client credentials tokens are short-lived (expires_in is in seconds), so the script asks for a new one each run.
  • If your account can't return a field, Lookup Enrich Fields shows which ones it can; your ZoomInfo account manager sells access to the rest.
  • ZoomInfo's terms, not Mailr's, set how you may use ZoomInfo data 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.

Templates that fit: Event invite (5.5x8.5).

Questions

Does ZoomInfo have home addresses?

Enrich Contacts documents a contact's work address and the company's primary address, and this page uses those. People are mailed at work.

Which address does the script use?

The contact's work address when it has a street and ZIP, otherwise the company's primary address. Change the place line to always use one or the other.

How many contacts can one run mail?

As many as your ZoomInfo credits and rate limits allow: 25 per enrich request and 1,000 per Mailr request. A run of 5,000 ids is 200 enrich calls and 5 Mailr batches.

Is there a Mailr app in ZoomInfo?

No. The script calls both REST APIs with your own credentials. Mailr has no webhooks yet; check status 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.
ZOOMINFO

Mail from ZoomInfo 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.