// support, community and events
Via APIHelp Scout email verification with pingutil
Help Scout threads live and die by email, so a customer who typed their address wrong on Beacon or a contact form never sees your answer. A webhook on convo.created hands each new conversation to your endpoint, pingutil verifies the customer address, and your code tags the conversation and leaves a note before anyone replies.
Where it connects: Help Scout webhook on the convo.created event, then the Inbox API 2.0 (conversation tags, notes)
What goes wrong without it
- Beacon messages come in from addresses like sarah@gmal.com and our reply goes nowhere.
- We answer spam from temp-mail addresses because they look like real questions at first glance.
- Agents cannot tell from the conversation that the customer will never receive the reply.
What you can do with Help Scout and pingutil
Note typos on the conversation
When pingutil suggests a correction through did_you_mean, the receiver adds a note with the suggested address so the agent can update the customer before replying.
Tag unreachable customers
Invalid addresses get an email-invalid tag. A Help Scout workflow can filter on the tag to move those conversations to a follow-up folder.
Keep throwaways out of reports
Disposable-domain conversations get an email-disposable tag so they are easy to exclude from response-time and volume reports.
Set it up
- 1
Create a pingutil API key and store it as PINGUTIL_KEY, plus a Help Scout OAuth access token for the Inbox API as HELPSCOUT_TOKEN.
- 2
In Help Scout, open Manage, Apps, Webhooks, enter your callback URL and a secret key, and select the Conversation Created event (convo.created).
- 3
Deploy the handler below. It checks the X-HelpScout-Signature header (base64 HMAC-SHA1 of the raw body), answers 200, then verifies the customer email.
- 4
The receiver sets tags with the Update Conversation Tags endpoint and posts a note with the Create Note endpoint.
- 5
Send a test message from Beacon with a mistyped address and check the conversation for the tag and note.
import express from 'express';
import crypto from 'node:crypto';
const app = express();
const HS = 'https://api.helpscout.net/v2';
const headers = { authorization: 'Bearer ' + process.env.HELPSCOUT_TOKEN, 'content-type': 'application/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; // fail open on 429 / 5xx
} catch {
return null;
}
}
app.post('/webhooks/helpscout', express.raw({ type: 'application/json' }), async (req, res) => {
const sig = crypto.createHmac('sha1', process.env.HELPSCOUT_WEBHOOK_SECRET!).update(req.body).digest('base64');
if (sig !== req.get('X-HelpScout-Signature')) return res.sendStatus(401);
res.sendStatus(200);
if (req.get('X-HelpScout-Event') !== 'convo.created') return;
const convo = JSON.parse(req.body.toString('utf8'));
const email = convo.primaryCustomer?.email;
if (!email) return;
const v = await verify(email);
if (!v || v.status === 'valid' || v.status === 'unknown') return;
const tag = v.reason === 'disposable_domain' ? 'email-disposable' : v.status === 'invalid' ? 'email-invalid' : 'email-risky';
const existing = (convo.tags ?? []).map((t: { tag: string }) => t.tag);
await fetch(HS + '/conversations/' + convo.id + '/tags', {
method: 'PUT', // replaces the tag list, so keep the existing tags
headers,
body: JSON.stringify({ tags: [...existing, tag] }),
});
let text = 'pingutil: customer email is ' + v.status + ' (' + v.reason + ').';
if (v.did_you_mean) text += ' Suggested address: ' + v.did_you_mean;
await fetch(HS + '/conversations/' + convo.id + '/notes', { method: 'POST', headers, body: JSON.stringify({ text }) });
});
app.listen(3000);What to do with each result
| pingutil result | Action in Help Scout |
|---|---|
| did_you_mean is not null | Add a note with the suggested address; the agent updates the customer profile before replying. |
| status: 'invalid' | Tag email-invalid and let a workflow move the conversation to a follow-up folder. |
| reason: 'disposable_domain' | Tag email-disposable and exclude it from reports, or close it as spam after a glance. |
| status: 'risky' (accept_all, mailbox_full) | Tag email-risky; reply as usual but watch for a bounce. |
| status: 'unknown' | Leave the conversation alone. |
Limits to plan for
- Help Scout retries a failed webhook up to 10 times and deactivates the webhook after ten or more discarded events, so the receiver must answer 2xx reliably.
- The Update Conversation Tags endpoint replaces the full tag list; merge existing tags as the snippet does or you will remove tags set by workflows.
- Verification counts toward the 300 addresses per day (3,000 a month) account default, and catch-all domains can only ever be reported as risky. Those are Free plan limits; Enterprise has custom limits.
Help Scout documentation
Help Scout is a trademark of its owner. This integration uses Help Scout's documented extension points; it is not an official Help Scout app.
Common questions
- Why convo.created and not customer.created?
- customer.created fires for every customer added anywhere in the account, including imports, and cannot be limited to one inbox. convo.created ties the check to someone who is actually waiting for a reply.
- Does the note show up for the customer?
- No. Notes in Help Scout are internal and only visible to your team.
Stop bad addresses in Help Scout 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 Help Scout setup will receive.