Skip to content

// frameworks and platforms

Via API

Netlify Functions email verification with pingutil

Static sites on Netlify often post signups straight to a function that writes to a database or an email tool, with no check beyond type="email" in the browser. Calling pingutil from that function rejects disposable and dead addresses before they are stored, and passes everything through if the API is slow.

Where it connects: Netlify Function with the modern Request/Response handler and config.path

What goes wrong without it

  • Our Jamstack waitlist is full of throwaway addresses and our launch email is going to bounce.
  • Client-side validation is all we have, and anyone can POST to the function directly.
  • We pay per contact in our email tool and a lot of those contacts are fake.

What you can do with Netlify Functions and pingutil

  • Clean waitlists and early-access signups

    Reject disposable and invalid addresses before the function adds them to your database or email list, so your launch email goes to people who can receive it.

  • One endpoint for every form

    Expose the function at /api/signup with config.path and point your signup, waitlist and contact forms at it.

  • Return the typo fix to the page

    The 422 response includes did_you_mean, so the page can offer "Did you mean ...?" before the user leaves.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and add PINGUTIL_KEY as an environment variable scoped to Functions in the Netlify UI.

  2. 2

    Create netlify/functions/signup.mts with a default export that takes a Request and a Context and returns a Response.

  3. 3

    Set export const config = { path: "/api/signup" } so the function answers on your own domain.

  4. 4

    Call /v1/lookup with skip_enrichment: true, then optionally /v1/verify, each with AbortSignal.timeout.

  5. 5

    Store the contact, and redeploy whenever you change the environment variable.

netlify/functions/signup.mts
// netlify/functions/signup.mts  (Netlify Functions, modern Request/Response API)
import type { Config, Context } from '@netlify/functions'

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 }

// Module scope survives only while this function instance stays warm.
// Good enough to skip repeat lookups for the same throwaway domain; use a shared store for more.
const categories = new Map<string, { category: string; expires: number }>()

async function pingutil<T>(path: string, body: object, timeoutMs: number): Promise<T | null> {
  try {
    const res = await fetch(`https://pingutil.com/v1${path}`, {
      method: 'POST',
      headers: {
        authorization: `Bearer ${process.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
  }
}

export default async (req: Request, context: Context) => {
  if (req.method !== 'POST') return new Response('Method not allowed', { status: 405 })

  const { email: raw } = (await req.json().catch(() => ({}))) as { email?: unknown }
  const email = typeof raw === 'string' ? raw.trim().toLowerCase() : ''
  const domain = email.split('@')[1]
  if (!domain) return Response.json({ error: 'Enter a valid email address.' }, { status: 422 })

  const cached = categories.get(domain)
  if (cached && cached.expires > Date.now() && cached.category === 'disposable') {
    return Response.json({ error: 'Please use a permanent email address.' }, { status: 422 })
  }

  const lookup = await pingutil<Lookup>('/lookup', { input: email, skip_enrichment: true }, 2000)
  if (lookup) {
    categories.set(lookup.domain, { category: lookup.category, expires: Date.now() + 86_400_000 })
    if (lookup.verdict.is_spam) {
      return Response.json({ error: 'Please use a different email address.' }, { status: 422 })
    }
  }

  const check = await pingutil<Verification>('/verify', { email }, 5000)
  if (check?.status === 'invalid') {
    return Response.json(
      { error: 'That mailbox does not exist.', did_you_mean: check.did_you_mean },
      { status: 422 },
    )
  }

  // Create the account or add the contact here. Flag anything that isn't a confirmed "valid".
  console.log('signup', { request: context.requestId, category: lookup?.category, status: check?.status })
  return Response.json({ ok: true, needs_review: check?.status !== 'valid' }, { status: 201 })
}

export const config: Config = {
  path: '/api/signup',
}

What to do with each result

pingutil resultAction in Netlify Functions
verdict.is_spam: trueReturn 422; do not store the contact.
status: invalidReturn 422 with did_you_mean for the page to show.
status: risky or unknownStore with a needs_review flag and send a double opt-in email.
No answer (timeout or error)Store the contact and re-check it before your next send.

Limits to plan for

  • Netlify documents a 60 second synchronous execution limit; the example keeps the whole check well under 10 s so the form stays responsive.
  • Environment variables are fixed at deploy time, and only variables scoped to Functions (not ones declared in netlify.toml) are available to the function.
  • The module-level cache only lives while an instance is warm. Per-account defaults are 60 requests a minute, 300 verified addresses and 2,000 lookups a day (3,000 and 30,000 a month). Those are Free plan limits; Enterprise has custom limits.

Netlify Functions documentation

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

Common questions

Can I use this with Netlify Forms?
Netlify Forms stores submissions without running your code first. To validate before storing, post the form to a function like this one instead, or check submissions after the fact with a function that reacts to them.
Should I verify every waitlist signup?
The fast lookup, yes. Mailbox checks count toward the 300 verified addresses a day (3,000 a month), so on a busy launch day consider running /v1/verify/batch on the list before you send instead.

Stop bad addresses in Netlify Functions 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 Netlify Functions setup will receive.