// email marketing and newsletters
Via APIButtondown email verification with pingutil
Buttondown newsletters often grow through a single embed form, and spam signups or typos end up waiting in your subscriber list for the next issue. A subscriber.created webhook sends the new subscriber's ID to your endpoint, which fetches the address, verifies it with pingutil, and tags or removes the subscriber through the Buttondown API.
Where it connects: Buttondown webhook (subscriber.created event) plus the API PATCH and DELETE /v1/subscribers/{id_or_email} endpoints
What goes wrong without it
- Someone scripted our embed form and we got a few hundred random-looking signups overnight.
- Each issue goes out to subscribers who will never read it, and the bounces make our sending reputation worse.
- I run the newsletter alone and do not want to clean the list by hand every month.
What you can do with Buttondown and pingutil
Drop scripted signups automatically
Invalid and disposable addresses are deleted before they confirm, and randomized local parts get a review tag.
Tag risky subscribers
Catch-all and unknown results get a pingutil-risky tag, so you can filter them in Buttondown before a paid launch.
Store the reason in metadata
Write the pingutil status and reason to subscriber metadata so the decision is visible on the subscriber page later.
Set it up
- 1
Create a Buttondown API key and a pingutil API key.
- 2
Deploy the endpoint below with a secret path.
- 3
In Buttondown, create a webhook for the subscriber.created event pointing at your endpoint (from the dashboard or the /v1/webhooks API).
- 4
Sign up with a test address on your embed form and check the subscriber's tags and metadata.
import os
import threading
import requests
from flask import Flask, request
app = Flask(__name__)
BD = "https://api.buttondown.com/v1"
BD_HEADERS = {"Authorization": "Token " + os.environ["BUTTONDOWN_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 / 5xx: fail open
except requests.RequestException:
return None
def handle(subscriber_id):
sub = requests.get(f"{BD}/subscribers/{subscriber_id}", headers=BD_HEADERS, timeout=15).json()
v = verify(sub["email_address"])
if v is None:
return
if v["status"] == "invalid":
# New signups are usually unactivated, which can't be unsubscribed; delete instead.
requests.delete(f"{BD}/subscribers/{subscriber_id}", headers=BD_HEADERS, timeout=15)
return
tags = list(sub.get("tags", []))
if v["status"] != "valid":
tags.append("pingutil-" + v["status"])
metadata = dict(sub.get("metadata", {}), pingutil_status=v["status"], pingutil_reason=v["reason"])
requests.patch(f"{BD}/subscribers/{subscriber_id}", headers=BD_HEADERS,
json={"tags": tags, "metadata": metadata}, timeout=15)
@app.post("/hooks/buttondown/<secret>")
def buttondown_hook(secret):
if secret != os.environ["HOOK_SECRET"]:
return "", 401
event = request.get_json(force=True)
if event.get("event_type") == "subscriber.created":
threading.Thread(target=handle, args=(event["data"]["subscriber"],), daemon=True).start()
return "", 200What to do with each result
| pingutil result | Action in Buttondown |
|---|---|
| status: "invalid" | DELETE the subscriber; unactivated subscribers cannot be set to unsubscribed. |
| reason: "randomized_local_part" | Comes back risky; add pingutil-risky and review, since it often means a scripted signup. |
| status: "risky" or "unknown" | Add a pingutil tag and keep the subscriber. |
| status: "valid" | Write metadata only; nothing else changes. |
Limits to plan for
- Buttondown notes that webhook events can arrive out of order, which is why the handler re-fetches the subscriber from the API instead of trusting the payload.
- pingutil checks up to 300 addresses per account per day (3,000 a month). A scripted signup flood beyond that is left unchecked; pair this with a captcha on the form. Those are Free plan limits; Enterprise has custom limits.
- Catch-all domains are reported as risky, not valid, so do not delete on risky results.
Buttondown documentation
- docs.buttondown.com/event-types
- docs.buttondown.com/api-subscribers-update
- docs.buttondown.com/api-authentication
Buttondown is a trademark of its owner. This integration uses Buttondown's documented extension points; it is not an official Buttondown app.
Common questions
- Why does the handler call the API before verifying?
- The subscriber.created payload carries the subscriber ID, not the full record, so the handler fetches the email address, tags and metadata first.
- Will deleting a subscriber send them anything?
- No. Deleting removes the record without an email. Use it for invalid addresses only, and keep risky ones tagged.
Stop bad addresses in Buttondown 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 Buttondown setup will receive.