Direct mail API for Framer
Direct mail API for Framer: point a Framer form at a webhook, and a small function you host checks Framer's signature and asks Mailr to print and mail a postcard or letter to the address on the form. The Mailr key stays on your server, because everything in a published Framer site, code components included, runs in the visitor's browser.
What to mail from Framer
| When this happens | Mail this |
|---|---|
| A form submission with Send To set to Webhook (a catalog or sample request) | A postcard in your own design to the address on the form. |
| A quote or demo request form on a B2B landing page | A letter from your sales team in your own design, on an 8.5x11 flat. |
| A submission Framer flags as possible spam (X-Framer-Spam-Protection: marked) | Nothing. The function skips it, so spam never costs you postage. |
Set it up
- Name the inputs. Framer sends the form as JSON keyed by each input's name. Name them name, address, address2, city, state and zip. Use a Select for state with two-letter values (AZ, not Arizona); Mailr needs a two-letter state and a 5-digit or ZIP+4 code.
- Deploy the function. Use the Next.js route (Vercel or any Node host) or the Cloudflare Worker below. Set MAILR_API_KEY to a test key and FRAMER_WEBHOOK_SECRET to a random string of at least 32 characters, for example from openssl rand -hex 32.
- Add the webhook in Framer. Select the form on the canvas, click Add… next to Send To in the right sidebar and choose Webhook. Paste the function's https URL and the same secret. Framer won't show the secret again.
- Save your return address in Mailr. With a return address saved in Settings, requests can leave out from and Mailr prints the saved one.
- Test, then go live. Publish, submit the form with your own address, and the postcard appears in your Mailr dashboard and moves through every status in about 8 minutes, free. Then add funds and swap in your mlr_live_ key.
The function that receives the webhook
// Next.js route handler (Vercel or any Node host). Env: MAILR_API_KEY, FRAMER_WEBHOOK_SECRET.
import { createHmac, timingSafeEqual } from "node:crypto";
// Your design: start from a template's front.html and back.html in mailr.dev/downloads/mailr-kit.zip.
const FRONT = "<html>…your 6x9 front.html with {{first_name}}…</html>";
const BACK = "<html>…your 6x9 back.html…</html>";
export async function POST(req: Request) {
const raw = Buffer.from(await req.arrayBuffer());
const submissionId = req.headers.get("framer-webhook-submission-id") ?? "";
const signature = req.headers.get("framer-signature") ?? "";
// Framer signs the raw body followed by the submission id: "sha256=" + hex HMAC SHA-256.
const expected = "sha256=" + createHmac("sha256", process.env.FRAMER_WEBHOOK_SECRET!).update(raw).update(submissionId).digest("hex");
if (!submissionId || signature.length !== expected.length || !timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return new Response("bad signature", { status: 401 });
}
if (req.headers.get("x-framer-spam-protection") === "marked") return new Response("possible spam, skipped");
const f = JSON.parse(raw.toString("utf8")); // keys are the input names
const zip = String(f.zip ?? "").trim();
if (!f.address || !/^\d{5}(-?\d{4})?$/.test(zip)) return new Response("no US address, skipped");
const name = String(f.name ?? "").trim();
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": "framer-" + submissionId,
},
body: JSON.stringify({
size: "6x9",
front: FRONT,
back: BACK,
to: { name: name.slice(0, 40), line1: f.address, line2: f.address2 || undefined, city: f.city, state: String(f.state ?? "").toUpperCase(), zip },
merge: { first_name: name.split(" ")[0].slice(0, 14) },
description: "Framer form " + submissionId,
}),
});
if (res.ok) return new Response("mailed");
const err = await res.json().catch(() => ({}));
console.error("Mailr", res.status, submissionId, err.error?.message);
// Framer retries anything that isn't 2xx, up to 5 times. Ask for a retry only when one can work.
const retry = res.status >= 500 || res.status === 402 || res.status === 409;
return new Response("not mailed", { status: retry ? 500 : 200 });
}- Framer retries a delivery that doesn't get a 2xx, up to 5 times, and it doesn't follow redirects. Give it the final URL: if your domain redirects from the bare domain to www, or adds a trailing slash, the webhook fails.
- The signature covers the body and the Framer-Webhook-Submission-Id header, and Framer sends no timestamp. The Idempotency-Key framer-{submission id} is what stops a retried delivery from mailing a second postcard: Mailr returns the first one for 24 hours.
- Code components and code overrides run in the visitor's browser, and Framer's own docs say an API key can't be used securely on the front end. The Mailr key only ever lives in the function's environment.
- With spam protection in Pass mode, Framer still delivers flagged submissions and marks them with X-Framer-Spam-Protection: marked. The function skips those. Framer's Advanced spam protection is on Pro plans and above.
- Template merge values have length limits (first_name 14 characters, for example). Your own design's merge fields can be up to 200 characters. The function trims the name before sending.
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.
Questions
Can I call Mailr straight from a Framer code component?
No. A code component is React that runs in the visitor's browser, so a key inside it is public. Use a code component only for the form's UI if you need one (address autocomplete, say) and have it post to your function. That request isn't signed by Framer, so add a bot check such as Cloudflare Turnstile; the native webhook above is simpler and signed.
Doesn't Framer have a Server API now?
It does, in open beta since February 2026, but it's for managing and publishing projects from your own server. It doesn't receive form submissions, so the form webhook is still the way to get an address out of a Framer site.
We get thousands of form fills a month from Framer landing pages. Per submission or in batches?
Per submission. Each request mails one piece, a bad address fails on its own without holding up the rest, and the idempotency key makes retries safe. Batches (POST /v1/batches, up to 1,000 recipients) suit campaigns to a list you already have, such as everyone who requested a catalog last quarter.
Is there a Mailr plugin in the Framer marketplace?
No. The function on this page is the integration. A coding agent can adapt it from https://mailr.dev/llms.txt or the SKILL.md in the template kit.
How do we check what was delivered?
Each piece is in the Mailr dashboard with its status. Mailr doesn't send webhooks yet, so poll GET /v1/postcards/{id} if you want statuses in your own tools.