Skip to content

// auth and identity

Via API

Stytch email verification with pingutil

With Stytch's API-first model your backend calls loginOrCreate, and Stytch emails a sign-up link to whatever address you pass it, including typos and temp-mail inboxes. Because your server makes that call, the natural place for pingutil is right before it: verify the address, return a typo suggestion or a refusal, and only then ask Stytch to send.

Where it connects: Your backend, before calling Stytch Magic Links Login or Create (magicLinks.email.loginOrCreate)

What goes wrong without it

  • Users type gmial.com, never receive the magic link and assume our login is broken.
  • Throwaway inboxes receive Stytch links fine, so verification by email does not keep them out.
  • Every link sent to a dead address is a bounce on email we send for our app.

What you can do with Stytch and pingutil

  • Suggest a fix before sending the link

    If /v1/verify returns did_you_mean, answer the form with the suggestion instead of calling Stytch. The user corrects the address on the spot.

  • Refuse disposable and dead addresses

    For status invalid, return a 422 to your login form. Stytch never sends the email, so the bounce never happens.

  • Create risky users as pending

    For status risky, pass create_user_as_pending: true to loginOrCreate so the user stays pending until they actually authenticate.

Set it up

  1. 1

    Create a pingutil API key and set PINGUTIL_KEY next to STYTCH_PROJECT_ID and STYTCH_SECRET.

  2. 2

    Find the route where your backend calls magicLinks.email.loginOrCreate.

  3. 3

    Call /v1/verify first, as in the code below, and return early for invalid addresses or typos.

  4. 4

    Show did_you_mean in your login form when the API returns it.

  5. 5

    Test with a mistyped Gmail address and a disposable address.

Login route (Express + stytch Node SDK)
import express from 'express';
import * as stytch from 'stytch';

const app = express();
app.use(express.json());

const client = new stytch.Client({
  project_id: process.env.STYTCH_PROJECT_ID!,
  secret: process.env.STYTCH_SECRET!,
});

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(5000), // the user is waiting
    });
    return res.ok ? await res.json() : null;
  } catch {
    return null; // fail open
  }
}

app.post('/auth/email', async (req, res) => {
  const email = String(req.body.email ?? '').trim();
  const result = await verify(email);

  if (result?.did_you_mean) {
    return res.status(422).json({ error: 'typo', suggestion: result.did_you_mean });
  }
  if (result?.status === 'invalid') {
    return res.status(422).json({ error: 'undeliverable', reason: result.reason });
  }

  await client.magicLinks.email.loginOrCreate({
    email,
    create_user_as_pending: result?.status === 'risky',
  });
  res.json({ sent: true });
});

app.listen(3000);

What to do with each result

pingutil resultAction in Stytch
did_you_mean is setReturn the suggestion to the form; do not call Stytch yet
status: "invalid"Return 422; no magic link is sent
status: "risky"Call loginOrCreate with create_user_as_pending: true
status: "valid" or "unknown"Call loginOrCreate as usual
Timeout, 429 or 5xxCall loginOrCreate as usual (fail open)

Limits to plan for

  • Stytch's Login or Create endpoint is called for returning users too. pingutil caches definitive results for 30 days, but every call still counts toward the 300 verified addresses a day (3,000 a month); skip the check for emails you already know. Those are Free plan limits; Enterprise has custom limits.
  • A first-seen address on a slow mail server can take several seconds. The 5-second timeout falls back to sending the link.
  • Catch-all domains return risky (accept_all). The mailbox may or may not exist; pingutil does not round that up to valid.

Stytch documentation

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

Common questions

Does Stytch have a pre-signup hook I could use instead?
Stytch's Login or Create docs do not describe one. Since your backend already makes the Stytch call, checking just before it is the simplest blocking point.
Should I use /v1/lookup instead to save time?
Use /v1/lookup with skip_enrichment for a millisecond disposable check. /v1/verify is slower but it is the one that catches typos and dead mailboxes, which is what stops magic links bouncing.

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