vrfymail
Get started
For Bolt.new — StackBlitz's full-stack AI builder

Add email verification to Bolt.new apps via your project prompt.

Include the vrfymail contract in your Bolt.new project prompt. The scaffold ships with the signup handler already wired — no follow-up turns, no SDK install, just an env var.

Get an API key — free 5,000/mo See the API docs

Note: if you landed here trying to configure auth or one-time codes for the app you're building inside Bolt's preview, that's a different page — see Bolt's auth docs. This page covers wiring vrfymail's API into a user-facing signup form of an app Bolt.new generates.

Step 1 — paste the prompt

The Bolt.new project prompt

Open bolt.new, paste this as your starter prompt. Bolt scaffolds the whole project — Next.js app router, signup form, server route — with verification wired in from the first turn. Cheaper than 3 follow-up prompts to retrofit it.

bolt-project-prompt.txt
markdown 
Build a Next.js 15 SaaS starter with email/password signup.

The signup endpoint at app/api/signup/route.ts MUST verify the email before
creating the user. Use vrfymail's API:

  POST https://vrfymail.com/v1/check
  Authorization: Bearer ${process.env.MAIL_VERIFIER_KEY}
  Content-Type: application/json
  Body: { "email": "<email>", "strict": true }

Response:
  result          "deliverable" | "undeliverable" | "risky" | "unknown"
  reason          machine code (string)
  reason_message  end-user copy already mapped (string)
  did_you_mean    typo correction or null

Handling (do not deviate):
  - did_you_mean non-null → return 400 with the suggestion as a one-click apply.
  - undeliverable → return 400 with reason_message verbatim.
  - risky + role_account → 200 with a soft warning, allow signup.
  - deliverable → 200, proceed with account creation.
  - unknown → 200, proceed (refunded server-side, never block on a DNS hiccup).

No SDK install — use plain fetch. Read the key from process.env.MAIL_VERIFIER_KEY,
which I'll set in Bolt's environment variables panel.
Step 2 — env var

Open Project Settings → Environment Variables in Bolt's sidebar. Add MAIL_VERIFIER_KEY=vk_live_... Bolt re-injects it on the next preview reload.

Step 3 — export

When ready, Download to ZIP or Connect to GitHub. The integration travels intact — no Bolt-specific dependency to unwind. Re-set the env var in your destination.

What you get

The signup handler Bolt scaffolds

With the prompt above, this is what lands in app/api/signup/route.ts on Bolt's first turn. Real TypeScript, copy-pasteable into any Next.js 15 app router project.

app/api/signup/route.ts
typescript 
// app/api/signup/route.ts
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const { email, password, name } = await req.json();

  // Verify before creating the user.
  const v = await fetch("https://vrfymail.com/v1/check", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MAIL_VERIFIER_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email, strict: true }),
  });
  const verdict = await v.json();

  if (verdict.did_you_mean) {
    return NextResponse.json(
      { error: `Did you mean ${verdict.did_you_mean}?`, suggestion: verdict.did_you_mean },
      { status: 400 }
    );
  }
  if (verdict.result === "undeliverable") {
    return NextResponse.json(
      { error: verdict.reason_message, code: verdict.reason },
      { status: 400 }
    );
  }
  // deliverable, unknown, and risky-but-role_account all fall through.
  // Create the user here…
  return NextResponse.json({ ok: true });
}
Why putting it in the project prompt matters: Bolt's strength is generating a whole working app from a single prompt. Adding verification after the scaffold is 3 follow-up turns of "now move that to the server", "now handle unknown", "now use the env var." Putting it in the project prompt collapses that into zero — the first scaffold is the right shape.
The pattern most tutorials skip

On unknown, accept the signup.

unknown is what you get when the verification pipeline couldn't reach a verdict in the time budget. DNS lookup failed. MX timed out. None of those are evidence the email is bad — they're evidence the network had a bad second.

Bolt's default scaffolds sometimes fail-closed (block on anything that isn't deliverable). The prompt above patches that — deliverable and unknown both fall through to the account-creation path.

On vrfymail the cost-side argument vanishes too: unknown verdicts don't bill. refundUsage() releases the slot when the pipeline can't reach a verdict.

Verdict handling cheat sheet
  • deliverable Accept.
  • unknown Accept. Log the verdict if you want a paper trail. Not billed.
  • risky role_account → soft warning, allow submit. Other reasons → block or quarantine.
  • undeliverable Block. Show reason_message verbatim.
  • did_you_mean Non-null → suggest the correction inline. Works on any verdict.
The compounding case

Zero retrofits. The first scaffold is the right one.

Bolt's economy is the first prompt. Every retrofit (move client → server, fix verdict handling, add env var, refactor for unknown) is another generation. The prompt above pre-empts all of them in one paste.

The same scaffolding logic works in other AI app builders — Lovable (reference URL pattern), v0 (server-action prompt), Replit Agent (Secrets + agent prompt). Different surfaces, identical vrfymail contract.

Frequently asked

Bolt.new + email verification, answered

Where do I add MAIL_VERIFIER_KEY in Bolt.new?
Click the Project Settings icon in Bolt's sidebar, open Environment Variables, add MAIL_VERIFIER_KEY=vk_live_... Hit Save and Bolt will inject it into the preview's runtime. The variable persists for the Bolt project (it travels with the project, not the chat). If you export to StackBlitz / GitHub, copy the variable to your new environment.
Does the Bolt preview hit production vrfymail or a sandbox?
Production. Bolt's preview is a real Node runtime that makes outbound HTTPS calls — vrfymail sees those as normal API traffic from your bearer token. The first 5,000/month are on the free tier whether they come from preview or your real app. If you want to test bulk paths without burning quota, use the same email repeatedly: vrfymail caches per-customer for 24h.
Can I use Bolt with frameworks other than Next.js?
Yes. Bolt scaffolds Astro, SvelteKit, Nuxt, Remix, and vanilla Vite + React. The prompt above is Next.js-flavoured but the vrfymail call is identical across them — fetch + JSON. Adjust the prompt to name your target framework and Bolt will use the right idiom (Astro action, SvelteKit form action, Nuxt server route, Remix loader).
What if Bolt's scaffold puts the verification on the client?
Re-prompt with: 'Move the vrfymail.com/v1/check call to the server. The bearer token must never reach the browser.' Bolt corrects in one turn. The prompt above pre-empts this by specifying app/api/signup/route.ts as the location — Bolt will scaffold the verification in the server handler, not the React component.
How do I export a Bolt project so I can keep iterating in my own editor?
Click Download to ZIP for a one-shot export, or Connect to GitHub for ongoing sync. Either way the env var has to be re-set in your destination (Vercel, Netlify, Cloudflare, local .env). The vrfymail integration travels with the code — there's no Bolt-specific glue to unwind.

One prompt. Project scaffolded. Verification wired.

vrfymail's /v1/check returns a verdict in 50ms p50. Free tier: 5,000 verifies/month, no card. Paid plans start at $9/mo for 10,000 — see pricing.

Get my API key