Skip to content

// frameworks and platforms

Via API

Cloudflare Workers email verification with pingutil

When signups hit your origin directly, every throwaway and mistyped address costs a database write and a bounced welcome email. A Worker on the signup route asks pingutil first, answers 422 for disposable or invalid addresses at the edge, and forwards everything else with the result in a header, without changing your backend code.

Where it connects: Workers fetch handler on a route in front of the signup endpoint, with the Cache API

What goes wrong without it

  • Signup floods from temp-mail domains reach our origin and fill the users table before anything can stop them.
  • Our backend is a legacy app we do not want to touch just to add an email check.
  • Welcome emails to typo addresses keep bouncing and our email provider is unhappy.

What you can do with Cloudflare Workers and pingutil

  • Edge filter with no backend changes

    Put the Worker on the POST route for /signup. It rejects bad addresses itself and forwards good ones to the origin unchanged apart from x-email-category and x-email-status headers.

  • Cache disposable domains per data center

    The Cache API stores the category per domain for a day, so a flood from one throwaway domain is rejected at the edge without another API call.

  • Let the origin decide on uncertain results

    risky and unknown results are forwarded with their status, so the origin can hold trial credits until the address is confirmed.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and store it with npx wrangler secret put PINGUTIL_KEY (and in .dev.vars for wrangler dev).

  2. 2

    Deploy the Worker on a route that matches your signup URL on your zone.

  3. 3

    In the fetch handler, read the email from a clone of the request so the original body can still be forwarded.

  4. 4

    Call /v1/lookup with skip_enrichment: true and an AbortSignal.timeout, cache the category with cache.put inside ctx.waitUntil, and reject on verdict.is_spam.

  5. 5

    Optionally call /v1/verify, reject invalid addresses, and forward the rest with the result headers.

  6. 6

    Have the origin trust the x-email-* headers only on requests that came through the Worker.

src/index.ts
// src/index.ts  (Worker on a route in front of POST /signup; npx wrangler secret put PINGUTIL_KEY)
interface Env {
  PINGUTIL_KEY: string
}

type Lookup = {
  domain: string
  category: string
  verdict: { is_spam: boolean; low_trust: boolean; reason: string | null }
}
type Verification = { status: 'valid' | 'invalid' | 'risky' | 'unknown'; did_you_mean: string | null }

const API = 'https://pingutil.com/v1'
const CATEGORY_TTL = 86_400 // seconds; the Cache API is per data center

async function pingutil<T>(env: Env, path: string, body: object, timeoutMs: number): Promise<T | null> {
  try {
    const res = await fetch(`${API}${path}`, {
      method: 'POST',
      headers: { authorization: `Bearer ${env.PINGUTIL_KEY}`, 'content-type': 'application/json' },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
    })
    if (res.status === 401) console.error('pingutil rejected PINGUTIL_KEY')
    return res.ok ? ((await res.json()) as T) : null
  } catch {
    return null // timeout or network error: fail open
  }
}

// Synthetic GET key: cache.put only accepts GET requests.
const categoryKey = (domain: string) =>
  new Request(`https://pingutil-cache.internal/category/${encodeURIComponent(domain)}`)

function reject(message: string, extra: Record<string, unknown> = {}) {
  return Response.json({ error: message, ...extra }, { status: 422 })
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    if (request.method !== 'POST') return fetch(request)

    // Read from a clone so the original body can still be forwarded to the origin.
    const form = await request.clone().formData().catch(() => null)
    const email = String(form?.get('email') ?? '').trim().toLowerCase()
    const domain = email.split('@')[1]
    if (!domain) return fetch(request) // let the origin's own validation answer

    const cache = caches.default
    const cached = await cache.match(categoryKey(domain))
    if (cached && (await cached.text()) === 'disposable') {
      return reject('Please use a permanent email address.')
    }

    const lookup = await pingutil<Lookup>(env, '/lookup', { input: email, skip_enrichment: true }, 1500)
    if (lookup) {
      ctx.waitUntil(cache.put(categoryKey(lookup.domain), new Response(lookup.category, {
        headers: { 'cache-control': `max-age=${CATEGORY_TTL}` },
      })))
      if (lookup.verdict.is_spam) return reject('Please use a different email address.')
    }

    const check = await pingutil<Verification>(env, '/verify', { email }, 4000)
    if (check?.status === 'invalid') {
      return reject('That mailbox does not exist.', { did_you_mean: check.did_you_mean })
    }

    // Forward to the origin with the result attached, so it can flag risky/unknown signups.
    const forwarded = new Request(request)
    forwarded.headers.set('x-email-category', lookup?.category ?? 'unchecked')
    forwarded.headers.set('x-email-status', check?.status ?? 'unchecked')
    return fetch(forwarded)
  },
} satisfies ExportedHandler<Env>

What to do with each result

pingutil resultAction in Cloudflare Workers
verdict.is_spam: trueReturn 422 from the Worker; the origin never sees the request.
status: invalidReturn 422 with did_you_mean.
status: risky or unknownForward with x-email-status so the origin can flag the account.
No answer (timeout, 429, network)Forward with x-email-status: unchecked; never block on an outage.

Limits to plan for

  • The Cache API is per data center and does nothing in the dashboard editor or Playground previews; cache.put only accepts GET keys, hence the synthetic URL.
  • The example reads form-encoded bodies; for JSON, parse request.clone().json() instead. Waiting on fetch is wall time, not CPU time, but the user still waits, so the mailbox check is capped at 4 s.
  • Per-account defaults: 60 requests a minute, 300 verified addresses and 2,000 lookups a day (3,000 and 30,000 a month). Catch-all domains come back risky. Those are Free plan limits; Enterprise has custom limits.

Cloudflare Workers documentation

Cloudflare Workers is a trademark of its owner. This integration uses Cloudflare Workers's documented extension points; it is not an official Cloudflare Workers app.

Common questions

Should I fail closed at the edge during an attack?
Only temporarily. Failing closed blocks real users whenever the API is slow. A safer pattern is to fail open by default and add a variable you can flip to closed while you are actively being flooded.
Why not store the categories in Workers KV?
KV writes are limited and eventually consistent, and a category cache does not need global replication. The Cache API is local, fast and has no write budget to manage.

Stop bad addresses in Cloudflare Workers today

Sign in with your email, create an API key and paste it into the step above. Test on a few real addresses first: the live demo shows exactly what your Cloudflare Workers setup will receive.