// frameworks and platforms
Via APIExpress email verification with pingutil
In an Express app the signup handler usually trusts req.body.email once a regex passes, so throwaway inboxes and dead addresses end up as users and bounce your first email. A small middleware in front of the route asks pingutil whether the address is disposable or machine-generated, optionally checks the mailbox, and attaches the result to res.locals for the handler.
Where it connects: Express route middleware on the signup route (Express 5)
What goes wrong without it
- Someone scripted our /signup route and created a few hundred accounts on rotating temp-mail domains overnight.
- Our confirmation emails keep bouncing and our email provider is warning us about the bounce rate.
- We copied a disposable-domain list into the repo a year ago and nobody has updated it since.
What you can do with Express and pingutil
Reusable middleware for every entry point
Mount the same screenEmail() middleware on /signup, /invite and /newsletter. Each route gets the same rules and the result on res.locals.emailCheck.
Reject throwaways with a 422
When verdict.is_spam is true the middleware answers 422 before your handler runs, so no user row, session or welcome email is created.
Flag instead of block for uncertain results
risky and unknown results pass through with their status attached, so the handler can hold free credits until the user clicks the confirmation link.
Set it up
- 1
Create an API key in the pingutil dashboard and set PINGUTIL_KEY in the server environment.
- 2
Make sure the signup route parses its body (express.json() or express.urlencoded()); in Express 5 req.body is undefined without a parser.
- 3
Add the screenEmail middleware, which calls /v1/lookup with skip_enrichment: true and, if enabled, /v1/verify, each with AbortSignal.timeout.
- 4
Mount it before your handler: app.post("/signup", screenEmail({ verifyMailbox: true }), handler).
- 5
In the handler, read res.locals.emailCheck and store category and status with the user.
// middleware/screen-email.js (Express 5, Node.js 20+, ESM)
const API = 'https://pingutil.com/v1'
const DAY_MS = 86_400_000
// Category belongs to the domain, so it is safe to cache per domain. The verdict
// is about the address (randomized local parts), so never cache it per domain.
// Use Redis instead of a Map when you run more than one process.
const categories = new Map() // domain -> { category, expires }
let backoffUntil = 0
// Parsed JSON, or null when pingutil is slow, down or rate limited (fail open).
async function pingutil(path, body, timeoutMs) {
if (Date.now() < backoffUntil) return null
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 === 429) {
const { retry_after_seconds } = await res.json().catch(() => ({}))
backoffUntil = Date.now() + (Number(retry_after_seconds) || 60) * 1000
return null
}
if (res.status === 401) console.error('pingutil: API key rejected')
return res.ok ? await res.json() : null
} catch {
return null
}
}
export function screenEmail({ verifyMailbox = false } = {}) {
return async (req, res, next) => {
const email = String(req.body?.email ?? '').trim().toLowerCase()
const domain = email.split('@')[1]
if (!domain) return res.status(422).json({ error: 'Enter a valid email address.' })
const cached = categories.get(domain)
if (cached && cached.expires > Date.now() && cached.category === 'disposable') {
return res.status(422).json({ 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() + DAY_MS })
if (lookup.verdict.is_spam) {
return res.status(422).json({ error: 'Please use a different email address.' })
}
}
let verification = null
if (verifyMailbox) {
verification = await pingutil('/verify', { email }, 5000)
if (verification?.status === 'invalid') {
return res.status(422).json({
error: 'That mailbox does not exist.',
did_you_mean: verification.did_you_mean,
})
}
}
res.locals.emailCheck = {
category: lookup?.category ?? null,
lowTrust: lookup?.verdict.low_trust ?? false,
status: verification?.status ?? null, // valid | risky | unknown | null
}
next()
}
}
// app.js
import express from 'express'
import { screenEmail } from './middleware/screen-email.js'
const app = express()
app.use(express.json({ limit: '10kb' }))
app.post('/signup', screenEmail({ verifyMailbox: true }), async (req, res) => {
// await createUser(req.body, res.locals.emailCheck) // Express 5 forwards rejections to next()
res.status(201).json({ ok: true })
})
app.listen(3000)What to do with each result
| pingutil result | Action in Express |
|---|---|
| verdict.is_spam: true | Respond 422 from the middleware and never call next(). |
| status: invalid | Respond 422 with did_you_mean so the client can offer the corrected address. |
| verdict.low_trust: true (role or system address) | Call next() but keep lowTrust on res.locals for review or a stricter trial. |
| status: risky or unknown | Create the user and require the confirmation link before granting rewards. |
| No answer (timeout, 429, network) | Call next() with a null status and re-check the address later. |
Limits to plan for
- The in-memory Map and backoff are per process. With several Node processes or containers, move them to Redis so the cache and the 429 backoff are shared.
- A mailbox check can take seconds on slow mail servers, so the middleware caps it at 5 s and fails open. Catch-all domains are reported as risky, not valid.
- Per-account defaults: 60 requests a minute, 300 verified addresses and 2,000 lookups a day (3,000 and 30,000 a month); past them the API returns 429. Those are Free plan limits; Enterprise has custom limits.
Express documentation
- expressjs.com/en/guide/writing-middleware.html
- expressjs.com/en/guide/using-middleware.html
- expressjs.com/en/guide/error-handling.html
Express is a trademark of its owner. This integration uses Express's documented extension points; it is not an official Express app.
Common questions
- Do I need a try/catch around the async middleware in Express 5?
- Not for errors you want Express to handle: in Express 5 a rejected promise from an async handler or middleware is passed to next() automatically. The pingutil helper still catches its own errors, because a slow or failing API should let the signup through, not trigger your error handler.
- Why cache the category per domain but not the verdict?
- Category is a property of the domain, so every address at a disposable domain shares it. The verdict also looks at the local part: two Gmail addresses can get different answers if one is machine-generated, so it has to be checked per address.
Stop bad addresses in Express 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 Express setup will receive.