Introduction

@nestbolt/disposable-email is a NestJS module that prevents users from signing up or submitting forms with disposable (temporary/throwaway) email addresses. It ships with a comprehensive, regularly-updated list of known disposable email providers and integrates directly with the class-validator ecosystem, so blocking throwaway emails is as simple as adding a decorator to your DTO.

Key Features

• Single-decorator validation -- add @IsNotDisposableEmail() to any DTO property and disposable emails are automatically rejected.
• Comprehensive domain list -- ships with thousands of known disposable domains sourced from disposable/disposable, a widely-trusted community-maintained list.
• Subdomain matching -- optionally block subdomains of known disposable providers (e.g. sub.mailinator.com).
• Domain whitelisting -- allow specific domains through even if they appear on the disposable list.
• Automatic updates -- fetch fresh domain lists from remote sources on a schedule, so your blocklist stays current without redeploying.
• Custom fetcher support -- bring your own HTTP client for environments that require proxies, custom headers, or other request modifications.
• Local persistence -- save fetched domain lists to disk so they survive application restarts.
• Standalone mode -- the decorator works even without registering the NestJS module, falling back to the bundled domain list.
• Global module -- register once in your root module and use the decorator and service anywhere in your application.

Quick Example

import { IsEmail, IsNotEmpty } from "class-validator";
import { IsNotDisposableEmail } from "@nestbolt/disposable-email";

export class CreateUserDto {
  @IsNotEmpty()
  @IsEmail()
  @IsNotDisposableEmail()
  email: string;

  @IsNotEmpty()
  name: string;
}

When a user submits a disposable email address such as user@mailinator.com, the validation pipeline returns a 400 Bad Request response:

{
  "statusCode": 400,
  "message": ["Disposable email addresses are not allowed."],
  "error": "Bad Request"
}

How It Works

The module loads a set of known disposable email domains at startup. When a request comes in containing an email field decorated with @IsNotDisposableEmail(), the validator extracts the domain portion of the email address and checks it against the loaded set. If the domain is found in the disposable list (and is not whitelisted), validation fails and the request is rejected.

The domain set is stored in memory as a Set<string> for O(1) lookups, so there is no measurable performance overhead on individual validations -- even with tens of thousands of domains loaded.

Architecture

The package is composed of three main parts:

1. DisposableEmailModule -- a dynamic NestJS module that accepts configuration via forRoot() or forRootAsync() and registers the service and validator constraint as global providers.
2. DisposableEmailService -- an injectable service that manages the domain set, provides programmatic checking methods (isDisposable, isNotDisposable), and handles fetching and persisting updated domain lists.
3. @IsNotDisposableEmail() decorator -- a class-validator decorator that delegates to the service when available, or falls back to the bundled domain list for standalone usage.

Next Steps

• Installation -- install the package and its peer dependencies.
• Quick Start -- go from zero to blocking disposable emails in minutes.
• Configuration -- explore all available configuration options.
• Decorator -- learn about the @IsNotDisposableEmail() decorator in depth.
• Service API -- use the service directly for programmatic email checks.
• Domain Updates -- keep your domain list fresh with scheduled updates.