Skip to content

// frameworks and platforms

Via API

Flask email verification with pingutil

WTForms' Email validator checks the format of an address, so a Flask signup form accepts throwaway inboxes and addresses that will bounce. An inline validate_email method that calls pingutil turns those into normal field errors, shown by the template you already render.

Where it connects: Flask-WTF form with a WTForms inline validator (validate_email)

What goes wrong without it

  • Our Flask app sends a welcome email on signup and the bounces from fake addresses are hurting our sender reputation.
  • Bots hit the signup form with temp-mail addresses to claim the free tier.
  • We have no idea which signups are from companies and which are personal accounts.

What you can do with Flask and pingutil

  • Field errors without new templates

    Raise ValidationError from validate_email and the message appears in form.email.errors, exactly where your template already shows format errors.

  • Skip the call when the format is wrong

    The inline validator returns early if Email() already failed, so malformed input never costs an API call.

  • Keep the result for the view

    The form stores category and status on form.email_check after validation, so the view can save them with the user.

Set it up

  1. 1

    Create an API key in the pingutil dashboard and set PINGUTIL_KEY in the environment.

  2. 2

    Install flask-wtf, email-validator and requests, and set a SECRET_KEY for CSRF.

  3. 3

    Add a validate_email(self, field) method to the signup FlaskForm; WTForms runs it after the field's own validators.

  4. 4

    Call /v1/lookup with skip_enrichment, then optionally /v1/verify, raising ValidationError on spam or invalid results.

  5. 5

    Use form.validate_on_submit() in the view and save form.email_check with the new user.

app.py
# app.py  (Flask 3, Flask-WTF; pip install flask flask-wtf email-validator requests)
import os
import time

import requests
from flask import Flask, redirect, render_template, url_for
from flask_wtf import FlaskForm
from wtforms import EmailField, PasswordField
from wtforms.validators import DataRequired, Email, Length, ValidationError

app = Flask(__name__)
app.config["SECRET_KEY"] = os.environ["FLASK_SECRET_KEY"]

API = "https://pingutil.com/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['PINGUTIL_KEY']}"
categories: dict[str, tuple[str, float]] = {}  # per process; use Redis to share


def pingutil(path, payload, read_timeout):
    """Parsed JSON, or None when pingutil is slow, down or rate limited (fail open)."""
    try:
        r = session.post(f"{API}{path}", json=payload, timeout=(1, read_timeout))
    except requests.RequestException:
        return None
    if r.status_code == 401:
        app.logger.error("pingutil rejected the API key")
    return r.json() if r.ok else None


class SignupForm(FlaskForm):
    email = EmailField("Email", validators=[DataRequired(), Email()])
    password = PasswordField("Password", validators=[DataRequired(), Length(min=12)])
    email_check: dict = {}

    def validate_email(self, field):  # WTForms inline validator for the email field
        if field.errors:  # Email() already failed, skip the API call
            return
        email = field.data.strip().lower()
        domain = email.rsplit("@", 1)[1]

        cached = categories.get(domain)
        if cached and cached[1] > time.time() and cached[0] == "disposable":
            raise ValidationError("Please use a permanent email address.")

        lookup = pingutil("/lookup", {"input": email, "skip_enrichment": True}, 2)
        if lookup:
            categories[lookup["domain"]] = (lookup["category"], time.time() + 86400)
            if lookup["verdict"]["is_spam"]:
                raise ValidationError("This email address can't be used. Please use a different one.")

        check = pingutil("/verify", {"email": email}, 5)
        if check and check["status"] == "invalid":
            hint = f" Did you mean {check['did_you_mean']}?" if check["did_you_mean"] else ""
            raise ValidationError("That mailbox does not exist." + hint)

        self.email_check = {
            "category": lookup["category"] if lookup else None,
            "status": check["status"] if check else None,
        }


@app.route("/signup", methods=["GET", "POST"])
def signup():
    form = SignupForm()
    if form.validate_on_submit():
        # create_user(form.email.data, form.password.data, **form.email_check)
        return redirect(url_for("welcome"))
    return render_template("signup.html", form=form)


@app.route("/welcome")
def welcome():
    return "Check your inbox to confirm your address."

What to do with each result

pingutil resultAction in Flask
verdict.is_spam: trueRaise ValidationError; validate_on_submit() returns False and the form re-renders.
status: invalid with did_you_meanRaise ValidationError including the suggestion.
status: risky or unknownAccept; send the confirmation email and hold perks until it is clicked.
No answer (timeout or error)Accept and mark the account for a later re-check.

Limits to plan for

  • Validation runs in the request thread, so a slow answer holds that worker. The example uses a 1 s connect timeout and 2 s or 5 s read timeouts.
  • The category dict lives per process; with Gunicorn workers, use Redis or Flask-Caching with a shared backend.
  • Catch-all domains come back risky, not valid. Per-account defaults are 60 requests a minute, 300 verified addresses and 2,000 lookups a day (3,000 and 30,000 a month). Those are Free plan limits; Enterprise has custom limits.

Flask documentation

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

Common questions

Can I do this without Flask-WTF?
Yes. Call the same pingutil helper in the view after reading request.form and return the template with an error. The inline validator is just the tidiest place when you already use WTForms.
Why not cache the whole response per domain?
Because the verdict depends on the full address: a machine-generated local part is flagged even on gmail.com. Cache the domain category, check the verdict per address.

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