// crm
Via APIfolk email verification with pingutil
folk makes it easy to pull contacts in from LinkedIn, Gmail and imports, and just as easy to end up emailing addresses that no longer exist. A webhook on person.created sends new people to a small service that verifies the primary email with pingutil and writes the status and email category to custom fields in the person's group.
Where it connects: folk webhook subscribed to person.created, with a service that writes group custom field values via PATCH /v1/people/{personId}
What goes wrong without it
- We imported a list of prospects into folk and our first mail merge bounced all over the place.
- Contacts added from LinkedIn come with guessed emails we never checked.
- Our folk group mixes founders' work emails with personal addresses, and we cannot filter by it.
What you can do with folk and pingutil
Verify before a mail merge
Write `status` to an "Email status" field in the group, and filter the group view to exclude `invalid` before sending a campaign from folk.
Split work and personal emails
Write `category` from `/v1/lookup` to an "Email type" field, so outreach to companies and to personal contacts can be handled separately.
Catch guessed addresses
Addresses guessed from a name and a domain often come back `invalid` or `risky` with `accept_all`; treat those as unconfirmed.
Set it up
- 1
In the group you prospect from, add text custom fields named "Email status" and "Email type".
- 2
Create an API key in folk's workspace API settings and note the group id.
- 3
Deploy the service below with `FOLK_KEY`, `FOLK_GROUP_ID`, `HOOK_PATH_TOKEN` and `PINGUTIL_KEY`.
- 4
Create the webhook with `POST https://api.folk.app/v1/webhooks`, body `{"name": "pingutil", "targetUrl": "https://your-host/folk/<token>", "subscribedEvents": [{"eventType": "person.created"}]}`, and store the signing secret shown once in the response.
- 5
Filter the group view on Email status before your next campaign.
// node >= 18, npm install express
import express from 'express';
const fk = { authorization: 'Bearer ' + process.env.FOLK_KEY, 'content-type': 'application/json' };
const pu = { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' };
const GROUP = process.env.FOLK_GROUP_ID;
const app = express();
app.use(express.json());
// For production, also verify the webhook-signature header with your signing secret (see folk's docs).
app.post('/folk/:token', (req, res) => {
if (req.params.token !== process.env.HOOK_PATH_TOKEN) return res.sendStatus(401);
res.sendStatus(200);
if (req.body?.type === 'person.created' && req.body.data?.url) {
handlePerson(req.body.data.url).catch((e) => console.error(e));
}
});
async function pingutil(path, body) {
const r = await fetch('https://pingutil.com' + path, {
method: 'POST', headers: pu, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000),
});
return r.ok ? r.json() : null; // fail open on 429 or errors
}
async function handlePerson(url) {
const person = (await fetch(url, { headers: fk }).then((r) => r.json())).data;
const email = person?.emails?.[0];
const groups = person?.groups ?? [];
if (!email || !groups.some((g) => g.id === GROUP)) return; // only people in the prospecting group
const [v, l] = await Promise.all([pingutil('/v1/verify', { email }), pingutil('/v1/lookup', { input: email, skip_enrichment: true })]);
const fields = {};
if (v) fields['Email status'] = v.status + ' (' + v.reason + ')';
if (l) fields['Email type'] = l.category;
if (!Object.keys(fields).length) return;
await fetch('https://api.folk.app/v1/people/' + person.id, {
method: 'PATCH', headers: fk,
body: JSON.stringify({ groups: groups.map((g) => ({ id: g.id })), customFieldValues: { [GROUP]: fields } }),
});
}
app.listen(process.env.PORT ?? 3000);What to do with each result
| pingutil result | Action in folk |
|---|---|
| `status: "valid"` | Include in mail merges and campaigns. |
| `status: "invalid"` | Exclude from the campaign view and look for a current address. |
| `status: "risky"`, `reason: "accept_all"` | Send in small batches; the domain accepts any address. |
| `category: "free"` | Mark as a personal address in the Email type field. |
| `verdict.reason: "role_based"` | Shared inbox; find a named person at the company. |
Limits to plan for
- folk webhook payloads carry only the person id and API url, so the service reads the person before verifying.
- Custom field values are set per group, and the group must be included in the update; the service sends the person's current groups back so membership does not change.
- pingutil allows 300 verified addresses a day (3,000 a month) per account; a big import is better verified as a CSV export in batches of 50. Those are Free plan limits; Enterprise has custom limits.
folk documentation
- developer.folk.app/webhooks/events-and-payloads
- developer.folk.app/webhooks/create-webhooks
- developer.folk.app/api-reference/people/update-a-person
folk is a trademark of its owner. This integration uses folk's documented extension points; it is not an official folk app.
Common questions
- Does folk already verify emails?
- folk has its own enrichment features; this setup adds a mailbox check and an email-type label from pingutil to fields you control. Check folk's documentation for what its enrichment covers.
- What if a person is added to the group later?
- person.created fires once. Subscribe to person.groups_updated as well if people are often moved into the prospecting group after creation.
Stop bad addresses in folk 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 folk setup will receive.