// sales engagement and cold email
Via APIWoodpecker email verification with pingutil
Woodpecker tracks bounced and invalid prospects and keeps them out of campaigns once it knows, but that knowledge usually comes from a bounce. Verify prospects with pingutil before you add them through the API, so the bounce never happens, and tag catch-all prospects for a slower campaign.
Where it connects: Woodpecker API, POST /rest/v1/add_prospects_campaign (requires the API key add-on)
What goes wrong without it
- Woodpecker only marks a prospect as bounced after the bounce already hit our domain.
- We import from several data vendors and their accuracy varies from list to list.
- Agency clients send us lists and we have no quick way to tell them which rows are bad.
What you can do with Woodpecker and pingutil
Verify before add_prospects_campaign
Run the vendor file through pingutil, then add only valid prospects to the campaign in one request.
Tag catch-all prospects
Woodpecker tags start with # and are space separated, so #catchall on accept_all prospects makes them easy to filter.
Report back to the list owner
Keep the invalid rows with their reason codes and send them back to the vendor or client who supplied the file.
Set it up
- 1
Enable the Woodpecker API key add-on and generate a key under Settings, API Keys. Create a pingutil API key.
- 2
Verify the prospect list with POST https://pingutil.com/v1/verify/batch, 50 addresses per call.
- 3
Build the prospects array from valid results, and from accept_all results with a #catchall tag if you choose to mail them.
- 4
POST to https://api.woodpecker.co/rest/v1/add_prospects_campaign with the x-api-key header and campaign.campaign_id.
- 5
Leave force set to false so prospects with BOUNCED, INVALID or other non-active statuses are not re-added.
// Node 18+. Env: PINGUTIL_KEY, WOODPECKER_API_KEY, CAMPAIGN_ID
type Prospect = { email: string; first_name?: string; last_name?: string; company?: string; tags?: string };
async function verifyBatch(emails: string[]) {
const res = await fetch('https://pingutil.com/v1/verify/batch', {
method: 'POST',
headers: { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' },
body: JSON.stringify({ emails }),
signal: AbortSignal.timeout(120_000),
});
if (!res.ok) throw new Error('pingutil ' + res.status);
return (await res.json()).results as { status: string; reason: string }[];
}
export async function addVerified(list: Prospect[]) {
const keep: Prospect[] = [];
const rejected: { email: string; reason: string }[] = [];
const retry: Prospect[] = [];
for (let i = 0; i < list.length; i += 50) {
const chunk = list.slice(i, i + 50);
let results;
try {
results = await verifyBatch(chunk.map((p) => p.email));
} catch {
retry.push(...chunk); // pingutil unavailable or over limit: keep for later
continue;
}
results.forEach((r, j) => {
if (r.status === 'valid') keep.push(chunk[j]);
else if (r.reason === 'accept_all') keep.push({ ...chunk[j], tags: '#catchall' });
else if (r.status === 'unknown') retry.push(chunk[j]);
else rejected.push({ email: chunk[j].email, reason: r.reason });
});
}
const res = await fetch('https://api.woodpecker.co/rest/v1/add_prospects_campaign', {
method: 'POST',
headers: { 'x-api-key': process.env.WOODPECKER_API_KEY!, 'content-type': 'application/json' },
body: JSON.stringify({
campaign: { campaign_id: Number(process.env.CAMPAIGN_ID) },
force: false,
prospects: keep,
}),
});
if (res.status === 409) throw new Error('Woodpecker rate limit (E_TOO_MANY_REQUESTS)');
return { added: keep.length, rejected, retry };
}What to do with each result
| pingutil result | Action in Woodpecker |
|---|---|
| status: valid | Add to the campaign. |
| status: invalid | Leave out and report the reason to whoever supplied the list. |
| status: risky, reason: accept_all | Add with a #catchall tag, or to a separate campaign, if you mail catch-all at all. |
| status: unknown | Keep aside and verify again later. |
Limits to plan for
- The Woodpecker API needs a paid API key add-on; without it calls fail with E_NO_PERMISSION.
- On the v1 endpoint Woodpecker signals rate limiting with HTTP 409 and E_TOO_MANY_REQUESTS rather than 429.
- pingutil verifies 300 addresses per account per day (3,000 a month), so a large vendor file takes several runs. Those are Free plan limits; Enterprise has custom limits.
Woodpecker documentation
Woodpecker is a trademark of its owner. This integration uses Woodpecker's documented extension points; it is not an official Woodpecker app.
Common questions
- What does force do in add_prospects_campaign?
- With force set to true, Woodpecker adds prospects even when their global status is not active, such as BOUNCED or INVALID. Keep it false so earlier bounces stay excluded.
- Is there a pingutil app in the Woodpecker marketplace?
- No. You connect the two through your own script or an automation tool calling both APIs.
Stop bad addresses in Woodpecker 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 Woodpecker setup will receive.