// crm
Via APICopper email verification with pingutil
Copper adds people from Gmail threads, forms and imports, which means typos, old addresses and personal accounts end up in the CRM next to real buyers. A webhook subscription on new people sends their ids to a small service that verifies each address with pingutil and writes the status and email category to Copper custom fields.
Where it connects: Copper Developer API webhook subscription (type person, event new) to a service that updates person custom fields
What goes wrong without it
- Copper creates contacts from every Gmail thread, and some of those addresses stopped working years ago.
- We cannot tell at a glance which people are at a company and which used their personal email.
- Our follow-up emails from Copper bounce and nobody updates the record.
What you can do with Copper and pingutil
Verify new people automatically
Write `status` to a dropdown or text custom field so saved filters can exclude `invalid` addresses from follow-ups.
Label personal vs work addresses
Write `category` from `/v1/lookup` to the person, so `company` contacts are prioritized and `free` or `isp` ones are reviewed.
Catch typos from manual entry
When `did_you_mean` is set, write it to a "Suggested email" field for the owner to confirm.
Set it up
- 1
Create person custom fields "Email status", "Email category" and "Suggested email" and note each `custom_field_definition_id` from the custom field definitions API.
- 2
Deploy the service below with `COPPER_TOKEN`, `COPPER_EMAIL`, `PINGUTIL_KEY`, `HOOK_SECRET` and the field ids.
- 3
Create the subscription with `POST https://api.copper.com/developer_api/v1/webhooks`, body `{"target": "https://your-host/copper", "type": "person", "event": "new", "headers": {"X-Hook-Secret": "<your secret>"}}`.
- 4
Copper sends the custom header with every notification; the service rejects requests without it.
- 5
Run a nightly job for people with an empty Email status, because Copper does not retry failed notifications.
// node >= 18, npm install express
import express from 'express';
const CU = 'https://api.copper.com/developer_api/v1';
const cu = {
'X-PW-AccessToken': process.env.COPPER_TOKEN,
'X-PW-Application': 'developer_api',
'X-PW-UserEmail': process.env.COPPER_EMAIL,
'Content-Type': 'application/json',
};
const pu = { authorization: 'Bearer ' + process.env.PINGUTIL_KEY, 'content-type': 'application/json' };
const app = express();
app.use(express.json());
app.post('/copper', (req, res) => {
if (req.headers['x-hook-secret'] !== process.env.HOOK_SECRET) return res.sendStatus(401);
res.sendStatus(200);
for (const id of req.body?.ids ?? []) handlePerson(id).catch((e) => console.error(id, 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: leave fields empty for the nightly job
}
async function handlePerson(id) {
const person = await fetch(CU + '/people/' + id, { headers: cu }).then((r) => r.json());
const email = person.emails?.[0]?.email;
if (!email) return;
const [v, l] = await Promise.all([pingutil('/v1/verify', { email }), pingutil('/v1/lookup', { input: email, skip_enrichment: true })]);
const fields = [];
if (v) fields.push({ custom_field_definition_id: Number(process.env.CF_STATUS), value: v.status + ' (' + v.reason + ')' });
if (v?.did_you_mean && v.did_you_mean !== v.email) fields.push({ custom_field_definition_id: Number(process.env.CF_SUGGESTED), value: v.did_you_mean });
if (l) fields.push({ custom_field_definition_id: Number(process.env.CF_CATEGORY), value: l.category });
if (!fields.length) return;
await fetch(CU + '/people/' + id, { method: 'PUT', headers: cu, body: JSON.stringify({ custom_fields: fields }) });
}
app.listen(process.env.PORT ?? 3000);What to do with each result
| pingutil result | Action in Copper |
|---|---|
| `status: "invalid"` | Exclude from follow-up filters and ask the owner for a current address. |
| `status: "risky"`, `reason: "role_based"` | Shared inbox; look for a named person at the company. |
| `did_you_mean` set | Fill Suggested email for the owner to confirm; do not overwrite automatically. |
| `category: "company"` | Prioritize in sales views. |
| `category: "free"` or `"isp"` | Review before adding to a pipeline. |
Limits to plan for
- Copper sends each notification at most once and does not retry, whatever your endpoint returns, so a nightly sweep of unverified people is needed.
- Copper allows 100 active webhook subscriptions per account and up to 30 record ids per notification.
- The snippet uses `skip_enrichment: true` for a fast category check; drop it if you also want `company.*` fields, which can take a few seconds for a first-seen domain.
Copper documentation
- developer.copper.com/webhooks/overview.html
- developer.copper.com/webhooks/create-new-subscription.html
Copper is a trademark of its owner. This integration uses Copper's documented extension points; it is not an official Copper app.
Common questions
- Can I set this up in Copper's UI?
- Copper's Developer API webhooks are created through the API, which is what this setup uses. The service that verifies and writes back runs on your own host or a serverless function.
- Will updating the person trigger the webhook again?
- No. The subscription listens to new people only, and the service updates existing ones.
Stop bad addresses in Copper 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 Copper setup will receive.