// auth and identity
Via APIZITADEL email verification with pingutil
ZITADEL creates a human user for any well-formed email the User Service receives, so temp-mail and scripted sign-ups land in your instance. An Actions v2 request execution on CreateUser (or AddHumanUser) sends the request to your Call target first; your target asks pingutil and either returns the request unchanged or forwards a 400 with a message.
Where it connects: ZITADEL Actions v2: a Call target (restCall, interruptOnError) on a request execution for UserService CreateUser or AddHumanUser
What goes wrong without it
- Our ZITADEL instance has users at temp-mail domains that never verified anything and still count against our user list.
- We need the check in front of user creation, not in a cleanup script that runs after the fact.
- Actions v1 scripts were awkward for calling outside APIs, and we are moving to v2 anyway.
What you can do with ZITADEL and pingutil
Block disposable addresses before the user is created
The Call target reads request.human.email.email, calls fast-mode /v1/lookup and responds with forwardedStatusCode 400 and a forwardedErrorMessage when verdict.is_spam is true. ZITADEL returns that error instead of creating the user.
Stop machine-generated local parts
verdict.reason randomized_local_part flags strings like q8zj3kx0w@ on any domain, which catches scripted sign-ups that a domain list misses.
Check mailboxes in the background
For a mailbox check without slowing sign-up, add an event execution with a Webhook or Async target and call /v1/verify from there, then flag or deactivate users whose status is invalid.
Set it up
- 1
Deploy the endpoint below on HTTPS with PINGUTIL_KEY set.
- 2
Create a target with POST /v2/actions/targets: a name, your endpoint, restCall with interruptOnError true, and a timeout such as 5s. Keep the signing key from the response to verify the ZITADEL-Signature header.
- 3
Set an execution with PUT /v2/actions/executions whose condition.request.method is /zitadel.user.v2.UserService/CreateUser and whose targets list your target ID; add a second one for /zitadel.user.v2.UserService/AddHumanUser if your registration UI uses it.
- 4
Create a user with a disposable address through the API or your registration UI and confirm the 400 and message come back.
- 5
Check that the request execution fires for the path your users actually register through before you rely on it.
import express from 'express';
const app = express();
app.use(express.json());
// ZITADEL posts { fullMethod, instanceID, orgID, projectID, userID, request }.
// A Call target on a request execution returns the request body to continue.
app.post('/zitadel/user-create', async (req, res) => {
// Verify the ZITADEL-Signature header with your target's signing key here.
const request = req.body?.request ?? {};
const email: string | undefined =
request.human?.email?.email ?? // CreateUser
request.email?.email; // AddHumanUser
if (!email) return res.json(request);
try {
const r = await fetch('https://pingutil.com/v1/lookup', {
method: 'POST',
headers: {
authorization: 'Bearer ' + process.env.PINGUTIL_KEY,
'content-type': 'application/json',
},
body: JSON.stringify({ input: email, skip_enrichment: true }),
signal: AbortSignal.timeout(2000), // stay under the target timeout
});
if (!r.ok) return res.json(request); // 429 or 5xx: fail open
const data = await r.json();
if (data.verdict?.is_spam) {
// Status 200 with forwarded fields: ZITADEL returns this 4xx to the caller.
return res.json({
forwardedStatusCode: 400,
forwardedErrorMessage: 'Please register with a permanent email address.',
});
}
return res.json(request); // unchanged request, user creation continues
} catch {
return res.json(request);
}
});
app.listen(3000);What to do with each result
| pingutil result | Action in ZITADEL |
|---|---|
| verdict.is_spam: true, reason "disposable_domain" | Respond 200 with forwardedStatusCode 400 and forwardedErrorMessage |
| verdict.is_spam: true, reason "randomized_local_part" | Same forwarded 400; no user is created |
| verdict.low_trust: true | Return the request unchanged and log the reason, or add user metadata to the returned request |
| category: "free" or "company" | Return the request unchanged |
| Timeout, 429 or 5xx from pingutil | Return the request unchanged (fail open) |
Limits to plan for
- With interruptOnError, ZITADEL treats any status of 400 or more from your target as a failed execution, so return 200 with the forwarded fields to block and 200 with the request to allow. A crash in your endpoint blocks user creation.
- Request executions only run for API calls that match the condition. Users created through another method, or through a login UI that does not call these User Service methods, are not checked.
- Each user creation counts toward 2,000 lookups a day (30,000 a month) per account. Those are Free plan limits; Enterprise has custom limits.
ZITADEL documentation
- zitadel.com/docs/guides/integrate/actions/usage
- zitadel.com/docs/guides/integrate/actions/testing-request-manipulation
- zitadel.com/docs/concepts/features/actions_v2
ZITADEL is a trademark of its owner. This integration uses ZITADEL's documented extension points; it is not an official ZITADEL app.
Common questions
- Can I use ZITADEL Actions v1 instead?
- Actions v1 has its own flows and triggers and a JavaScript runtime. ZITADEL documents a migration path to v2, and v2 targets are plain HTTP endpoints, which makes calling pingutil simpler, so we show v2.
- Why not run a full mailbox check in the Call target?
- The user waits for the target to answer, and a mailbox check on a slow server can take several seconds. Use fast-mode lookup in the request execution and run /v1/verify from an asynchronous event execution if you want mailbox status.
Stop bad addresses in ZITADEL 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 ZITADEL setup will receive.