This package provides a class-validator decorator for NestJS that validates email addresses against a comprehensive list of known disposable email services such as Mailinator, Guerrillamail, Tempmail, and thousands more.

Once installed, blocking disposable emails is as simple as adding a decorator to your DTO:

import { IsNotDisposableEmail } from "@nestbolt/disposable-email";

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

Uses the disposable domains list from disposable/disposable by default — the same trusted source used by many other packages across different ecosystems.

Table of Contents

• Installation
• Quick Start
• Module Configuration
  • Static Configuration (forRoot)
  • Async Configuration (forRootAsync)
• Using the Decorator
• Using the Service Directly
• Configuration Options
• Features
  • Subdomain Matching
  • Whitelisting Domains
  • Custom Fetcher
  • Updating the Domains List
• Standalone Usage
• Testing
• Changelog
• Contributing
• Security
• Credits
• License

Installation

Install the package via npm:

npm install @nestbolt/disposable-email

Or via yarn:

yarn add @nestbolt/disposable-email

Or via pnpm:

pnpm add @nestbolt/disposable-email

Peer Dependencies

This package requires the following peer dependencies, which you likely already have in a NestJS project:

@nestjs/common ^10.0.0 || ^11.0.0
@nestjs/core   ^10.0.0 || ^11.0.0
class-validator ^0.14.0
class-transformer ^0.5.0
reflect-metadata ^0.1.13 || ^0.2.0

Quick Start

1. Register the module in your AppModule:

import { Module } from "@nestjs/common";
import { DisposableEmailModule } from "@nestbolt/disposable-email";

@Module({
  imports: [DisposableEmailModule.forRoot()],
})
export class AppModule {}

2. Enable class-validator's DI container in main.ts:

import { NestFactory } from "@nestjs/core";
import { ValidationPipe } from "@nestjs/common";
import { useContainer } from "class-validator";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Enable class-validator to use NestJS DI container
  useContainer(app.select(AppModule), { fallbackOnErrors: true });

  app.useGlobalPipes(new ValidationPipe({ whitelist: true }));

  await app.listen(3000);
}
bootstrap();

3. Use the @IsNotDisposableEmail() decorator in your DTOs:

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

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

  @IsNotEmpty()
  name: string;
}

That's it! Any request with a disposable email will now receive a 400 Bad Request response with the validation error:

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

Module Configuration

Static Configuration (forRoot)

Pass options directly to forRoot():

import { Module } from "@nestjs/common";
import { DisposableEmailModule } from "@nestbolt/disposable-email";

@Module({
  imports: [
    DisposableEmailModule.forRoot({
      whitelist: ["example.com", "mycompany.com"],
      includeSubdomains: true,
      storagePath: "./storage/disposable_domains.json",
      sources: [
        "https://cdn.jsdelivr.net/gh/disposable/disposable-email-domains@master/domains.json",
      ],
    }),
  ],
})
export class AppModule {}

Async Configuration (forRootAsync)

Use forRootAsync() when your configuration depends on other services, such as ConfigService:

import { Module } from "@nestjs/common";
import { ConfigModule, ConfigService } from "@nestjs/config";
import { DisposableEmailModule } from "@nestbolt/disposable-email";

@Module({
  imports: [
    ConfigModule.forRoot(),
    DisposableEmailModule.forRootAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({
        whitelist: config
          .get<string>("DISPOSABLE_WHITELIST", "")
          .split(",")
          .filter(Boolean),
        includeSubdomains: config.get<boolean>(
          "DISPOSABLE_INCLUDE_SUBDOMAINS",
          false,
        ),
        storagePath: config.get<string>("DISPOSABLE_STORAGE_PATH", ""),
      }),
    }),
  ],
})
export class AppModule {}

Note: The module is registered as global by default, so you only need to import it once in your root module. The DisposableEmailService and the decorator will be available throughout your entire application.

Using the Decorator

The @IsNotDisposableEmail() decorator works just like any other class-validator decorator. You can combine it with other validators and customize the error message:

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

export class RegisterDto {
  @IsEmail()
  @IsNotDisposableEmail({
    message: "Please use a permanent email address to register.",
  })
  email: string;
}

With Validation Groups

export class UpdateProfileDto {
  @IsEmail()
  @IsNotDisposableEmail({ groups: ["registration"] })
  email: string;
}

Using the Service Directly

You can also inject DisposableEmailService anywhere in your application for programmatic checks:

import { Injectable } from "@nestjs/common";
import { DisposableEmailService } from "@nestbolt/disposable-email";

@Injectable()
export class UsersService {
  constructor(private readonly disposableEmail: DisposableEmailService) {}

  async createUser(email: string) {
    if (this.disposableEmail.isDisposable(email)) {
      throw new BadRequestException("Disposable emails are not allowed");
    }

    // ... create the user
  }
}

