Skip to content

// frameworks and platforms

Via API

AWS Lambda email verification with pingutil

A Lambda signup handler behind API Gateway usually checks the email with a regex and writes the user, so temp-mail accounts and bouncing addresses go straight into DynamoDB or your user pool. Calling pingutil from the handler rejects them first, with the mailbox check sized to the time the function has left.

Where it connects: Node.js Lambda handler behind an API Gateway HTTP API or function URL (payload format 2.0)

What goes wrong without it

  • Our serverless signup API is being hit with throwaway addresses to farm free credits.
  • SES is warning us about bounces from addresses that never existed.
  • Our first attempt at an email check made the function time out at the default 3 seconds.

What you can do with AWS Lambda and pingutil

  • Signup and lead APIs on API Gateway

    Reject disposable and invalid addresses with a 422 before the handler writes to your database or calls SES.

  • Time-aware mailbox checks

    context.getRemainingTimeInMillis() sizes the /v1/verify timeout, so the check can never push the function past its own timeout.

  • Warm-instance cache

    Domain categories are kept in module scope, which Lambda reuses across invocations in the same execution environment.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and store it as the PINGUTIL_KEY environment variable (or load it from Secrets Manager at init).

  2. 2

    Use a Node.js 22 or later runtime, which has global fetch and AbortSignal.timeout.

  3. 3

    Raise the function timeout above the 3 second default, for example to 10 seconds.

  4. 4

    Connect the function to an API Gateway HTTP API route or a function URL using payload format 2.0.

  5. 5

    Deploy the handler; it decodes the body, calls /v1/lookup and /v1/verify, and returns statusCode, headers and body.

index.mjs
// index.mjs  (Node.js 22+ runtime, behind an API Gateway HTTP API or a function URL, payload format 2.0)
// Set the function timeout above the default 3 seconds, for example 10 seconds.
const API = 'https://pingutil.com/v1'

// Lives as long as the execution environment. Only domain categories go here, no user data.
const categories = new Map() // domain -> { category, expires }

async function pingutil(path, body, timeoutMs) {
  try {
    const res = await fetch(API + 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() : null
  } catch {
    return null // timeout or network error: fail open
  }
}

const reply = (statusCode, payload) => ({
  statusCode,
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(payload),
})

export const handler = async (event, context) => {
  const raw = event.isBase64Encoded ? Buffer.from(event.body ?? '', 'base64').toString() : event.body
  let email = ''
  try {
    email = String(JSON.parse(raw ?? '{}').email ?? '').trim().toLowerCase()
  } catch {
    return reply(400, { error: 'Body must be JSON.' })
  }
  const domain = email.split('@')[1]
  if (!domain) return reply(422, { error: 'Enter a valid email address.' })

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

  const lookup = await pingutil('/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 reply(422, { error: 'Please use a different email address.' })
  }

  // Never let the mailbox check outlive the function: keep a second in reserve.
  const budget = Math.min(5000, context.getRemainingTimeInMillis() - 1000)
  const check = budget > 500 ? await pingutil('/verify', { email }, budget) : null
  if (check?.status === 'invalid') {
    return reply(422, { error: 'That mailbox does not exist.', did_you_mean: check.did_you_mean })
  }

  // Create the user here. Flag risky, unknown and unchecked addresses for review.
  return reply(201, { ok: true, category: lookup?.category ?? null, needs_review: check?.status !== 'valid' })
}

What to do with each result

pingutil resultAction in AWS Lambda
verdict.is_spam: trueReturn statusCode 422; skip the database write and the SES send.
status: invalidReturn 422 with did_you_mean.
status: risky or unknownCreate the user with a needs_review flag and send a confirmation email.
No answer, or too little time leftCreate the user and re-check the address asynchronously.

Limits to plan for

  • Lambda's default timeout is 3 seconds, too short for a mailbox check on a slow server; raise it. API Gateway HTTP APIs also cap integration time at 30 seconds.
  • AWS advises against keeping user data in the execution environment between invocations; the example caches only domain categories.
  • 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, never valid. Those are Free plan limits; Enterprise has custom limits.

AWS Lambda documentation

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

Common questions

Should I use a Cognito pre sign-up trigger instead?
If your users sign up through Amazon Cognito, yes: the same checks fit the pre sign-up Lambda trigger. This handler is for signup and lead endpoints you run yourself behind API Gateway or a function URL.
How do I keep the cold start small?
The example has no dependencies: global fetch is built into the Node.js runtime. Keep the key in an environment variable or fetch it once at init with top-level await.

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