Skip to content

// forms and surveys

Via API

Paperform 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. 1

    Create a pingutil key and a random PAPERFORM_SECRET; store both as Lambda environment variables.

  2. 2

    In the Paperform question settings, give the email question the custom pre-fill key email.

  3. 3

    Deploy the Lambda below behind a function URL.

  4. 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. 5

    Submit a test response and confirm the function logs a pingutil status.

AWS Lambda (function URL) receiving Paperform webhooks
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 resultAction in Paperform
status: "valid"Add the contact to your list or CRM.
status: "invalid" on a paid submissionAlert the team to reach the customer another way.
status: "invalid" on an unpaid submissionDo 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 setInclude 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.