Direct mail API for Vercel
Direct mail API for Vercel: a Vercel Function posts to Mailr when a webhook arrives, a schedule calls another function every morning to mail a batch, and your Mailr key stays in a Secret environment variable that never reaches the browser.
What to mail from Vercel
| When this happens | Mail this |
|---|---|
| Shopify's orders/paid webhook reaches api/hooks/order-paid | A thank-you postcard for a customer's first order. (First-order thank you) |
| A Vercel schedule calls api/cron/winback every morning | Win-back postcards to everyone 60+ days past their last order, one batch per 1,000. (Win-back) |
| Your signup function creates an account | A founder welcome letter, mailed flat. (Welcome letter) |
Set it up
- Store the key. Run vercel env add MAILR_API_KEY --environment production,preview --sensitive and paste your mlr_test_ key. Secret variables are write-only once saved, and a deployment keeps the values it was built with, so redeploy after any change.
- Add CRON_SECRET and save a return address. Add CRON_SECRET, a random string of 16 or more letters and numbers; Vercel sends it as Authorization: Bearer <CRON_SECRET> on every scheduled request to a path. In Mailr's dashboard Settings, save your return address, so the requests below can leave out from.
- Add the helper and the two routes. Copy lib/mailr.ts and the two functions below. The paths are for a project without a framework; in Next.js the same code goes in app/api/hooks/order-paid/route.ts and app/api/cron/winback/route.ts, and the scheduled route also needs export const dynamic = "force-dynamic".
- Schedule the batch. Add the schedules entry from the top of api/cron/winback.ts to vercel.json and deploy. Schedules is the successor to Cron Jobs and is in public beta; a crons entry with the same path calls the same route, in UTC.
- Test, then go live. Point your store's orders/paid webhook at /api/hooks/order-paid with its signing secret in SHOPIFY_WEBHOOK_SECRET, and start the schedule once with Run Schedule on the project's Schedules page. Test pieces show up in your Mailr dashboard and never print. Then set MAILR_API_KEY in Production to your mlr_live_ key and redeploy.
Vercel Functions
// lib/mailr.ts: one helper for every Mailr call. MAILR_API_KEY is a Secret environment variable.
export type Address = { name: string; line1: string; line2?: string; city: string; state: string; zip: string };
/** POST to Mailr. The same Idempotency-Key within 24 hours returns the first response instead of mailing again. */
export async function mailr<T = { id: string; status: string }>(path: string, body: object, idempotencyKey: string): Promise<T> {
const res = await fetch(`https://api.mailr.dev/v1${path}`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.MAILR_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(body), // no "from": Mailr prints the return address saved in Settings
signal: AbortSignal.timeout(20_000),
});
const data = await res.json();
if (!res.ok) throw new Error(`Mailr ${res.status}: ${data.error?.message}`);
return data as T;
}- Vercel doesn't retry a failed scheduled run, for Cron Jobs or for Schedules path targets, and can occasionally deliver the same run twice. The key built from the batch's customer ids makes a second delivery replay the first batch instead of mailing again.
- On Hobby, Cron Jobs run at most once a day, at any time within the scheduled hour; Schedules can run as often as every 15 minutes, start within a 15-minute window and are capped at 5,000 runs a month. On Pro, both start within about a minute.
- Static schedules are active in Production only. In Preview branches they start inactive, so a preview deployment doesn't mail anyone until you enable its schedule.
- Functions on Hobby can run for up to 300 seconds, the default on every plan. Each batch of up to 1,000 recipients is a single request to Mailr.
- Merge values have length caps (first_name 14 characters, last_product 22). A longer value fails the whole batch with a 422 before anything prints, so trim them in lapsedCustomers.
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: First-order thank you (6x9), Win-back (6x11), Welcome letter (8.5x11).
Questions
Should I use Cron Jobs or Schedules?
Vercel calls Cron Jobs a legacy feature and Schedules its successor, in public beta since November 2026. Both call the route above with CRON_SECRET, so you can start on either. Schedules adds a timezone, runs in Preview branches when you enable them, and can target a queue when a run must be retried.
Can the browser call Mailr directly?
No. Mailr keys are secret, so every request goes through a Vercel Function that reads MAILR_API_KEY from the environment. A browser only ever talks to your own routes.
What if Mailr is unreachable when the schedule fires?
The function throws and Vercel doesn't retry it. Start the schedule again with Run Schedule the same day: the same customers give the same key, so any batch that already went through is replayed, not sent twice.
Does Mailr call my Vercel app back when a postcard is delivered?
Not yet. Mailr has no webhooks, so read GET /v1/postcards/{id} when you need a status, or list a batch's pieces with GET /v1/postcards?batch=bat_...