freemail

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to `import freemail from 'freemail'` in an ES Module context.
  fix Use `const freemail = require('freemail');` instead. If in a pure ESM file, consider a wrapper function or a dynamic import (e.g., `const freemail = await import('freemail');` if the package supports it, which this one likely doesn't without CJS interop).

• TypeError: freemail.isFree is not a function

  cause This error can occur if `freemail` is not correctly imported as an object with `isFree` and `isDisposable` methods, or if the `require` call failed silently.
  fix Ensure `const freemail = require('freemail');` is used at the top level of a CommonJS file. Verify the package is correctly installed and accessible.

• Database update script './update' fails with network errors or parsing issues.

  cause The `sources.txt` file may contain outdated URLs or the format of external domain lists has changed, breaking the parsing logic in the `update` script.
  fix Manually inspect `node_modules/freemail/sources.txt` and the `node_modules/freemail/update` script. Update URLs, adapt parsing logic, or replace problematic sources to ensure successful data synchronization.

Warnings

• breaking The `freemail` package is a CommonJS module only. Attempting to `import` it directly in a native ES Module project will result in a runtime error (e.g., `ERR_REQUIRE_ESM`).
  Fix: For ES Module projects, you must use `require()` through a compatibility layer or configure your build system (e.g., Webpack, Rollup) to handle CommonJS modules. The simplest approach for a pure Node.js ESM project is often to create a wrapper file that uses `require()` and then re-exports.
• gotcha The project appears to be abandoned, with no significant code updates or maintenance activity in several years. This means the underlying domain database (free.txt, disposable.txt) is likely outdated and may misclassify new or changed email providers.
  Fix: Users must manually update the database by running the `./update` script provided within the package's `node_modules/freemail` directory. Be aware that this script itself may have outdated dependencies or fail due to changes in external data sources. For critical applications, consider alternatives or manually curating your own domain lists.
• gotcha The `./update` script, which synchronizes the domain database, relies on external sources defined in `sources.txt`. These external sources may change their format, URL, or availability, causing the update script to fail or import malformed data.
  Fix: Periodically inspect the `sources.txt` file and the `./update` script for potential issues. If the script fails, manual intervention may be required to fix the script or update the `sources.txt` to point to valid and current data providers.
• gotcha The database only includes domains explicitly listed as free or disposable. New or less common free/disposable email providers might not be present, leading to false negatives.
  Fix: For comprehensive coverage, users should augment the `freemail` database with their own lists or contribute updates to the project's GitHub repository, although contributions may not be merged due to project abandonment.

Install

• npm install freemail npm
• yarn add freemail yarn
• pnpm add freemail pnpm

Imports

• freemail
  wrong:

  import freemail from 'freemail';

  correct:

  const freemail = require('freemail');

  This package is a CommonJS module and does not natively support ES Module `import` syntax in modern Node.js environments without transpilation or specific loader configurations. The `require()` syntax is the only supported direct import method.
• isFree
  wrong:

  import { isFree } from 'freemail';

  correct:

  const freemail = require('freemail');
  const isFreeDomain = freemail.isFree('example@gmail.com');

  The `isFree` method is a property of the object exported by `freemail`. Using ES Module destructuring syntax for a CommonJS module will result in a runtime error.
• isDisposable
  wrong:

  import * as freemail from 'freemail';

  correct:

  const { isDisposable } = require('freemail');
  const isDisposableDomain = isDisposable('temp@mailinator.com');

  While `const freemail = require('freemail')` and then `freemail.isDisposable()` is shown in examples, destructuring the properties directly from the `require` call, as shown in the correct example, is also a valid CommonJS pattern.

Quickstart

This quickstart demonstrates how to use `freemail` to check if various email addresses belong to free or disposable email providers, illustrating its core functionality.

const freemail = require('freemail');

// Example: Checking common free email domains
console.log('Is gmail.com free?', freemail.isFree('user@gmail.com'));
console.log('Is outlook.com free?', freemail.isFree('another@outlook.com'));

// Example: Checking common disposable email domains
console.log('Is mailinator.com disposable?', freemail.isDisposable('temp@mailinator.com'));
console.log('Is yopmail.com disposable?', freemail.isDisposable('anon@yopmail.com'));

// Example: Checking a standard corporate/personal domain (should be neither)
console.log('Is mycompany.com free?', freemail.isFree('ceo@mycompany.com'));
console.log('Is mycompany.com disposable?', freemail.isDisposable('ceo@mycompany.com'));

// Demonstrating the full object structure (optional, for inspection)
// console.log(Object.keys(freemail));