no-disposable-email

A fast, reliable tool to check if an email address uses a disposable domain. Includes an Express API, CLI, and utility function. Perfect for validation in web apps, and scripts.

Table of Contents

• Features
• Demo
• Installation
• Usage
  • API
  • CLI
  • Utility Function
• Docker
• Development
• Contributing
• License

Features

• 🚀 Express API: /check?email=... endpoint
• 🛠️ CLI: npx no-disposable-email <email>
• 🧩 Utility: isDisposable(email)
• 🐳 Docker support
• ⚡ Domains are regularly updated from https://github.com/disposable-email-domains/disposable-email-domains/blob/main/disposable_email_blocklist.conf

Demo

Try it online :
Is Disposable Email API or Is Disposable Email GUI

Installation

NPM (CLI & Utility)

npm install no-disposable-email

Clone & Run Locally

git clone https://github.com/yassirh/no-disposable-email.git

cd no-disposable-email

npm install

Usage

API

Start the server:

node index.js

Check an email:

curl 'http://localhost:3000/[email protected]'

Response:

{
  "email": "[email protected]",
  "disposable": true
}

CLI

npx no-disposable-email [email protected]
# or if installed globally
no-disposable-email [email protected]

Utility Function

const { isDisposable } = require('no-disposable-email');

console.log(isDisposable('[email protected]')); // true or false

Heartbeat Endpoint

A simple health check endpoint is available:

GET /heartbeat

Response:

{
  "status": "ok"
}

You can use this to verify the service is running (e.g., for Docker health checks or uptime monitoring).

Docker

Running with Docker

To run the service using Docker:

Start the container, mapping port 3000 inside the container to port 3000 on your host:

docker run -d -p 3000:3000 yassirh/no-disposable-email

The API will be available at: http://localhost:3000/[email protected]

Build and run with Docker:

docker build -t no-disposable-email .

docker run -p 3000:3000 no-disposable-email

Multi-Architecture Image for Docker Hub

To build and push a multi-architecture image to Docker Hub:

docker buildx create --use
# Build for amd64 and arm64 v8
docker buildx build --platform linux/amd64,linux/arm64/v8 -t yassirh/no-disposable-email:latest --push .

Updating the Blocklist

To update the list of disposable domains to the latest version from the official source, run:

npm run update-blocklist

This will download the latest disposable_email_blocklist.conf from the upstream repository.

Development

• Add domains to disposable_email_blocklist.conf (one per line)
• Run tests:

npm test

Contributing

Pull requests welcome! For major changes, open an issue first to discuss what you would like to change.

License

You can copy, modify, distribute and use the work, even for commercial purposes, all without asking permission.