5 Ways to Implement Email Validation with Joi

Ensuring data quality often starts with proper email validation in Joi. We'll walk through five different implementation methods, providing working code for each. After examining the pitfalls of these traditional techniques, we will see how Abstract API addresses their shortcomings.

How to Implement Email Validation in Joi

Joi offers several built-in methods to validate email addresses. Each approach provides a different level of control over the validation rules, from basic syntax checks to more specific configurations.

Vanilla Joi.string().email()

The most direct method uses Joi’s standard email validation. This function employs an RFC-compliant parser from the @hapi/address module to check the email's syntax. It also consults the official IANA Top-Level Domain (TLD) list.

If a bundler removes this list, Joi may return a “Built-in TLD list disabled” error. You can find more details in the Joi documentation and on this GitHub issue.

const schema = Joi.string().email();

Explicit TLD Configuration

This method gives you direct control over which TLDs to accept. You can provide an allow list or disable the TLD check completely. The `minDomainSegments` option ensures an address has a minimum number of domain parts, so `foo@bar` fails while `foo@bar.com` passes.

According to a Stack Overflow discussion, `tlds: false` is the documented workaround when the TLD list is not available in the browser, as noted in the official API docs.

const schema = Joi.string().email({
  tlds: { allow: ['com', 'net', 'io'] },
  minDomainSegments: 2
});

Refined Length, Unicode, and FQDN Rules

Joi allows for more granular control over email validation rules. You can adjust settings for character types, length, and domain format. Here is a breakdown of the options:

• allowUnicode: false: This option blocks non-ASCII characters in either the local or domain part of the email. This is often a requirement for legacy systems.
• ignoreLength: false: This enforces the 254-character hard limit for email addresses.
• allowFullyQualified: true: This option permits a trailing dot in the domain name, which supports certain internal DNS workflows. More information is available in the Joi API documentation and a related GitHub discussion.

const schema = Joi.string().email({
  allowUnicode: false,
  ignoreLength: false,
  allowFullyQualified: true
});

Custom Rule with @hapi/address

For more advanced cases, you can create a custom validation rule. This approach uses `Address.analyzeEmail`, the same evaluation tool Joi uses internally. The function returns a specific failure code if the email is invalid, which you can translate into a custom error message.

When you wrap this logic in a `custom()` method, you can chain additional checks, such as a company-specific blocklist. The @hapi/address documentation provides further details.

const Address = require('@hapi/address');
const emailSchema = Joi.string().custom((value, helpers) => {
  const error = Address.analyzeEmail(value, { tlds: { allow: true } });
  if (error) return helpers.error('string.email', { value });
  return value;
});

Challenges of Joi Email Validation

While Joi provides useful tools for basic email validation, its syntax-first approach presents several practical limitations. These drawbacks often force developers to implement workarounds or accept a lower standard of data quality.

• The vanilla Joi.string().email() method rejects email addresses that contain UTF-8 characters in the local part. This limitation makes it incompatible with modern international standards, as it fails to validate many legal, non-ASCII addresses.
• Joi's validator does not handle Punycode translation for internationalized domain names. As a result, native-script domains fail validation unless developers pre-encode them, which adds an extra step to the process and complicates the validation logic.
• By default, Joi.string().email() permits addresses without a top-level domain, like "user@local". To enforce a TLD, you must add extra configuration like minDomainSegments, which creates unintuitive defaults and potential maintenance friction.
• All Joi methods, including custom rules, only assert syntax correctness. They cannot determine actual mailbox deliverability, so an address that passes validation may still bounce due to provider policies or because it is a disposable domain.