Skip to content

chore: add email validation rules #2497

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pi1814 merged 2 commits into from
Apr 3, 2026
+33 −0
Merged

chore: add email validation rules #2497

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
52ad2a5
chore: add email validation rules
pi1814 Apr 2, 2026
a52df97
chore: dummy commit
pi1814 Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/kratos/manage-identities/15_customize-identity-schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -509,6 +509,39 @@ Note that the `format` field of the identity schema will perform validation of t
is validated using the [JSON Schema](https://json-schema.org/understanding-json-schema/reference/string.html#email-addresses) rule
set.

##### Email validation rules

When you use `"format": "email"`, Ory validates the email address against
[RFC 5322, section 3.4.1](https://datatracker.ietf.org/doc/html/rfc5322#section-3.4.1) and the domain part against
[RFC 1034, section 3.1](https://datatracker.ietf.org/doc/html/rfc1034#section-3.1) and
[RFC 1123, section 2.1](https://datatracker.ietf.org/doc/html/rfc1123#section-2.1).

The following rules are enforced:

- The total address length must not exceed 254 characters.
- The address must contain an `@` separator.
- The local part (before `@`) must not exceed 64 characters.
- The domain part (after `@`) must be a valid hostname:
- Only ASCII letters (`a-z`, `A-Z`), digits (`0-9`), and hyphens (`-`) are allowed.
- Each label must be 1–63 characters long.
- Labels must not start or end with a hyphen.
- The total hostname length must not exceed 253 characters.

For example, `test_user_name@example.com` is valid because underscores are allowed in the local part. However,
`user@domain_name.com` is rejected because underscores are not allowed in the domain part.

To customize email validation beyond these rules, you can replace `"format": "email"` with a `"pattern"` regex in your identity
schema. Alternatively, you can use a [before-registration webhook](../../guides/integrate-with-ory-cloud-through-webhooks.mdx) to
apply custom validation logic.

:::caution

Replacing `"format": "email"` with a custom `"pattern"` bypasses RFC-compliant validation. This can allow malformed or
undeliverable addresses into your system, which may cause issues with account recovery, email verification, and other flows that
depend on valid email addresses. Only relax validation when you have a clear need and understand the trade-offs.

:::

#### Phone number

Let's extend the identity schema from the previous chapter with a phone number:
Expand Down
Loading