Direct mail API for political campaigns
Direct mail API for political campaigns: a precinct list exported from the voter file goes out as batches of up to 1,000 get-out-the-vote cards, a contribution webhook triggers a thank-you card from the candidate, a volunteer signup triggers a welcome card, and the yard signs, stickers and palm cards are ordered with the same API key and shipped to the field office.
Who builds this
Data directors and digital staff on campaigns, the consultants and mail vendors who run programs for many candidates and ballot committees at once, party and caucus tech teams, and the developers of campaign tools (CRM, texting, volunteer and fundraising apps) who want a mail step. They cut voter universes from the voter file into precinct lists, send contributions and signups to a thank-you queue, and order yard signs, stickers and palm cards for field offices on a deadline that doesn't move.
Who to mail
| Who | Why paper works | What to send |
|---|---|---|
| Likely voters, by precinct | A mailer reaches the household whether or not the voter answers the door, the phone or a text, and it carries the candidate's face and the election date. | An 11x17 persuasion mailer folded to 8.5x11, then a 6x11 get-out-the-vote card the week before Election Day. |
| Absentee and early voters | Voters with a mail ballot decide on their own schedule, so a card that arrives while the ballot is on the table is timely. | A 6x9 card with the return-by date and drop-box locations, then a reminder to those whose ballot hasn't come back. |
| Donors | A thank-you card from the candidate is rare in a cycle of fundraising emails, and it reaches donors who stopped opening them. | A 6x9 thank-you card signed by the candidate after a first contribution, with no amount on it. |
| Volunteers | Volunteers give hours, not dollars, and a card from their field organizer is a thank-you they can keep. | A 4x6 card after their first shift with the next canvass or phone-bank date. |
| Yard-sign hosts | Sign hosts put their name on the lawn, and a mailed thank-you with the election date keeps the sign up through Election Day. | A 4x6 thank-you when the sign request comes in, with the election date and a number to call if the sign goes missing. |
| Endorsers and community leaders | A letter from the candidate is the right register for thanking an endorser or asking someone to join a host committee. | An 8.5x11 letter signed by the candidate, mailed flat. |
What to mail, and when
| When this happens | Mail this | Price |
|---|---|---|
| A persuasion universe is cut for a precinct | A persuasion mailer folded to 8.5x11, sent in batches of up to 1,000 per precinct. (11x17 folded mailer) | $1.39 |
| A voter's mail-ballot request shows up in the voter file | A vote-by-mail card with the return-by date and drop-box locations. (6x9 postcard) | $0.89 |
| Two weeks before Election Day, for supporters who haven't voted early | A get-out-the-vote card with their polling place hours and the last day of early voting. (6x11 postcard) | $0.99 |
| Someone contributes for the first time | A thank-you card from the candidate. No amount on the card. (6x9 postcard) | $0.89 |
| A volunteer signs up | A welcome card with the field office address and the next shift. (4x6 postcard) | $0.85 |
| Someone requests a yard sign | A thank-you card with the election date and the field office number. (4x6 postcard) | $0.85 |
| A town hall or rally is scheduled | An invite to supporters in the district with the date and place. (5.5x8.5 postcard, Event invite) | $0.89 |
| An endorsement comes in or a host committee forms | A letter from the candidate, mailed flat. (8.5x11 letter) | $0.95 |
What to print
Printed and picked up free in Phoenix or shipped UPS Ground, ordered with POST /v1/prints.
| Piece | Used for | Price |
|---|---|---|
| 18x24 yard sign | Lawn signs for sign hosts and corner placements, printed both sides, with H-stakes if you ask for them. | $4.75–$7.00, from 10 |
| 3x3 vinyl sticker | Candidate stickers for canvass kits, rallies and parades, cut square or circle. | $0.64, from 50 |
| 4x9 rack card | Palm cards for canvassers and poll greeters. | $0.26, from 100 |
| 4.25x11 rack card | Taller walk pieces for door-to-door literature drops. | $0.30, from 100 |
| 8.5x11 flyer | Event flyers and issue one-pagers for community boards and house parties. | $0.53, from 100 |
| 24x36 poster | Field office window posters and rally signs, from one. | $19.20 |
| 18x24 poster | Posters for events, volunteer centers and campaign offices. | $9.60 |
Systems to connect
- Voter file and field: NGP VAN / EveryAction or your state party's voter file. A scheduled export per list. VAN's API runs an export job for a saved list (POST /v4/exportJobs with savedListId, an export type and a webhookUrl) and POSTs the finished job back with a downloadUrl; changed-entity export jobs return records changed since a date up to 90 days back.
- Fundraising: ActBlue, WinRed. Webhooks per contribution. ActBlue's ActBlue Default webhook (Tools > Integrations > Webhooks) sends the donor's name and address with each contribution; refunds and cancellations are separate webhook types. WinRed offers Donation, Lead and Subscription webhooks under Utilities > Integrations, filtered by amount, campaign or contributor type.
- Organizing and signups: NationBuilder or your website's forms. NationBuilder sends Person created, Person changed and Donation succeeded webhooks on Enterprise accounts. A volunteer or yard-sign form on your own site can call Mailr directly when it's submitted.
- Zapier or n8n. Connect a signup form, a fundraising webhook or a spreadsheet to Mailr with one HTTP step.
- No software, or something else. Export a spreadsheet of voters, donors or volunteers with addresses, one row each, and send it as a batch of up to 1,000.
Code: a donor thank-you, precinct GOTV batches and yard signs
// Call this from whatever sends you contributions: a fundraising-platform webhook, a nightly export or your CRM.
// gift is your own record: id (the platform's order or transaction id), donor name and mailing address.
import { readFileSync } from "node:fs";
const FRONT = readFileSync("mail/donor-thanks/front.html", "utf8"); // 6x9, signed by the candidate, uses {{first_name}}
const BACK = readFileSync("mail/donor-thanks/back.html", "utf8"); // includes the committee's "Paid for by" box
export async function mailDonorThanks(gift) {
const a = gift.donor.address;
if (!a?.line1 || a.country !== "US" || !(await isFirstGift(gift.donor))) return null; // your own donor table
const res = await fetch("https://api.mailr.dev/v1/postcards", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": `donor-thanks-${gift.id}`, // a webhook redelivered within 24 hours returns the first card
},
body: JSON.stringify({
size: "6x9",
front: FRONT,
back: BACK,
to: {
name: `${gift.donor.firstName} ${gift.donor.lastName}`.slice(0, 40),
line1: a.line1,
line2: a.line2 || undefined,
city: a.city,
state: a.state,
zip: a.zip,
},
merge: { first_name: gift.donor.firstName.slice(0, 14) }, // never the amount: postcards mail without an envelope
description: `Donor thank-you ${gift.id}`,
}),
});
const card = await res.json();
if (!res.ok) throw new Error(card.error.message);
return card.id; // save it on the donor so later gifts skip the card
}What it costs
Get-out-the-vote cards to 10,000 likely voters: 10,000 6x11 postcards at $0.99 each is $9,900.00 on pay as you go, or $7,100.00 on the Agency plan, printing and postage included. Ten batches of 1,000 cut by precinct, each voter's polling place hours in a merge field, and the committee's "Paid for by" disclaimer in the design. Test pieces are free. All prices.
Questions
Does Mailr have political or nonprofit postage rates?
No. Every sender pays the same price per piece, printing and USPS postage included: $0.99 for a 6x11 card and $1.39 for an 11x17 folded mailer pay as you go, or $0.71 and $1.04 on the Agency plan ($149 a month).
Where does the "Paid for by" disclaimer go?
In your design: Mailr prints what you send and doesn't add or check disclaimers. For federal committees the FEC requires it on mailers, yard signs and posters, in a printed box set apart from the rest of the piece, readable (12-point type is the safe harbor on signs and posters up to 24x36) and in clear contrast. Small items such as bumper stickers and buttons are exempt when it can't be conveniently printed. State and local races follow state law.
Does Mailr provide voter files or lists?
No. Mailr doesn't sell lists or voter files, verify addresses or run NCOA. Universes come from your voter file vendor, your party or the state file; clean them there and send the addresses you want mailed.
How do we mail 30,000 voters?
As batches of up to 1,000 from one design. Each batch is all or nothing, so a bad ZIP code stops that batch instead of half of it. Give each batch an Idempotency-Key such as gotv-2026-precinct-114-1 so a job retried within 24 hours gets the first batch back instead of mailing the precinct twice.
How do yard signs get to the field office?
18x24 corrugated plastic signs, printed both sides, from 10 signs: $11.20 each for 10 to 100, $9.60 for 101 to 250 and $7.60 above that pay as you go, plus $1.20 a stake with stands: true. Pick up free in Phoenix or ship UPS Ground, priced by destination in the lower 48; POST /v1/prints/quote shows the total first.
Can we test the donor thank-you without mailing anything?
Yes. A mlr_test_ key is free and never prints. Test pieces move through every status on their own, so the webhook handler and the batch job can run end to end before you add funds.