Bounce feedback loop, scoped to your key.
Forward your ESP bounce webhook to vrfymail once. From then on, every /v1/check from your key checks the address against YOUR bounce history before scoring. Scoped to your api_key — your signal never leaks to other customers.
POST /v1/report-bounce
Tell the verifier an address bounced. The next /v1/check on the same address (from your key) returns previously_bounced. Reasons: hard_bounce, soft_bounce, spam_complaint, unsubscribe.
curl https://vrfymail.com/v1/report-bounce \
-H "Authorization: Bearer vk_live_..." \
-d '{
"email": "bounced@example.com",
"reason": "hard_bounce",
"occurred_at": "2026-05-13T10:00:00Z"
}'{
"result": "undeliverable",
"reason": "previously_bounced",
"reason_message": "This address bounced from your previous send. Don't retry.",
"account_history": {
"matched": true,
"previous_reason": "hard_bounce",
"occurred_at": "2026-05-13T10:00:00Z"
}
}Forward your existing webhook — one URL.
Every major ESP posts bounce events as JSON webhooks. Point the webhook URL at vrfymail; the api_key is embedded so no shared bearer token leaks into your ESP config.
// Point your Resend webhook at this URL.
// The key is in the path so no shared bearer token is needed.
https://vrfymail.com/v1/report-bounce/from-resend?key=ak_live_...
// Resend sends bounce events as POST JSON; the URL embeds the
// api_key_id, vrfymail verifies + records, no further setup.Your bounces don't become someone else's blocklist.
Most "shared blocklist" verifiers operate on the assumption that one customer's bounce is everyone's signal. That model has the wrong incentives — your competitor's lazy list hygiene becomes your signup-form noise.
vrfymail's overlay is keyed on your api_key_id. user@example.com bouncing on your list flags it for your future checks only. A different customer asking about the same address gets a fresh verdict from the underlying signals — no overlay applied.
The one exception: customer-consensus promotion. If ≥3 distinct customers report a hard-bounce or spam-complaint on the same domain within 30 days, the domain promotes to a global spam_trap=1 flag — but per-address signal stays scoped. Free-mail providers excluded from consensus promotion.
- 1. ESP posts bounce event to
/v1/report-bounce. - 2. vrfymail records
(api_key_id, email, reason). Cache for that customer/email cleared. - 3. Next
/v1/checkfrom your key on that email returnspreviously_bounced. - 4. Other customers' checks on the same email get fresh verdicts. Signal isolated.
Other signals in the same call
The bounce overlay runs alongside disposable detection (238K+ domains), spam-trap detection, and B2C strict-mode flags. One call returns every signal, your overlay applied on top — 50ms p50.
Bounce feedback loop, answered
- What's a per-customer overlay vs a shared blocklist?
- A shared blocklist promotes every bounce to a global flag — your competitor's bad addresses become your bad addresses, and vice versa. A per-customer overlay keeps the signal scoped to your api_key. If user@example.com bounced on YOUR list, future calls from your key return previously_bounced; other customers' calls on the same address get a fresh verdict. Your bounce data doesn't leak.
- How is this different from just blocking bounced addresses in my ESP?
- Your ESP blocks the address from being sent to again — but the address can still re-signup on your form, and your form won't know. The overlay closes that loop: bounce → vrfymail records it → future verifies of the same address from your key return undeliverable before the signup completes. ESPs handle send-side; vrfymail handles signup-side. Both ends of the same loop.
- Which ESPs work with this?
- Resend, Postmark, SendGrid, Mailchimp, Mailgun, Loops, customer.io — any ESP that posts bounce/complaint webhooks as JSON. Point the webhook URL at vrfymail's /v1/report-bounce endpoint (the URL embeds your api_key_id so no shared bearer needed). Hard bounces, soft bounces, spam complaints, unsubscribes all forward into the overlay.
- What's the per-key budget on bounce reports?
- 1,000 reports/day default. Most signup forms see 0.5-2% bounce rates so this covers up to ~50,000-200,000 daily sends comfortably. If you're running a high-volume newsletter list, contact us for a raised budget. The endpoint rate-limits politely (HTTP 429 with Retry-After) rather than dropping events.
- When a customer reports a hard bounce on a domain — does that flag the whole domain?
- No, just the specific address — for that customer. The exception: customer-consensus promotion. If ≥3 distinct customers report hard_bounce or spam_complaint on the same domain within 30 days, the domain promotes to a global spam_trap=1 flag (free-mail providers like Gmail are excluded). Single-customer signal stays scoped; multi-customer signal goes global.
One webhook. Your signal stays yours.
5,000 verifies/month free, no card. 1,000 bounce reports/day on every plan. See pricing.
Get my API key