Direct mail API for Apollo
Direct mail API for Apollo lists starts with the right address: Apollo gives a contact's city, state and country, and the street and postal code belong to their company's account. Join the two exports on account id, or pull both from Apollo's API, and Mailr prints and mails a postcard to each contact at the office, 1,000 per request.
What to mail from Apollo
| When this happens | Mail this |
|---|---|
| You add the buyers at your target accounts to an Apollo list | Your own 6x9 postcard to each of them at the company address. |
| A nightly job finds contacts added to the list since the last run (Search for Contacts with contact_label_ids) | A card for each new contact only; contacts already in mailed.csv are skipped by their Apollo contact id. |
| You pick the accounts to invite to a dinner or field event | An event invite addressed to each buyer at the office. (Event invite) |
Set it up
- Export the contacts. In Apollo, go to Search > People, filter to your list, select the contacts and click Export. In Edit export CSV settings, include First name, Last name, Company name, Apollo contact id and Apollo account id. Exporting saved contacts doesn't use credits; net-new people from search are saved first, and each one with a verified email uses a credit.
- Export their accounts. The contact export has Company address, city, state and country but no postal code. Go to Companies, select the same accounts, click Export and include Apollo account ID, Company address, Company city, Company state, Company postal code and Company country. A field left out of the export settings comes through blank.
- Make the design. Copy blank/6x9/front.html and back.html from the Mailr kit (/downloads/mailr-kit.zip) into mail/abm-card/, add your design, and put {{first_name}} and {{company}} where the names go. Leave the keep-clear zone empty: Mailr prints the address, postage and barcode there.
- Run the script with a test key. Set MAILR_API_KEY to your mlr_test_ key and run python apollo_csv.py contacts.csv accounts.csv. Rows it can't mail (no US address, no ZIP, a state it can't read) go to skipped.csv with the reason; the rest go out 1,000 per request and land in mailed.csv with their piece ids.
- Go live, or run it nightly. Swap in your mlr_live_ key and run it again; rows in mailed.csv are skipped. To mail new list members every night, schedule apollo_api.py instead: it reads the list and the company addresses through the API, so there's nothing to export.
Scripts: Apollo to Mailr
"""Mail Apollo contacts at their company's address: python apollo_csv.py contacts.csv accounts.csv
contacts.csv: People export with First name, Last name, Company name, Apollo contact id, Apollo account id.
accounts.csv: Companies export with Apollo account ID, Company address, Company city, Company state,
Company postal code, Company country. The contact export has no postal code, so the two are joined on account id.
"""
import csv, sys
from pathlib import Path
from mailr_batch import address, already_mailed, report, send
def rows_of(path):
# Header names differ in case between Apollo's exports ("Apollo account id" / "Apollo account ID").
with open(path, newline="", encoding="utf-8-sig") as f:
for r in csv.DictReader(f):
yield {k.strip().lower(): (v or "").strip() for k, v in r.items() if k}
accounts = {a["apollo account id"]: a for a in rows_of(sys.argv[2])}
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"},
}
done, rows, skipped = already_mailed(), [], []
for c in rows_of(sys.argv[1]):
cid, acct = c["apollo contact id"], accounts.get(c["apollo account id"])
if cid in done:
continue
if not acct:
skipped.append([cid, "account not in accounts.csv"])
continue
if acct["company country"] not in ("United States", "US", "USA"):
skipped.append([cid, f"country {acct['company country']!r}"]) # Mailr mails US addresses only
continue
to, why = address(f"{c['first name']} {c['last name']}", acct["company address"], acct["company city"],
acct["company state"], acct["company postal code"], company=c["company name"])
if why:
skipped.append([cid, why])
continue
rows.append((cid, to, {"first_name": c["first name"][:14], "company": c["company name"][:24]}))
report(skipped)
send("apollo-abm-q1", DESIGN, rows)- Apollo's person records have city, state and country only; the street address and postal code are the company's (street_address and postal_code in the API). So the mail goes to the office.
- Company records use full state names such as California. Mailr needs two-letter codes, so mailr_batch.py converts them. Postal codes can be ZIP+4, which Mailr takes as is.
- Apollo's API limits are per team, counted per minute, hour and day, and set by your plan. A 429 comes with retry-after in seconds, which the script waits out.
- Search for Contacts uses no credits and shows up to 50,000 records, 100 a page. Bulk Company Enrichment takes 10 domains per call and uses 1 credit per company; the script only enriches companies of contacts not mailed yet.
- Spreadsheet apps can reformat ZIP codes and long ids. Run the script on the CSV as downloaded, or import those columns as text if you edit the file first.
- Apollo's terms, not Mailr's, set how you may use Apollo 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 Apollo have home addresses?
Not in the fields Apollo documents for its exports: a contact has City, State and Country, and the street and postal code belong to the company. This page mails people at work.
Does this use Apollo credits?
Exporting saved contacts doesn't. Net-new people from search use a credit each when they're saved with a verified email. In the API script, Search for Contacts uses none, and Bulk Company Enrichment uses 1 credit per company.
Is there a Mailr app in Apollo?
No. The scripts call Apollo'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} to see their status.
What if two contacts work at the same company?
Each gets their own card at the company address, addressed by name. To send one card per company, keep only the first contact for each Apollo account id before sending.
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.