Skip to content

// website builders and cms

Via API

Drupal email verification with pingutil

Drupal sites with open registration collect accounts on temp-mail domains and mistyped addresses, and the welcome or verification email bounces for each one. A small custom module can alter user_register_form, add a #validate handler that sends the address to pingutil, and set a form error on the mail field before the user entity is saved. If pingutil times out or returns an error, the handler does nothing and Drupal registers the user as usual.

Where it connects: hook_form_FORM_ID_alter() on user_register_form, adding a #validate handler (Drupal 10 and 11)

What goes wrong without it

  • Visitors can create accounts without approval, and the people list now has pages of users on yopmail and guerrillamail that never verified.
  • Our "verify your email" messages bounce because people type gmial.com, and those users then open a ticket saying they never got the link.
  • The honeypot module stopped the dumbest bots, but humans paid to register still come through with throwaway addresses.

What you can do with Drupal and pingutil

  • Reject dead and disposable addresses on /user/register

    The #validate handler calls /v1/verify and sets an error on the mail field when status is invalid, which covers disposable domains, domains with no mail server and mailboxes the server says do not exist. The account is never created.

  • Suggest the fix for a typo instead of a generic error

    When the response carries did_you_mean (for example jane@gmail.com for jane@gmial.com), show it in the error message so the visitor can correct the field and submit again.

  • Leave administrator-created accounts alone

    The same form ID renders at /admin/people/create. Skip the check for users with the administer users permission so staff can create accounts for any address.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and add it to settings.php as $settings['pingutil_api_key'] = getenv('PINGUTIL_API_KEY'); so it stays out of configuration exports.

  2. 2

    Create modules/custom/pingutil_signup with a pingutil_signup.info.yml (type: module, core_version_requirement: ^10 || ^11) and the .module file below.

  3. 3

    Enable the module with drush en pingutil_signup or from Extend, then clear caches so the form alter is picked up.

  4. 4

    Register with test@mailinator.com and with a mistyped Gmail address to confirm the mail field shows the error, then with your own address to confirm it passes.

  5. 5

    Watch the pingutil_signup channel in Recent log messages for skipped checks; those are the fail-open cases.

modules/custom/pingutil_signup/pingutil_signup.module
<?php

/**
 * @file
 * Verifies the email on user_register_form with pingutil. Fails open.
 */

use Drupal\Core\Form\FormStateInterface;
use Drupal\Core\Site\Settings;
use GuzzleHttp\Exception\GuzzleException;

/**
 * Implements hook_form_FORM_ID_alter() for user_register_form.
 */
function pingutil_signup_form_user_register_form_alter(array &$form, FormStateInterface $form_state, $form_id): void {
  // Staff creating accounts at /admin/people/create skip the check.
  if (\Drupal::currentUser()->hasPermission('administer users')) {
    return;
  }
  $form['#validate'][] = 'pingutil_signup_validate_mail';
}

/**
 * Form validation handler: sets an error on "mail" for undeliverable addresses.
 */
function pingutil_signup_validate_mail(array &$form, FormStateInterface $form_state): void {
  $mail = trim((string) $form_state->getValue('mail'));
  $key = Settings::get('pingutil_api_key');
  // Core already flagged the form (empty, malformed, taken): skip the call.
  if ($mail === '' || !$key || $form_state->getErrors()) {
    return;
  }

  try {
    $response = \Drupal::httpClient()->post('https://pingutil.com/v1/verify', [
      'headers' => ['Authorization' => 'Bearer ' . $key],
      'json' => ['email' => $mail],
      'connect_timeout' => 2,
      'timeout' => 6,
      'http_errors' => FALSE,
    ]);
  }
  catch (GuzzleException $e) {
    \Drupal::logger('pingutil_signup')->warning('pingutil skipped: @msg', ['@msg' => $e->getMessage()]);
    // Timeout or network error: fail open.
    return;
  }

  // 429 quota_exceeded / rate_limited or 5xx: fail open.
  if ($response->getStatusCode() !== 200) {
    return;
  }
  $result = json_decode((string) $response->getBody(), TRUE);
  if (!is_array($result)) {
    return;
  }

  if (!empty($result['did_you_mean']) && $result['status'] !== 'valid') {
    $form_state->setErrorByName('mail', t('That address looks mistyped. Did you mean @suggestion?', [
      '@suggestion' => $result['did_you_mean'],
    ]));
  }
  elseif ($result['status'] === 'invalid') {
    $form_state->setErrorByName('mail', t('Please use an email address that can receive mail.'));
  }
}

What to do with each result

pingutil resultAction in Drupal
status: "invalid" (disposable_domain, no_mx, mailbox_not_found)setErrorByName('mail') in the #validate handler; the user entity is not saved.
did_you_mean set and status not "valid"Show the suggested address in the form error so the visitor can fix it.
status: "risky" (accept_all, role_based)Let the registration through; consider requiring admin approval for these if abuse continues.
status: "unknown", timeout, 429 or 5xxReturn without an error so Drupal registers the user as usual.

Limits to plan for

  • A mailbox check can take several seconds on slow mail servers, so the handler waits at most 6 seconds and then lets the form submit. Slow domains pass unchecked.
  • Form validation handlers only run for the HTML form. Accounts created through the REST user registration resource, JSON:API or drush skip this check; cover those with an entity validation constraint if you expose them.
  • Each submit that reaches the handler uses one of the Free plan's 300 verifications a day (3,000 a month). A bot wave can use the daily budget, after which the check fails open until 00:00 UTC.

Common questions

Can I write this as an OOP hook in Drupal 11?
Yes. Drupal 11.1 and later can discover hooks as methods with the #[Hook] attribute in a class under src/Hook. The procedural function in the .module file shown here still works on Drupal 10 and 11, which is why the example uses it.
Why /v1/verify here and not the fast lookup?
Drupal usually sends a verification email at registration, so a dead mailbox or a typo is the expensive case. If you only want to block disposable and random addresses with no wait, call /v1/lookup with skip_enrichment: true and block on verdict.is_spam instead.

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