vrfymail API

You are helping me integrate vrfymail into this project.

vrfymail (https://vrfymail.com) is an HTTP API
that validates email addresses — disposable detection, typo correction,
role-account flagging, real-time spam-trap probes, and a per-account
bounce overlay. There is no SDK. One endpoint, JSON in, JSON out.

Follow these steps in order. Do not skip Step 1.

================================================================
Step 1 — Get my API key
================================================================

Before writing any code, say to me, verbatim:

  "Open https://vrfymail.com/dashboard, click
   'Create API key', copy the value (it starts with vk_live_), and
   paste it here."

Wait for me to paste a value that begins with `vk_live_`. Do not
continue until I do.

================================================================
Step 2 — Store the key as an environment variable
================================================================

Add the pasted key to this project's `.env` or `.env.local`:

  MAIL_VERIFIER_KEY=vk_live_<the value I pasted>

Add the same line (with no value) to `.env.example` if one exists.

If this is a Cloudflare Workers / Pages project, instead run:

  npx wrangler secret put MAIL_VERIFIER_KEY

If this is a Vercel project, run:

  vercel env add MAIL_VERIFIER_KEY

Never hardcode the key in source.

================================================================
Step 3 — Add the verify call
================================================================

Find every place this project validates an email address — signup
forms, contact forms, newsletter subscribe, anywhere `email.includes('@')`
or similar appears — and augment it with a call to /v1/check.

Use plain `fetch`. No package install.

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

Response — the fields that matter:
  result        : "deliverable" | "undeliverable" | "risky" | "unknown"
  reason        : short string, e.g. "valid_mailbox", "disposable",
                  "typo_suspected", "role_account", "spam_trap"
  did_you_mean  : a corrected email address, or null
  account_history.matched : true if THIS api key has previously
                            reported this email as bounced

Handling:
  result === "undeliverable" → reject the form. If did_you_mean is
                                non-null, suggest the corrected
                                address: "Did you mean foo@gmail.com?"
  result === "risky"          → soft warning. Allow it through unless
                                 this is a strict B2C signup gate.
  result === "deliverable" or "unknown" → accept.

Wrap the call with a 5-second timeout. On network error or 5xx
response, fail open (treat as deliverable) so a vrfymail outage
never blocks legit signups.

================================================================
Step 4 — Optional: bounce reporting
================================================================

If this project sends transactional email via Resend, Postmark,
SendGrid, or SES, find the webhook handler for bounce + complaint
events. Add a fire-and-forget call to vrfymail whenever a bounce
arrives:

  POST https://vrfymail.com/v1/report-bounce
  Authorization: Bearer ${MAIL_VERIFIER_KEY}
  Content-Type: application/json
  Body: { "email": "<email>", "reason": "<reason>" }

Where <reason> is one of:
  hard_bounce | soft_bounce | spam_complaint | unsubscribe

Map the ESP's event types to those reasons. This builds a per-account
overlay so future verifies of the same email by the same key
short-circuit to "undeliverable" without an extra DNS probe.

================================================================
Step 5 — Optional: safe-domain allowlist
================================================================

If this project has internal/trusted domains that should NEVER be
flagged (employee email domains, partner integrations, the company's
own product domains), add them to the per-account safe-domain
allowlist. Verifies whose email's domain is on the list return:

  { result: "deliverable", reason: "customer_safelisted" }

…without running disposable / spam-trap / MX / DBL checks. Per-account
only — never affects other customers.

  GET    https://vrfymail.com/v1/safe-domains
  POST   https://vrfymail.com/v1/safe-domains
         Body: { "domain": "example.com", "note": "(optional)" }
  DELETE https://vrfymail.com/v1/safe-domains/<domain>

All three require the same `Authorization: Bearer ${MAIL_VERIFIER_KEY}`.

When to use this: only add domains the application owner has
explicitly identified as trusted. Don't auto-populate from MX records
or signup history — that defeats the purpose. Reported bounces
(/v1/report-bounce) still win at the per-email level even when the
domain is allowlisted.

================================================================
Constraints
================================================================

- No SDK install. Plain `fetch`.
- Log all errors with a `[mail-verifier]` prefix so failures are
  visible during development.
- Do not add app-side caching — vrfymail already caches per
  (api-key, email) for up to 7 days on the server side.
- Do not block email-sending paths on the verifier. Only block form
  submissions.

================================================================
Now begin
================================================================

Ask me for my API key (Step 1). Once I paste it, execute Steps 2–4
against the current codebase, adapting to whatever framework / stack
this project uses.

curl https://vrfymail.com/v1/check \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "strict": true }'

curl https://vrfymail.com/v1/report-bounce \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "bounced@example.com", "reason": "hard_bounce" }'

curl https://vrfymail.com/v1/safe-domains \
  -H "Authorization: Bearer vk_live_..."

curl -X POST https://vrfymail.com/v1/safe-domains \
  -H "Authorization: Bearer vk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com", "note": "trusted partner" }'

curl -X DELETE https://vrfymail.com/v1/safe-domains/example.com \
  -H "Authorization: Bearer vk_live_..."