// email marketing and newsletters
Via APIbeehiiv 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
Create custom fields named pingutil_status and pingutil_reason in your beehiiv publication, and a beehiiv API key with access to subscriptions.
- 2
Deploy the endpoint below on a public HTTPS URL.
- 3
In beehiiv, go to Settings, open Webhooks, choose Create Webhook Endpoint, enter your URL and select Subscription Created.
- 4
Sign up with a test address and confirm the custom fields are filled in on the subscriber profile.
- 5
Build a segment that excludes pingutil_status values risky, unknown and invalid for your most important sends.
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 "", 200What to do with each result
| pingutil result | Action 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
- www.beehiiv.com/support/article/18034325358743-how-to-use-beehiiv-webhooks
- developers.beehiiv.com/webhooks/subscription/created
- developers.beehiiv.com/api-reference/subscriptions/put
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.