Skip to content

// support, community and events

Via API

Crisp email verification with pingutil

Crisp asks visitors for an email so the team can answer after they leave, and when that address is fake or mistyped the follow-up never arrives. A website hook on session:set_email sends each address to your endpoint as soon as the visitor enters it, pingutil verifies it, and your code adds a segment to the conversation so operators see the problem while the visitor may still be in the chat.

Where it connects: Crisp website hook on the session:set_email event, then the REST API v1 Update Conversation Metas route (segments)

What goes wrong without it

  • The visitor left before we answered, and the email they gave us was asdf@asdf.com.
  • Our chatbot collects emails all day and half the leads it creates are throwaways.
  • Operators cannot tell from the inbox whether a follow-up email will reach anyone.

What you can do with Crisp and pingutil

  • Ask again while the visitor is still there

    An invalid result or a did_you_mean suggestion adds an email-invalid segment within seconds, so the operator can ask the visitor to retype the address before they close the tab.

  • Segment throwaway leads

    Disposable addresses get an email-disposable segment, which you can exclude from campaigns and lead counts in Crisp.

  • Separate business visitors

    Run a fast /v1/lookup with skip_enrichment: true and add a work-email segment when category is company, so sales can pick those conversations first.

Set it up

  1. 1

    Create a pingutil API key (PINGUTIL_KEY). Create a Crisp REST API token in the Crisp Marketplace (plugin tier) with access to conversation sessions, and set CRISP_IDENTIFIER and CRISP_KEY.

  2. 2

    In Crisp, go to Settings, Website Settings, Advanced configuration, Web Hooks, and add your endpoint URL with a secret query string, for example https://example.com/webhooks/crisp?token=YOUR_SECRET.

  3. 3

    Select the session:set_email event for the hook.

  4. 4

    Deploy the handler below. It checks the token, answers 200, verifies the address and adds a segment using the Update Conversation Metas route.

  5. 5

    Open the chatbox on your site, enter a disposable address and confirm the segment appears on the conversation.

Express handler for Crisp session:set_email
import express from 'express';

const app = express();
app.use(express.json());
const CRISP = 'https://api.crisp.chat/v1';
const headers = {
  authorization: 'Basic ' + Buffer.from(process.env.CRISP_IDENTIFIER + ':' + process.env.CRISP_KEY).toString('base64'),
  'X-Crisp-Tier': 'plugin',
  '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/crisp', async (req, res) => {
  if (req.query.token !== process.env.CRISP_HOOK_TOKEN) return res.sendStatus(401); // website hooks are not signed
  res.sendStatus(200);

  const { event, data } = req.body;
  if (event !== 'session:set_email' || !data.email) return;

  const v = await verify(data.email);
  if (!v || v.status === 'valid' || v.status === 'unknown') return;
  const segment = v.reason === 'disposable_domain' ? 'email-disposable' : v.status === 'invalid' ? 'email-invalid' : 'email-risky';

  const metaUrl = CRISP + '/website/' + data.website_id + '/conversation/' + data.session_id + '/meta';
  const current = await fetch(metaUrl, { headers }).then((r) => r.json());
  const segments: string[] = current.data?.segments ?? [];
  await fetch(metaUrl, {
    method: 'PATCH',
    headers,
    body: JSON.stringify({ segments: [...segments, segment] }),
  });
});

app.listen(3000);

What to do with each result

pingutil resultAction in Crisp
status: 'invalid' or did_you_mean setAdd the email-invalid segment so the operator asks the visitor to retype the address.
reason: 'disposable_domain'Add the email-disposable segment and exclude it from campaigns and lead counts.
status: 'risky' (accept_all, role_based)Add the email-risky segment; answer in the chat rather than relying on email.
status: 'unknown'No segment. The mail server did not answer.
category: 'company' from /v1/lookupAdd a work-email segment so sales operators can prioritize the conversation.

Limits to plan for

  • Crisp website hooks are not signed and not retried on failure, so protect the URL with a secret and expect to miss an event now and then. Plugin hooks are signed and retried if you need stronger guarantees.
  • Webhooks and REST API access may require a paid Crisp plan; check your plan before building.
  • Verification can take several seconds on slow mail servers, so the segment may appear a little after the visitor types the address.

Crisp documentation

Crisp is a trademark of its owner. This integration uses Crisp's documented extension points; it is not an official Crisp app.

Common questions

Can I stop the chatbox from accepting a bad email?
Not through the hook, which fires after the email is saved. If you collect the email in your own UI before calling the Crisp chatbox SDK, you can call pingutil first and only pass on addresses that pass.
Why not use the plugin hook instead?
Plugin hooks are signed and retried, which is better for production. Website hooks are quicker to set up for a single site; both deliver session:set_email.

Stop bad addresses in Crisp 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 Crisp setup will receive.