// transactional email
Via APIMailgun email verification with pingutil
Mailgun will accept and queue a message to any syntactically valid address, then report a permanent_fail when the inbox does not exist. Verifying the address with pingutil before messages.create stops most of those bounces at the source, and the permanent_fail webhook tells you which users still need to fix their address.
Where it connects: Your code before messages.create, plus Mailgun webhooks (permanent_fail)
What goes wrong without it
- Half our permanent_fail webhooks are from addresses that were obviously wrong the moment the user typed them.
- We send from a shared sending domain for several products, so one product's junk signups drag down deliverability for all of them.
- Bots sign up with random strings at real-looking domains, and every one of them costs us a send and a bounce.
What you can do with Mailgun and pingutil
Screen signups in milliseconds, verify the mailbox in the background
Run /v1/lookup with skip_enrichment: true inline to reject disposable and randomized addresses fast, then call /v1/verify from a job before the first Mailgun send.
Catch randomized bot addresses
verdict.is_spam with reason randomized_local_part flags machine-made local parts like ccjxx90sze@ even on domains that resolve and accept mail.
Flag users after a permanent failure
When Mailgun posts permanent_fail for a user's address, mark it undeliverable and prompt them to update it. Verify the new address before sending again.
Set it up
- 1
Add PINGUTIL_KEY to the environment that holds your Mailgun API key and sending domain.
- 2
In the signup handler, call /v1/lookup with skip_enrichment: true and reject verdict.is_spam.
- 3
Queue a job that calls /v1/verify for the address before the welcome email.
- 4
In the job, skip the send for status invalid and call mg.messages.create for everything else.
- 5
Add a webhook for permanent_fail in the Mailgun control panel and point it at an endpoint that flags the user.
import FormData from 'form-data';
import Mailgun from 'mailgun.js';
const mg = new Mailgun(FormData).client({ username: 'api', key: process.env.MAILGUN_API_KEY! });
const PINGUTIL = { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' };
// 1) Inline at signup: fast classification, no mailbox check
export async function screenSignup(email: string): Promise<boolean> {
try {
const res = await fetch('https://pingutil.com/v1/lookup', {
method: 'POST',
headers: PINGUTIL,
body: JSON.stringify({ input: email, skip_enrichment: true }),
signal: AbortSignal.timeout(2000),
});
if (!res.ok) return true; // fail open
const data = await res.json();
return !data.verdict.is_spam; // disposable, reputation-flagged or randomized
} catch {
return true;
}
}
// 2) In the background job, before the first email
export async function sendWelcome(email: string) {
let status = 'unknown';
try {
const res = await fetch('https://pingutil.com/v1/verify', {
method: 'POST',
headers: PINGUTIL,
body: JSON.stringify({ email }),
signal: AbortSignal.timeout(30000), // a job can afford to wait for slow servers
});
if (res.ok) status = (await res.json()).status;
} catch {
// network error or timeout: send anyway
}
if (status === 'invalid') {
await markEmailUndeliverable(email);
return;
}
await mg.messages.create(process.env.MAILGUN_DOMAIN!, {
from: 'YourApp <hello@' + process.env.MAILGUN_DOMAIN + '>',
to: [email],
subject: 'Welcome to YourApp',
text: 'Thanks for signing up.',
});
}
declare function markEmailUndeliverable(email: string): Promise<void>;What to do with each result
| pingutil result | Action in Mailgun |
|---|---|
| verdict.is_spam true (disposable_domain or randomized_local_part) | Reject at signup. No Mailgun message is queued. |
| status invalid (mailbox_not_found, no_mx, null_mx) | Skip messages.create and ask the user for a working address. |
| status risky, reason accept_all | Send, and rely on the permanent_fail webhook if it bounces. |
| status unknown (greylisted, timeout) | Send. A later re-check may get a definitive answer once the server stops deferring. |
Limits to plan for
- Mailgun offers its own address validation product. Verifying with pingutil at capture makes sense if you want the category (disposable, free, company) and verification from one vendor across all your tools; otherwise either works.
- pingutil allows 300 verified addresses and 2,000 lookups a day (3,000 and 30,000 a month) per account, with 60 requests a minute. Over a budget the API returns 429 quota_exceeded, which your code should treat as allow. Those are Free plan limits; Enterprise has custom limits.
- Mailbox checks can't confirm catch-all domains or servers that refuse to answer; those come back risky or unknown, never valid.
Mailgun documentation
- documentation.mailgun.com/docs/mailgun/user-manual/webhooks/webhooks
- documentation.mailgun.com/docs/validate/
Mailgun is a trademark of its owner. This integration uses Mailgun's documented extension points; it is not an official Mailgun app.
Common questions
- Should I call pingutil inside the Mailgun webhook?
- Usually not. By the time permanent_fail arrives, Mailgun has already told you the mailbox is gone. Use pingutil earlier, when the address is entered, and again when the user replaces it.
- Is the lookup call enough on its own?
- It catches disposable, randomized and role addresses in milliseconds but does not check the mailbox. Pair it with /v1/verify before the first send if bounces are the concern.
Stop bad addresses in Mailgun 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 Mailgun setup will receive.