// auth and identity
Via APIOry email verification with pingutil
Ory creates an identity for any address the registration form accepts, and a temp-mail inbox can complete email verification. A web_hook on the registration after step with response.parse set to true runs before the identity is created; your endpoint asks pingutil and returns a 400 with a message on the email trait, which Ory shows on the form.
Where it connects: Ory Kratos / Ory Network registration "after" web_hook action with response.parse: true (flow-interrupting webhook)
What goes wrong without it
- Our Ory project keeps gaining identities at temp-mail domains that sign up, verify and never come back.
- We want the rejection to show up on the email field of the registration form, not as a generic error.
- Jsonnet, webhook auth and response parsing are a lot of moving parts for one email check.
What you can do with Ory and pingutil
Reject disposable addresses on the registration form
When pingutil returns status invalid with reason disposable_domain, the webhook answers 400 with a message whose instance_ptr is #/traits/email. Ory interrupts the flow and shows the text under the email field.
Return typo suggestions
did_you_mean holds the likely address for domains that look like a typo of a major provider. Include it in the message text so the user can correct the address and submit again.
Check mailboxes without blocking
Add a second web_hook with response.ignore: true after registration to verify the mailbox in the background and flag invalid identities through the Ory API.
Set it up
- 1
Deploy the endpoint below on HTTPS with PINGUTIL_KEY and ORY_HOOK_KEY set.
- 2
In the Ory Console, go to Authentication > Actions & Webhooks and create a new action for the registration flow, timing after, for the sign-up methods you use (for example password).
- 3
Set the URL and POST method, and use a Jsonnet body such as: function(ctx) { email: ctx.identity.traits.email } (adjust the trait name to your identity schema).
- 4
Turn on response parsing so the webhook can interrupt the flow, and set API key auth with name Authorization and your ORY_HOOK_KEY value in the header.
- 5
Register with a disposable address and confirm the error appears under the email field.
import express from 'express';
const app = express();
app.use(express.json());
const reject = (text: string) => ({
messages: [{
instance_ptr: '#/traits/email',
messages: [{ id: 4000001, text, type: 'error' }],
}],
});
app.post('/ory/registration', async (req, res) => {
if (req.get('authorization') !== process.env.ORY_HOOK_KEY) return res.status(401).end();
// Body comes from the Jsonnet template: function(ctx) { email: ctx.identity.traits.email }
const email: string | undefined = req.body?.email;
if (!email) return res.json({});
try {
const r = 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), // well inside Ory's 30 s per attempt
});
if (!r.ok) return res.json({}); // 429 or 5xx: fail open
const v = await r.json();
if (v.status === 'invalid') {
const hint = v.did_you_mean ? ' Did you mean ' + v.did_you_mean + '?' : '';
return res.status(400).json(reject('Please use a real, permanent email address.' + hint));
}
return res.json({}); // 200 with a JSON body: registration continues
} catch {
return res.json({});
}
});
app.listen(3000);What to do with each result
| pingutil result | Action in Ory |
|---|---|
| status: "invalid", reason "disposable_domain" | Respond 400 with a message on #/traits/email; the identity is not created |
| status: "invalid" with did_you_mean set | Respond 400 and put the suggestion in the message text |
| status: "risky" (accept_all, role_based, randomized_local_part) | Respond 200; optionally store the reason in metadata through a separate call |
| status: "valid" or "unknown" | Respond 200 with a JSON body |
| Timeout, 429 or 5xx from pingutil | Respond 200 (fail open) |
Limits to plan for
- Ory times out each webhook attempt after 30 seconds and retries up to three times. A user waits while your endpoint runs, so keep the pingutil timeout short, or switch to POST /v1/lookup with skip_enrichment: true for a millisecond disposable check.
- Ory notes that an empty or malformed HTTP 200 still fails when response parsing is on, so always return a JSON object. The hook only runs for the methods you attach it to; identities created through the admin API skip it.
- Each registration counts toward 300 verified addresses a day (3,000 a month) per account. Those are Free plan limits; Enterprise has custom limits.
Ory documentation
- www.ory.com/docs/guides/integrate-with-ory-cloud-through-webhooks
- www.ory.com/docs/kratos/hooks/configure-hooks
Ory is a trademark of its owner. This integration uses Ory's documented extension points; it is not an official Ory app.
Common questions
- Can a before registration webhook block sign-ups instead?
- A before hook runs before the user fills in the form, so there is no identity or email to check yet. Ory recommends after hooks with response parsing for flow-interrupting checks.
- Does this work on self-hosted Kratos?
- Yes. The web_hook action is a Kratos feature; on self-hosted Kratos you configure it in the registration after hooks of your Kratos config instead of the Ory Console.
Stop bad addresses in Ory 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 Ory setup will receive.