// frameworks and platforms
Via APIAWS 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
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
Use a Node.js 22 or later runtime, which has global fetch and AbortSignal.timeout.
- 3
Raise the function timeout above the 3 second default, for example to 10 seconds.
- 4
Connect the function to an API Gateway HTTP API route or a function URL using payload format 2.0.
- 5
Deploy the handler; it decodes the body, calls /v1/lookup and /v1/verify, and returns statusCode, headers and body.
// 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 result | Action in AWS Lambda |
|---|---|
| verdict.is_spam: true | Return statusCode 422; skip the database write and the SES send. |
| status: invalid | Return 422 with did_you_mean. |
| status: risky or unknown | Create the user with a needs_review flag and send a confirmation email. |
| No answer, or too little time left | Create 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
- docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html
- docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html
- docs.aws.amazon.com/apigateway/latest/developerguide/http-api-develop-integrations-lambda.html
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.