Available Service Methods

| Method | Returns | Description | | ------------------------ | --------------- | ---------------------------------------------------------- | | isDisposable(email) | boolean | Returns true if the email's domain is disposable | | isNotDisposable(email) | boolean | Returns true if the email's domain is not disposable | | getDomains() | string[] | Returns the full list of loaded disposable domains | | updateDomains() | Promise<void> | Fetches fresh domains from the configured sources | | bootstrap() | void | Reloads domains from local storage or the bundled list |

Configuration Options

| Option | Type | Default | Description | | ------------------- | ---------- | ---------------- | ------------------------------------------------------------------------------------- | | sources | string[] | jsDelivr CDN URL | Source URLs returning JSON arrays of disposable domains | | storagePath | string | '' | Local file path to persist fetched domains. When empty, only the bundled list is used | | whitelist | string[] | [] | Domains to exclude from the disposable list (allow through validation) | | includeSubdomains | boolean | false | When true, subdomains of disposable domains are also rejected | | fetcher | Fetcher | DefaultFetcher | Custom fetcher implementation for retrieving domain lists |

Features

Subdomain Matching

By default, only exact domain matches are checked. Enable includeSubdomains to also catch subdomains of known disposable domains:

DisposableEmailModule.forRoot({
  includeSubdomains: true,
});

With this enabled:

• [email protected] → blocked (exact match)
• [email protected] → blocked (subdomain match)
• [email protected] → allowed

Whitelisting Domains

If a domain appears in the disposable list but you want to allow it, add it to the whitelist:

DisposableEmailModule.forRoot({
  whitelist: ["example.com", "legitimate-service.com"],
});

Whitelisted domains are removed from the disposable set at load time, so there is no per-validation overhead.

Custom Fetcher

By default, the package uses the native fetch() API to retrieve domain lists. If your application runs behind a proxy or needs custom headers, implement the Fetcher interface:

import { Fetcher } from "@nestbolt/disposable-email";
import { HttpsProxyAgent } from "https-proxy-agent";

export class ProxyFetcher implements Fetcher {
  async fetch(url: string): Promise<string[]> {
    const response = await fetch(url, {
      agent: new HttpsProxyAgent("http://your-proxy:8080"),
    });

    if (!response.ok) {
      throw new Error(`Failed to fetch: ${response.statusText}`);
    }

    return response.json();
  }
}

Then pass it in the module configuration:

DisposableEmailModule.forRoot({
  fetcher: new ProxyFetcher(),
});

Updating the Domains List

The package ships with a bundled domains.json containing thousands of known disposable domains. To keep this list fresh, call updateDomains() on a schedule.

With a Cron Job (using @nestjs/schedule)

import { Injectable } from "@nestjs/common";
import { Cron, CronExpression } from "@nestjs/schedule";
import { DisposableEmailService } from "@nestbolt/disposable-email";

@Injectable()
export class DomainsUpdateTask {
  constructor(private readonly disposableEmail: DisposableEmailService) {}

  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
  async handleCron() {
    await this.disposableEmail.updateDomains();
  }
}

From a Controller / Admin Endpoint

import { Controller, Post, UseGuards } from "@nestjs/common";
import { DisposableEmailService } from "@nestbolt/disposable-email";

@Controller("admin")
export class AdminController {
  constructor(private readonly disposableEmail: DisposableEmailService) {}

  @Post("update-disposable-domains")
  @UseGuards(AdminGuard)
  async updateDomains() {
    await this.disposableEmail.updateDomains();
    return { message: "Disposable domains list updated successfully" };
  }
}

Tip: Set a storagePath in your configuration so that fetched domains are persisted to disk. This way your application will use the updated list even after a restart, without needing to re-fetch.

Standalone Usage

The @IsNotDisposableEmail() decorator also works without registering the NestJS module. In this mode, it falls back to the bundled domains.json list directly:

import { validate } from "class-validator";
import { IsNotDisposableEmail } from "@nestbolt/disposable-email";

class EmailDto {
  @IsNotDisposableEmail()
  email: string;
}

const dto = new EmailDto();
dto.email = "[email protected]";

const errors = await validate(dto);
// errors[0].constraints.isNotDisposableEmail === 'Disposable email addresses are not allowed.'

Note: Standalone mode does not support whitelist, subdomain matching, or custom fetchers. For the full feature set, register the DisposableEmailModule.

Testing

npm test

Run tests in watch mode:

npm run test:watch

Generate coverage report:

npm run test:cov

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please report them via GitHub Issues with the security label instead of using the public issue tracker.

Credits

• Disposable domains list from disposable/disposable

License

The MIT License (MIT). Please see License File for more information.