Direct mail API for Figma Sites
Direct mail API for Figma Sites: Figma's help center documents no built-in form handling for Sites, which is still in open beta, so the form is a code component (or an embedded form tool) that posts to a small endpoint you host. The endpoint checks the request and asks Mailr to print and mail a postcard or letter, and the Mailr key never touches the published site.
What to mail from Figma Sites
| When this happens | Mail this |
|---|---|
| A visitor submits a request form built as a code component | A postcard in your own design to the address on the form. |
| A quote request on a B2B landing page | A letter from your team in your own design, on an 8.5x11 flat. |
| A response to a form tool embedded on the page (Typeform, for example) | The same postcard, sent from that tool's webhook. See the Typeform page. |
Set it up
- Decide where the form lives. A code component gives you your own fields and posts straight to your endpoint (this page). An embedded form tool keeps its own builder and sends data through its own webhook; embeds only render in preview and on the published site, and fail if the tool blocks iframes.
- Create a Turnstile widget. In the Cloudflare dashboard, add a Turnstile widget for your site's domain (the figma.site address and any custom domain). The site key goes in the component and is public; the secret key goes in the Worker.
- Deploy the Worker. Set ORIGIN to your published domain, then npx wrangler deploy and add MAILR_API_KEY (a test key while you build) and TURNSTILE_SECRET with npx wrangler secret put. Save a return address in Mailr Settings so requests can leave out from.
- Add the code component. Add the component from the first tab to your page in Figma Sites and set ENDPOINT and the Turnstile site key. Code layers may not render accurately on the canvas, so check it in preview, then publish.
- Test, then go live. Submit the form on the published site with your own address. The postcard shows in your Mailr dashboard and moves through every status in about 8 minutes, free. Add funds and switch MAILR_API_KEY to your mlr_live_ key when it looks right.
The form component and the endpoint
import { useEffect, useRef, useState } from "react";
// Both values are public: your Worker's URL and your Cloudflare Turnstile site key. No Mailr key here.
const ENDPOINT = "https://mailr-figma.example.workers.dev/request";
const TURNSTILE_SITE_KEY = "0x4AAAAAAA_your_site_key";
declare global {
interface Window { turnstile?: { render: (el: HTMLElement, opts: { sitekey: string; callback: (token: string) => void }) => string } }
}
export default function CatalogRequestForm() {
const box = useRef<HTMLDivElement>(null);
const [token, setToken] = useState("");
const [requestId] = useState(() => crypto.randomUUID()); // one id per visit: a double click can't mail twice
const [state, setState] = useState<"idle" | "sending" | "sent" | "error">("idle");
useEffect(() => {
const render = () => box.current && window.turnstile?.render(box.current, { sitekey: TURNSTILE_SITE_KEY, callback: setToken });
if (window.turnstile) { render(); return; }
const script = document.createElement("script");
script.src = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
script.onload = render;
document.head.appendChild(script);
}, []);
async function submit(e: React.FormEvent<HTMLFormElement>) {
e.preventDefault();
setState("sending");
const fields = Object.fromEntries(new FormData(e.currentTarget));
const res = await fetch(ENDPOINT, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ ...fields, requestId, turnstile: token }),
}).catch(() => null);
setState(res?.ok ? "sent" : "error");
}
if (state === "sent") return <p>Thanks. We'll mail the catalog to that address.</p>;
return (
<form onSubmit={submit} style={{ display: "grid", gap: 12, maxWidth: 420 }}>
<input name="name" placeholder="Full name" required maxLength={40} />
<input name="line1" placeholder="Street address" required maxLength={64} />
<input name="line2" placeholder="Apt or suite (optional)" maxLength={64} />
<input name="city" placeholder="City" required maxLength={40} />
<input name="state" placeholder="State (AZ)" required pattern="[A-Za-z]{2}" maxLength={2} />
<input name="zip" placeholder="ZIP" required pattern="\d{5}(-\d{4})?" inputMode="numeric" />
<div ref={box} />
<button disabled={state === "sending" || !token}>Mail me the catalog</button>
{state === "error" && <p>That didn't go through. Check the address and try again.</p>}
</form>
);
}- As of November 2026, Figma's help center documents no native forms, form storage or form webhooks for Figma Sites, which Figma still labels open beta. If Figma adds a form webhook, swap the code component for it and keep the same Worker logic, the way the Framer page does.
- Code components are React rendered on the published site, and site-wide custom code goes into the page's head or body. Both reach every visitor's browser, so the Mailr key lives only in the Worker's secrets.
- The Worker's URL is public and each live postcard is paid from your balance, so it checks a Turnstile token on the server before calling Mailr. The Idempotency-Key figma-{request id} stops a double submit or a resend from mailing twice within 24 hours.
- Publishing a site takes a paid Figma plan (Professional, Organization, Enterprise or Education), and sites go live on a figma.site subdomain unless you connect a custom domain. Set ORIGIN to whichever address visitors use.
- Mailr mails to US addresses only and needs a two-letter state and a 5-digit or ZIP+4 code. The form's patterns and the Worker both check before anything is sent.
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
Does Figma Sites have its own forms?
Not according to Figma's documentation as of November 2026. Its help center mentions forms only as external content you can embed. The routes that work today are a code component posting to your own endpoint, or an embedded form tool with its own webhook.
Can the code component call Mailr directly?
No. It runs in the visitor's browser, so a key inside it is readable by anyone who opens the page and could be used to mail on your account. The component only knows your Worker's URL.
Can we use Zapier instead of a Worker?
The component can post to a Webhooks by Zapier catch hook, with a Code by Zapier step that calls Mailr. A catch hook URL is just as public and has no bot check, though, so for a page with paid traffic the Worker with Turnstile is the safer place to spend postage from.
We're sending ad traffic to a Figma Sites landing page. Will this hold up?
Each submission is one request and one postcard, a bad address fails on its own, and retries are safe because of the idempotency key. For a campaign to a list you already have, use POST /v1/batches instead: up to 1,000 recipients per request, all checked before anything prints.
How do we see 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 elsewhere.