// forms and surveys
Via APIPaperform email verification with pingutil
Paperform is often used for bookings, payments and lead magnets, where the confirmation email is the whole point. A webhook endpoint can pull the email answer out of the data array, verify it with pingutil and flag bookings or leads whose address will not receive mail. Paperform sends the webhook after submission, so this flags and routes; it does not block the form.
Where it connects: Paperform webhooks (submission POST with a data array and custom headers)
What goes wrong without it
- Customers book a session through Paperform and swear they never got the confirmation.
- Our lead magnet form is mostly temp-mail addresses grabbing the PDF.
- We only notice a bad email when a paid booking has no way to reach the customer.
What you can do with Paperform and pingutil
Flag paid bookings with an unreachable address
When the address comes back invalid on a submission that includes a charge, alert your team so they can contact the customer another way before the booking date.
Keep lead magnet sign-ups honest
Skip adding disposable and invalid addresses to your email list, while still letting the visitor see the download page.
Suggest a corrected address
Store did_you_mean so the follow-up goes to jane@outlook.com when she typed jane@outlok.com.
Set it up
- 1
Create a pingutil key and a random PAPERFORM_SECRET; store both as Lambda environment variables.
- 2
In the Paperform question settings, give the email question the custom pre-fill key email.
- 3
Deploy the Lambda below behind a function URL.
- 4
In the form's integration settings, add a webhook to the function URL, enable custom headers and add x-webhook-secret with your secret.
- 5
Submit a test response and confirm the function logs a pingutil status.
import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
type Question = { title: string; type: string; key: string; custom_key: string | null; value: unknown };
async function verify(email: string) {
try {
const res = await fetch('https://pingutil.com/v1/verify', {
method: 'POST',
headers: { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' },
body: JSON.stringify({ email }),
signal: AbortSignal.timeout(7000), // Paperform gives the webhook about 10 seconds
});
return res.ok ? await res.json() : null;
} catch {
return null; // fail open
}
}
export const handler = async (event: APIGatewayProxyEventV2): Promise<APIGatewayProxyResultV2> => {
if (event.headers['x-webhook-secret'] !== process.env.PAPERFORM_SECRET) {
return { statusCode: 401, body: 'unauthorized' };
}
const raw = event.isBase64Encoded ? Buffer.from(event.body ?? '', 'base64').toString('utf8') : event.body ?? '{}';
const submission = JSON.parse(raw) as { submission_id: string; data: Question[]; charge: unknown };
const question = submission.data.find((q) => q.custom_key === 'email');
const email = typeof question?.value === 'string' ? question.value.trim() : '';
if (!email) return { statusCode: 200, body: 'ok' };
const result = await verify(email);
const status = result?.status ?? 'unchecked';
if (status === 'invalid' && submission.charge) {
await fetch(process.env.TEAM_ALERT_URL!, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
text: 'Paid Paperform booking ' + submission.submission_id + ' has an unreachable email: ' + email,
did_you_mean: result?.did_you_mean ?? null,
}),
});
} else if (status !== 'invalid') {
await fetch(process.env.LIST_WEBHOOK_URL!, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ email, email_status: status, paperform_submission_id: submission.submission_id }),
});
}
return { statusCode: 200, body: 'ok' };
};What to do with each result
| pingutil result | Action in Paperform |
|---|---|
| status: "valid" | Add the contact to your list or CRM. |
| status: "invalid" on a paid submission | Alert the team to reach the customer another way. |
| status: "invalid" on an unpaid submission | Do not add it to any list. |
| status: "risky" or "unknown" | Add with the status stored, and send to it after valid contacts. |
| did_you_mean is set | Include it in the alert or store it on the contact. |
Limits to plan for
- Paperform allows about 10 seconds per webhook and disables a webhook that keeps failing. The snippet caps the mailbox check at 7 seconds and always returns 200.
- Paperform does not sign webhooks; the custom header secret is the only check that a request came from your form.
- Webhooks are only on some Paperform plans, and they run after submission, so the respondent is never blocked.
Paperform documentation
Paperform is a trademark of its owner. This integration uses Paperform's documented extension points; it is not an official Paperform app.
Common questions
- How do I find the email answer in a Paperform webhook?
- Every question is an object in the data array with key, custom_key, type and value. Give the email question a custom pre-fill key and match on custom_key so the code survives form edits.
- Will a slow mail server make Paperform disable my webhook?
- Not with the 7 second cap in the snippet. If the check times out, the submission is forwarded as unchecked and the function still returns 200.
Stop bad addresses in Paperform 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 Paperform setup will receive.