Skip to content

// frameworks and platforms

Via API

Next.js email verification with pingutil

A Next.js signup form usually checks only that the email field looks like an email, so temp-mail accounts and typos go straight into your database and your welcome emails bounce. Calling pingutil from the Server Action that handles the form rejects disposable and machine-generated addresses before the user is created, and an optional mailbox check catches dead addresses and typos like gmial.com.

Where it connects: Next.js App Router Server Action (form action with useActionState)

What goes wrong without it

  • Our free tier is being farmed by temp-mail accounts and every one of them shows up as an activated user.
  • Half our verification emails bounce because people mistype their address and the form accepts anything with an @ in it.
  • The Server Action is a public POST endpoint, so client-side checks in the form component stop nobody.

What you can do with Next.js and pingutil

  • Block disposable signups in the action

    Call /v1/lookup with skip_enrichment: true inside the Server Action and return an error to useActionState when verdict.is_spam is true. The check runs only on submit, on the server, where your API key stays private.

  • Catch typos before the confirmation email

    Run /v1/verify with a short timeout after the lookup. An invalid result with did_you_mean set lets the form show "Did you mean jane@gmail.com?" instead of sending a confirmation email that will bounce.

  • Store the category for onboarding

    Save category with the new user. A company address can go to a team-oriented onboarding flow, a free webmail address to the individual one, without asking the user anything extra.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and add it to .env.local as PINGUTIL_KEY, without the NEXT_PUBLIC_ prefix so it never reaches the browser.

  2. 2

    In the file that defines your signup Server Action (marked with the "use server" directive), add a small helper that POSTs to pingutil with AbortSignal.timeout and returns null on any failure.

  3. 3

    Call /v1/lookup with skip_enrichment: true first and return a form error when verdict.is_spam is true.

  4. 4

    Optionally call /v1/verify with a timeout of a few seconds and return a did_you_mean hint when status is invalid.

  5. 5

    Create the user, saving category and whether the address still needs review (risky, unknown or unchecked).

  6. 6

    Render errors from the action state with useActionState in your Client Component form.

app/signup/actions.ts
// app/signup/actions.ts  (Next.js App Router, Server Action)
'use server'

import { redirect } from 'next/navigation'
import { createUser } from '@/lib/users' // your own persistence

const API = 'https://pingutil.com/v1'

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

// Returns null when pingutil is slow, down or rate limited, so the caller fails open.
async function pingutil<T>(path: string, body: object, timeoutMs: number): Promise<T | null> {
  try {
    const res = await fetch(`${API}${path}`, {
      method: 'POST',
      headers: {
        authorization: `Bearer ${process.env.PINGUTIL_KEY}`, // no NEXT_PUBLIC_ prefix
        'content-type': 'application/json',
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(timeoutMs),
      cache: 'no-store',
    })
    if (res.status === 401) console.error('pingutil: API key rejected, check PINGUTIL_KEY')
    return res.ok ? ((await res.json()) as T) : null
  } catch {
    return null // TimeoutError or network failure
  }
}

export type SignupState = { error?: string; email?: string }

export async function signup(_prev: SignupState, formData: FormData): Promise<SignupState> {
  const email = String(formData.get('email') ?? '').trim().toLowerCase()
  const password = String(formData.get('password') ?? '')
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    return { error: 'Enter a valid email address.', email }
  }

  // 1. Fast classification: no LLM call, answers in milliseconds.
  const lookup = await pingutil<Lookup>('/lookup', { input: email, skip_enrichment: true }, 2000)
  if (lookup?.verdict.is_spam) {
    return {
      email,
      error: lookup.verdict.reason === 'disposable_domain'
        ? "Temporary email addresses can't be used. Please use a permanent one."
        : "We couldn't accept this email address. Please use a different one.",
    }
  }

  // 2. Optional mailbox check. Slow mail servers can take seconds, so cap it.
  const check = await pingutil<Verification>('/verify', { email }, 4000)
  if (check?.status === 'invalid') {
    return {
      email,
      error: check.did_you_mean ? `Did you mean ${check.did_you_mean}?` : 'That mailbox does not exist.',
    }
  }

  await createUser({
    email,
    password,
    emailCategory: lookup?.category ?? null, // "company" vs "free" drives onboarding and routing
    needsEmailReview: !lookup || !check || check.status !== 'valid', // risky, unknown or unchecked
  })
  redirect('/welcome') // outside any try/catch: redirect throws to end the action
}

What to do with each result

pingutil resultAction in Next.js
verdict.is_spam: true (reason disposable_domain)Return an error from the action asking for a permanent address; do not create the user.
verdict.is_spam: true (reason randomized_local_part)Return a generic "use a different address" error, so bots learn nothing about the rule.
status: invalid with did_you_meanReturn "Did you mean ...?" and keep the email in the form state so the user can fix it.
status: risky or unknownCreate the account but mark it for review or require the confirmation link before granting credits.
category: companySend the user to the team onboarding path and pass the domain to your CRM.

Limits to plan for

  • Server Actions run on every submit with the user waiting, so keep timeouts short. Fast-mode lookups normally answer in milliseconds, while a mailbox check can take seconds on slow mail servers (up to about 25 s), which is why the snippet caps it at 4 s and fails open.
  • Per-account defaults are 60 requests a minute, 300 verified addresses and 2,000 lookups a day (3,000 and 30,000 a month). Over a limit the API answers 429 and the helper treats it as unavailable. Those are Free plan limits; Enterprise has custom limits.
  • Catch-all domains come back as risky, never valid, so do not block on risky alone.

Next.js documentation

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

Common questions

Should the check go in Next.js middleware or in the Server Action?
In the Server Action. That is where the form data is parsed and the account is created, and it runs only on submit. Middleware runs on every matching request and is the wrong place to read and judge a form body.
What happens to signups if pingutil is slow or down?
With the helper in the example they go through. Any timeout, network error or non-2xx answer returns null, the action skips that check, and the user is saved with a flag so you can verify the address later.

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