Skip to content

// sales engagement and cold email

Via API

Woodpecker 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. 1

    Enable the Woodpecker API key add-on and generate a key under Settings, API Keys. Create a pingutil API key.

  2. 2

    Verify the prospect list with POST https://pingutil.com/v1/verify/batch, 50 addresses per call.

  3. 3

    Build the prospects array from valid results, and from accept_all results with a #catchall tag if you choose to mail them.

  4. 4

    POST to https://api.woodpecker.co/rest/v1/add_prospects_campaign with the x-api-key header and campaign.campaign_id.

  5. 5

    Leave force set to false so prospects with BOUNCED, INVALID or other non-active statuses are not re-added.

Verify a list and add the keepers to a Woodpecker campaign
// 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 resultAction in Woodpecker
status: validAdd to the campaign.
status: invalidLeave out and report the reason to whoever supplied the list.
status: risky, reason: accept_allAdd with a #catchall tag, or to a separate campaign, if you mail catch-all at all.
status: unknownKeep 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.