Direct mail API for Clay
Direct mail API for Clay: an HTTP API column posts each enriched row to Mailr, and Mailr prints a postcard to that person's office, mails it with USPS and returns a piece id into the row. For a whole table, export it as a CSV and a short script sends 1,000 rows per request.
What to mail from Clay
| When this happens | Mail this |
|---|---|
| A buyer at a target account lands in the table with a full office address (a conditional run on the Zip column) | An invitation to your dinner or event, addressed to them at the office. (Event invite) |
| A new row is added to the table while auto-run is on | The HTTP API column runs for that row and mails its card. |
| You finish enriching a table for an outbound campaign | Your own 6x9 postcard design to every row, sent from the exported CSV 1,000 rows per request. |
Set it up
- Put a mailable address in the row. Mailr needs a street, city, two-letter state and ZIP in their own columns, from an enrichment that returns a full office address or from your CRM. Mailr mails US addresses only and doesn't verify them, so check them first if the source isn't standardized (the Smarty page shows how). Then add a Formula column named Mail key that joins the campaign name and a value that doesn't change, such as the LinkedIn URL or company domain: Clay has no fixed row id.
- Save your Mailr key as a header account. In the table, choose Add enrichment > HTTP API > Configure. Open Select header account, choose + Add account, enter Authorization with the value Bearer mlr_test_... under API Request Headers, name the account Mailr and save. A key typed straight into the Headers field is visible to anyone who can open the table.
- Configure the column. Method POST, endpoint https://api.mailr.dev/v1/postcards, a header Idempotency-Key set to the Mail key column, and the body below. Column values go in with a leading slash, and text values need quotes around them. Set Field paths to return to id, turn on Remove empty fields from request, and add a conditional run so rows without a ZIP are skipped.
- Run one row twice. Click Run cell on one row. With a test key nothing prints, and the piece shows up in your Mailr dashboard. Run the same cell again: it should return the same id, which means the Idempotency-Key filled in. Then run the column for the rest of the table.
- Go live. Edit the Mailr header account to use your mlr_live_ key; every HTTP API column that uses the account picks up the change. For large tables, use the export script below instead of one request per row.
Clay setup and scripts
HTTP API column (Add enrichment > HTTP API > Configure)
Method POST
Endpoint https://api.mailr.dev/v1/postcards
Header account Mailr (Select header account > + Add account: Authorization = Bearer mlr_test_...)
Headers Idempotency-Key = /Mail key
Body
{
"size": "5.5x8.5",
"template": "tmpl_event_invite",
"to": {
"name": "/Full Name",
"company": "/Company Name",
"line1": "/Street",
"line2": "/Suite",
"city": "/City",
"state": "/State",
"zip": "/Zip"
},
"merge": {
"first_name": "/First Name",
"event_name": "Revenue Leaders Dinner",
"event_date": "Thursday, March 12"
},
"description": "/Mail key"
}
Field paths to return id
Remove empty fields from request On (so a blank Suite isn't sent)
Conditional runs Only run if Zip is not empty
Rate limiting 10 requests per 1000 ms
"from" is left out: Mailr uses the return address saved in Settings.
Limits: name and company 40 characters, line1 64, first_name 14, event_name 28, event_date 24.- Clay has no built-in row id, so the Idempotency-Key comes from a Formula column built from values that don't change. A repeat within 24 hours returns the first postcard; after that, running the column again would mail again.
- Table-level auto-run is on by default and runs enrichments when rows are added or edited. If an edit to a row could run the mail column again later, turn that column's auto-run off under Run settings and run it by hand.
- Set Rate limiting on the column (for example 10 requests per 1,000 ms) so a large table doesn't send every row at once. For thousands of rows, the export script makes one request per 1,000.
- The CSV export mirrors the table as you've set it up, so show the columns the script reads before you download it.
- Merge values have limits: first_name 14 characters, event_name 28 and event_date 24; name and company 40, street 64. A longer value fails that row with a 422 that names the field.
- How you may use data you enrich in Clay, mail included, is set by Clay's terms and each data provider's, not by Mailr.
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
Is there a Mailr integration in Clay?
Not a listed one. The HTTP API column calls Mailr's REST API directly with your key. Mailr has no webhooks yet, so to see where a piece is, retrieve it with GET /v1/postcards/{id}.
Where does the mailing address come from?
From whatever you already use in Clay that returns a full street address, city, state and ZIP, or from your CRM. Mailr doesn't sell lists or look up addresses; it prints and mails to the address you send.
Can I send my own design from Clay?
A template is the easy fit for a column, because the body stays small. For your own design, export the table and run the script: it sends your front.html and back.html, started from the blank 6x9 layout in the Mailr kit (/downloads/mailr-kit.zip), with each row's merge values.
Will a row ever be mailed twice?
Not within 24 hours: the same Mail key returns the first postcard. After that, running the column again would send another, so turn its auto-run off once a campaign is out. The export script also keeps mailed.csv and skips rows already in it.
What does a card cost?
The event invite is a 5.5x8.5 postcard at $0.89 on pay as you go, printing and postage included, and less on a plan. Test pieces with an mlr_test_ key are free and never print.