// email marketing and newsletters
Via APIBraze email verification with pingutil
Braze sends email to whatever address your app passes in, so typos and throwaway signups bounce and drag down engagement metrics across Canvases. A webhook step in your onboarding Canvas sends the user to your endpoint, pingutil verifies the address, and /users/track writes the result to a custom attribute and sets the email subscription state for invalid addresses.
Where it connects: Braze Canvas webhook step (or webhook campaign) plus the REST API /users/track endpoint
What goes wrong without it
- Our onboarding Canvas sends to every new user, and bounces from fake signups show up in every weekly email report.
- Free-tier abuse in our app comes from disposable addresses, and Braze happily messages all of them.
- Different teams build Canvases and nobody checks whether the email is real before adding a send step.
What you can do with Braze and pingutil
Verify in the first Canvas step
Add a webhook step before any email step, then an Audience Paths step that routes on the pingutil_status custom attribute.
Unsubscribe invalid addresses for every team
Setting email_subscribe to unsubscribed through /users/track stops all email Canvases and campaigns, not just the one that ran the check.
Report disposable signups to product
Store pingutil_reason as a custom attribute and build a segment on disposable_domain to size free-tier abuse.
Set it up
- 1
Create a Braze REST API key with users.track permission, find your REST endpoint (it depends on your Braze instance), and create a pingutil API key.
- 2
Deploy the endpoint below.
- 3
In your onboarding Canvas, add a step with a webhook message: POST to your endpoint, Content-Type application/json, an Authorization header with your shared secret, and the JSON body from the snippet.
- 4
Use the Test tab to send a test webhook for a specific user, then check that pingutil_status appears on the profile.
- 5
Add a Delay and an Audience Paths step on pingutil_status before the first email.
// Braze webhook body: { "external_id": "{{${user_id}}}", "email": "{{${email_address}}}" }
// Header: Authorization: Bearer <HOOK_SECRET>
import express from 'express';
const app = express();
app.use(express.json());
async function verify(email: string) {
try {
const res = await fetch('https://pingutil.com/v1/verify', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ email }),
signal: AbortSignal.timeout(30000),
});
return res.ok ? await res.json() : null;
} catch {
return null; // fail open
}
}
app.post('/hooks/braze', async (req, res) => {
if (req.get('authorization') !== 'Bearer ' + process.env.HOOK_SECRET) return res.sendStatus(401);
const { external_id, email } = req.body ?? {};
if (!external_id || !email) return res.sendStatus(200);
// Braze waits up to 120 seconds per webhook, so verifying inline is fine here.
const v = await verify(email);
if (!v) return res.sendStatus(200); // unchecked: leave the user as is
const attributes: Record<string, unknown> = {
external_id,
pingutil_status: v.status,
pingutil_reason: v.reason,
};
if (v.status === 'invalid') attributes.email_subscribe = 'unsubscribed';
const r = await fetch(process.env.BRAZE_REST_ENDPOINT + '/users/track', {
method: 'POST',
headers: { Authorization: 'Bearer ' + process.env.BRAZE_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify({ attributes: [attributes] }),
});
res.sendStatus(r.ok ? 200 : 502); // 5xx makes Braze retry
});
app.listen(3000);What to do with each result
| pingutil result | Action in Braze |
|---|---|
| status: "invalid" | Set email_subscribe to unsubscribed and pingutil_status to invalid; all email sends stop. |
| reason: "disposable_domain" | Invalid path plus a segment on pingutil_reason for abuse reporting. |
| status: "risky" | Keep subscribed; use Audience Paths to send fewer promotional messages. |
| status: "unknown" | Keep subscribed and re-run the webhook step later in the Canvas. |
Limits to plan for
- Braze allows 120 seconds per webhook request and retries 408, 429 and 5xx responses up to five attempts in total, so a slow mail server is not a problem here.
- Liquid in the webhook body needs default values for users without an email; otherwise the request sends an empty address and pingutil returns invalid_input.
- pingutil checks up to 300 addresses per account per day (3,000 a month) and allows 60 requests a minute, which matters if a Canvas enters thousands of users at once. Those are Free plan limits; Enterprise has custom limits.
Braze documentation
- www.braze.com/docs/user_guide/message_building_by_channel/webhooks/creating_a_webhook
- www.braze.com/docs/api/endpoints/user_data/post_user_track
Braze is a trademark of its owner. This integration uses Braze's documented extension points; it is not an official Braze app.
Common questions
- Could I use Connected Content instead of a webhook?
- Connected Content fetches data while a message renders, which runs the check every time you send. A webhook step checks once and stores the result on the profile, which is cheaper and visible to every Canvas.
- Does unsubscribing invalid users affect push or SMS?
- No. email_subscribe only changes the email subscription state. Push and SMS keep their own settings.
Stop bad addresses in Braze 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 Braze setup will receive.