Skip to content

// email marketing and newsletters

Via API

beehiiv email verification with pingutil

beehiiv growth tools like the referral program, boosts and recommendations bring in subscribers fast, and some of them are throwaway or mistyped addresses that never open. A subscription.created webhook sends each new subscriber to your endpoint, pingutil verifies the mailbox, and the beehiiv API writes the result to a custom field or unsubscribes the address.

Where it connects: beehiiv publication webhook (subscription.created event) plus the API v2 update subscription by ID endpoint

What goes wrong without it

  • Referral rewards are getting farmed with temp-mail addresses, and we only notice when the milestone emails start bouncing.
  • Our open rate looks worse every month because new subscribers include addresses that were never going to read anything.
  • Advertisers ask about engaged readers, and we have no quick way to say how many subscribers are real.

What you can do with beehiiv and pingutil

  • Protect the referral program

    Verify every new subscription. Disposable and invalid addresses are unsubscribed before they count toward a referrer's next reward tier.

  • Segment on a verification custom field

    Write pingutil_status to a custom field so beehiiv segments can exclude risky and unknown subscribers from sends where bounces matter.

  • Clean an imported list

    Before migrating a list into beehiiv, run it through /v1/verify/batch or the dashboard CSV upload and import only the rows that are not invalid.

Set it up

  1. 1

    Create custom fields named pingutil_status and pingutil_reason in your beehiiv publication, and a beehiiv API key with access to subscriptions.

  2. 2

    Deploy the endpoint below on a public HTTPS URL.

  3. 3

    In beehiiv, go to Settings, open Webhooks, choose Create Webhook Endpoint, enter your URL and select Subscription Created.

  4. 4

    Sign up with a test address and confirm the custom fields are filled in on the subscriber profile.

  5. 5

    Build a segment that excludes pingutil_status values risky, unknown and invalid for your most important sends.

Flask receiver for beehiiv subscription.created
import os
import threading

import requests
from flask import Flask, request

app = Flask(__name__)
PUB = os.environ["BEEHIIV_PUBLICATION_ID"]  # pub_...
BEEHIIV = {"Authorization": "Bearer " + os.environ["BEEHIIV_API_KEY"]}


def verify(email):
    try:
        r = requests.post(
            "https://pingutil.com/v1/verify",
            headers={"Authorization": "Bearer " + os.environ["PINGUTIL_KEY"]},
            json={"email": email},
            timeout=30,
        )
        return r.json() if r.ok else None  # 429 quota_exceeded / 5xx: fail open
    except requests.RequestException:
        return None


def handle(sub_id, email):
    v = verify(email)
    if v is None:
        return
    body = {
        "custom_fields": [
            {"name": "pingutil_status", "value": v["status"]},
            {"name": "pingutil_reason", "value": v["reason"]},
        ]
    }
    if v["status"] == "invalid":
        body["unsubscribe"] = True
    requests.put(
        f"https://api.beehiiv.com/v2/publications/{PUB}/subscriptions/{sub_id}",
        headers=BEEHIIV,
        json=body,
        timeout=15,
    )


@app.post("/hooks/beehiiv")
def beehiiv_hook():
    # beehiiv signs deliveries; check the signature as described in its webhook docs before trusting the body.
    event = request.get_json(force=True)
    if event.get("event_type") == "subscription.created":
        data = event["data"]
        threading.Thread(target=handle, args=(data["id"], data["email"]), daemon=True).start()
    return "", 200

What to do with each result

pingutil resultAction in beehiiv
status: "invalid"Set unsubscribe: true on the subscription and record the reason in pingutil_reason.
reason: "disposable_domain"Unsubscribed with other invalid results, so it never counts toward a referral reward.
status: "risky" (accept_all, role_based, randomized_local_part)Keep the subscription, store pingutil_status, exclude from segments for sponsor sends.
status: "unknown"Store the field and re-check before a big send; the mail server gave no clear answer.

Limits to plan for

  • beehiiv webhooks are available on paid plans (and the free trial), with three endpoints on Lite. Custom fields must exist first; unknown field names come back as warnings and are not applied.
  • pingutil checks up to 300 addresses per account per day (3,000 a month). A boost or recommendation spike can pass that; the code fails open and leaves those subscribers unchecked. Those are Free plan limits; Enterprise has custom limits.
  • subscription.created fires before double opt-in. beehiiv also has subscription.confirmed if you only want to check people who confirmed.

beehiiv documentation

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

Common questions

Should I verify on subscription.created or subscription.confirmed?
Use subscription.created when you want to stop referral and reward abuse early. Use subscription.confirmed if you only care about readers who clicked the confirmation link, since unconfirmed addresses will not receive your posts anyway.
Does unsubscribing through the API delete the subscriber?
No. It changes the subscription status for the publication and keeps the record, so you can still see how many fake signups a growth channel produced.

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