Guides

Last updated

July 25, 2025

5 Ways to Implement Email Validation with Joi

Nicolas Rios

Table of Contents:

ON THIS PAGE

Heading

Get your free

email validation

API key now

4.8 from 1,863 votes

See why the best developers build on Abstract

Thank you! Your submission has been received!

Oops! Something went wrong while submitting the form.

No credit card required

Validating emails in Joi is a common step for maintaining data quality. We'll walk through five different implementation methods, complete with working code. Along the way, we'll look at the pitfalls of these traditional approaches and see how Abstract API helps overcome them.

How to Implement Email Validation in Joi

Joi offers several ways to validate email addresses. Here are four common methods, from basic syntax checks to custom rule creation, each with a corresponding code example.

Standard Joi Email Validation

The most direct method uses the “Joi.string().email()” chain. This approach employs the RFC-compliant parser from “@hapi/address” for syntax validation. It also checks the email's top-level domain against the IANA TLD list.

If a bundler removes this list, you might encounter a “Built-in TLD list disabled” error message. The Joi documentation provides more details on this function.

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

Explicit TLD Configuration

You can specify which top-level domains to accept. The “tlds” option lets you define an “allow” list, such as “com” or “net”. Alternatively, you can set “tlds” to “false” to bypass this check entirely.

This is a documented workaround for bundler issues. The “minDomainSegments” option ensures an address has a minimum number of domain parts, like in “foo@bar.com”. The official API documentation has further examples.

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

Refined Rules for Length, Unicode, and FQDNs

Joi allows for tighter control over validation rules. You can set “allowUnicode” to “false” to block non-ASCII characters, a common need for legacy systems. To enforce the 254-character limit on email addresses, set “ignoreLength” to “false”.

The “allowFullyQualified” option, when “true”, permits a trailing dot in the domain name. This can be useful for certain internal DNS workflows. More information is available on the Joi API page.

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

Custom Rules with @hapi/address

For more advanced cases, you can build a custom rule. The “custom()” method lets you use “@hapi/address” directly. The “Address.analyzeEmail” function exposes the same validator Joi uses internally.

This setup lets you chain extra logic without a need to fork Joi. The Address module API explains this in greater detail.

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 several validation methods, they come with inherent limitations. These challenges range from incomplete standards support to the inability to confirm if an email address is actually functional.

Joi only implements a subset of RFC 5322 and rejects legal UTF-8 characters in an address's local part. The standard Joi.string().email() method lacks an option to support newer international standards.
International domain names require Punycode translation. Joi validates the raw string, so native-script domains fail unless pre-encoded. This forces extra logic around methods like Joi.string().email() to handle these cases correctly.
The default Joi.string().email() rule does not require a top-level domain, so it accepts invalid addresses. To fix this, you must explicitly configure TLDs, which creates maintenance overhead for your validation schema.
Joi only asserts syntax, not deliverability. An address that passes validation with any method may still be undeliverable. The library cannot check for provider policies or actual mailbox existence.

Validate Emails with Abstract API.

Ensure data integrity in your Joi projects by implementing robust and accurate email validation.

Get started for free

How Abstract API Handles Email Validation in Joi

Abstract API addresses the core weaknesses of traditional Joi validation through real-time network checks and advanced filters.

It confirms mail deliverability through real-time MX record lookups and SMTP handshakes.
The system detects and flags disposable, role-based, and catch-all email addresses.
It suggests corrections for common typographical errors in email addresses.
The API integrates directly into Joi's asynchronous validation flow with an external hook.
It returns a clear, final verdict on deliverability, which simplifies validation logic.

How to Set Up Abstract API in Your Project

Once you're familiar with Abstract's capabilities, the addition of its email validation API to your project is simple. To prepare your development environment, you need to complete a few steps:

Sign up at Abstract and obtain your email validation API key from the dashboard.
Install the necessary packages, Joi for schema validation and Axios for HTTP requests.
Store your API key in a ".env" file to keep it out of source control.

Sample Email Validation Implementation with Abstract API

The code below defines a Joi schema that uses an external, asynchronous function to validate an email. It sends the email address to the Abstract API endpoint. If the API response indicates the email is not "DELIVERABLE" or is a disposable address, the validation fails and throws an error. Otherwise, the original email value passes.

Upon a successful validation for a deliverable email, the API returns a detailed JSON object. This payload provides a clear "DELIVERABLE" status, a quality score, and boolean flags for disposable, role-based, and free email providers. It also confirms the mail server exists and accepts connections, which offers a definitive check that simple pattern matching cannot perform.

Final Thoughts

Traditional validation methods approve syntactically correct but undeliverable emails. They fail to detect typos, disposable domains, or non-existent mail servers. Abstract API closes these gaps with real-time network checks for a definitive verdict on deliverability. To reliably validate user emails, consider an account on Abstract API to get your free API key.

Frequently Asked Questions

What does Joi's built-in email validation actually check?

Joi's Joi.string().email() uses the RFC-compliant parser from @hapi/address to verify that an address is correctly formatted and checks the top-level domain against the IANA TLD list. It confirms syntax only; it cannot verify whether the mailbox exists or whether the address will actually receive mail.

How do I restrict which top-level domains Joi accepts?

Pass the tlds option to .email() with an allow set listing only the TLDs you want to permit, for example tlds: { allow: ['com', 'net', 'io'] }. You can also set tlds: { allow: false } to skip TLD checking entirely, which is useful for avoiding the "Built-in TLD list disabled" error that appears in some environments where the list was removed to reduce bundle size.

Can Joi validate international or Unicode email addresses?

Joi supports Unicode characters in email addresses by default (allowUnicode defaults to true), but it has known gaps: it rejects some legitimate UTF-8 characters in the local portion and fails on internationalized domain names written in native scripts unless they are first converted to Punycode. Set allowUnicode: false if your system only accepts ASCII addresses.

When should I use a custom Joi rule with @hapi/address instead of the built-in email validator?

Use the custom() method with @hapi/address directly when you need validation logic that goes beyond what the built-in options expose, such as enforcing the 254-character length limit, combining multiple checks into one rule, or integrating domain-specific policies. This approach gives you full control without leaving the Joi schema pattern.

Why does an email pass Joi validation but still bounce?

All five Joi approaches described in the article are syntax-only checks: they confirm the address is formatted correctly but cannot perform MX record lookups, SMTP handshakes, or mailbox-existence probes. A syntactically valid address can still belong to a non-existent domain, a deactivated mailbox, or a disposable email provider, all of which would cause a bounce.

How do you add real deliverability checking to a Joi schema?

The article shows how to attach an external validation hook to your Joi schema that calls Abstract's Email Validation API via Axios. The hook checks the API response for a "DELIVERABLE" status and flags disposable addresses, giving you live MX and SMTP verification alongside Joi's syntax check without changing the rest of your schema.