Skip to content

// automation and data tools

Via API

Retool email verification with pingutil

Internal Retool tools are where support and ops look up users, approve accounts and fix bad data, usually without any way to tell whether an address is real. A REST API resource pointed at pingutil and a small JavaScript query add a verify button that shows status, reason, category and company next to the record.

Where it connects: REST API resource query, triggered from a JavaScript query with additionalScope

What goes wrong without it

  • Support asks engineering to check if a customer's email is real every time a password reset never arrives.
  • Our account review tool shows the email but nothing about whether it is disposable.
  • Ops approves trial accounts by eye and keeps letting temp-mail signups through.

What you can do with Retool and pingutil

  • Verify button on a user detail page

    Run /v1/verify for the selected user and show status, reason and did_you_mean, so support can tell a typo from a full mailbox.

  • Trial approval queue

    Run a fast lookup on every pending signup and highlight rows where verdict.is_spam is true before someone clicks approve.

  • Company context for account managers

    A full lookup returns company.name, company.industry and company.employee_size_estimate for a work email.

Set it up

  1. 1

    Create a REST API resource with base URL https://pingutil.com/v1 and a header Authorization: Bearer pk_live_... with your key.

  2. 2

    Add a query verifyEmail on that resource: POST to /verify with a JSON body field email set to {{ email }}.

  3. 3

    Add a JavaScript query that triggers verifyEmail with additionalScope for the selected row, as in the snippet.

  4. 4

    Bind a button to the JavaScript query and show the returned status and reason in a Statistic or Tag component.

  5. 5

    Restrict the app to the roles that need it, since every click spends from the account's daily verification budget.

JavaScript query: verify the selected users
// verifyEmail is a REST API resource query on a resource whose base URL is
// https://pingutil.com/v1 (Bearer key in the resource headers):
// POST /verify, JSON body { "email": "{{ email }}" }
const rows = table1.selectedRows || [];
const results = [];

for (const row of rows.slice(0, 20)) {
  try {
    const data = await verifyEmail.trigger({
      additionalScope: { email: row.email },
    });
    results.push({
      id: row.id,
      email: row.email,
      status: data.status,
      reason: data.reason,
      did_you_mean: data.did_you_mean,
    });
  } catch (err) {
    results.push({ id: row.id, email: row.email, status: 'unverified', reason: 'request_failed' });
  }
}

return results;

What to do with each result

pingutil resultAction in Retool
status = "valid"Green tag; support can rule out the address as the problem
status = "risky" with reason mailbox_full or accept_allAmber tag with the reason so support explains it to the user
status = "invalid"Red tag and a prompt to ask the user for a new address
verdict.is_spam = true (from /lookup)Disable the approve button for that trial row

Limits to plan for

  • Each click spends from the account's 300 verified addresses a day (3,000 a month) and 60 requests a minute, so cap multi-row checks. Those are Free plan limits; Enterprise has custom limits.
  • Verification can take up to about 25 seconds per address on slow mail servers; show a loading state.
  • Catch-all domains and servers that refuse to answer come back risky or unknown, not valid.

Retool documentation

Retool is a trademark of its owner. This integration uses Retool's documented extension points; it is not an official Retool app.

Common questions

Should the API key live in the query or the resource?
In the resource. Headers set on a REST API resource are sent with every request that uses it, so the key is not repeated in each query.
Can I verify a whole table at once?
Use a second resource query that POSTs up to 50 addresses to /verify/batch, and keep the Free plan budget of 300 addresses a day (3,000 a month) in mind.

Stop bad addresses in Retool 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 Retool setup will receive.