tempmailtracker

Node.js library jo signup/login forms me disposable, temporary ya fake email addresses (jaise mailinator, guerrillamail, 10minutemail, etc.) ko detect aur block karti hai — taaki users apni real email hi use karein.

⚠️ Important, honest disclaimer: Koi bhi disposable-email checker 100% ya "99.99% guaranteed" nahi ho sakta. Naye temp-mail services roz launch hote hain, aur koi bhi library sirf ek known-domain list + DNS check ke basis par kaam karti hai. Ye library ek achi, production-grade first line of defense hai (list + MX record check), lekin isse full-proof mat samjho — abuse-prone signups ke liye OTP verification jaise extra layers bhi rakhna best practice hai.

Features

• ✅ 159,000+ known disposable/temp-mail domains ka bundled list — 4 alag maintained open-source projects se merge kiya gaya hai
• ✅ Domain whitelisting (allowedDomains) — sirf specific domains allow karo (e.g. sirf Gmail), baaki sab reject
• ✅ Gmail dot/plus-trick detection (normalizeEmail) — [email protected], [email protected], [email protected] — ye sab actually same real inbox hai; isse fake-multiple-account abuse rukta hai
• ✅ Live real-time check (checkLive) — Kickbox ki free, constantly-updated database se live query karta hai. Ye specifically rotating temp-mail domains (jaise temp-mail.org, jo har kuch ghante me naye random domains banata hai — e.g. aghism.com type) ko pakadne ke liye hai, jo kisi bhi static bundled list me miss ho sakte hain
• ✅ Subdomain matching (e.g. abc.mailinator.com bhi block hoga agar mailinator.com list me hai)
• ✅ Built-in safety net — well-known real providers (Gmail, Yahoo, Outlook, iCloud, etc.) aur reserved/placeholder domains hamesha hardcoded "safe" rehte hain
• ✅ Email syntax validation (regex based)
• ✅ Optional MX record check
• ✅ Optional domain age / reputation check (RDAP based, no API key)
• ✅ Custom blocklist aur allowlist
• ✅ Ready-made Express middleware
• ✅ Zero runtime dependencies
• ✅ TypeScript type definitions included

⚠️ Rotating temp-mail domains (jaise temp-mail.org) ke baare me zaroori baat

temp-mail.org jaisi services har kuch ghante me naya random domain generate karti hain. Koi bhi static/bundled list is rotation ke saath 100% real-time match nahi kar sakti — ye ek fundamental limitation hai, sirf is library ki nahi, kisi bhi disposable-email checker ki. Isiliye is library me ab checkLive: true option hai, jo ek continuously-updated live database se bhi check karta hai — bundled list ke saath milke coverage kaafi behtar ho jaati hai.

const result = await tempMailTracker.validate('[email protected]', {
  checkLive: true,       // default: false — live API call karta hai
  liveTimeoutMs: 3000,
});

Isse bhi 100% guarantee nahi milti (rotation itni fast ho sakti hai ki koi bhi source turant catch na kar paaye), lekin ye significantly better coverage deta hai bundled-list-only approach se. Runtime par outbound internet access zaroori hai.

Chrome extension detect karti hai kya?

Nahi, aur ye technically possible bhi nahi hai — ye ek Node.js backend/server-side library hai. Server ko kabhi pata nahi chal sakta ki user ke browser me kaunsa extension install hai (browsers is data ko privacy reasons se expose hi nahi karte, koi bhi library isse bypass nahi kar sakti). Lekin practically fark nahi padta: jab bhi koi temp-mail Chrome extension (fake email generator) use hota hai, wo backend ko ek real domain string hi bhejta hai (e.g. [email protected]) — aur wo domain almost hamesha is library ki list me already maujood hota hai. Toh result same milta hai, bas detection domain-level par hoti hai, extension-level par nahi.

Installation

npm install tempmailtracker

Quick Usage

1. Simple check — kya ye email disposable hai?

const tempMailTracker = require('tempmailtracker');

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

2. Full validation (syntax + disposable check)

const tempMailTracker = require('tempmailtracker');

async function checkEmail() {
  const result = await tempMailTracker.validate('[email protected]');
  console.log(result);
  /*
  {
    email: '[email protected]',
    valid: false,
    syntaxValid: true,
    disposable: true,
    mxValid: null,
    reason: 'DISPOSABLE_EMAIL'
  }
  */
}

checkEmail();

3. Full validation + Live check (rotating temp-mail domains ke liye — recommended)

const result = await tempMailTracker.validate('[email protected]', {
  checkLive: true,      // default: false — real-time database se bhi check karega
  liveTimeoutMs: 3000,
});

if (!result.valid) {
  console.log('Reason:', result.reason);           // 'DISPOSABLE_EMAIL'
  console.log('Kahan se pakda:', result.disposableSource); // 'builtin-list' ya 'live-api'
}

4. Full validation + MX record check (extra layer, thodi der lagti hai)

MX check yeh confirm karta hai ki domain ke paas mail server hi nahi hai (jaise [email protected] type ke fake/typo domains).

const result = await tempMailTracker.validate('[email protected]', {
  checkMx: true,       // default: false
  mxTimeoutMs: 3000,   // default: 3000ms, taaki request slow na ho
});

if (!result.valid) {
  console.log('Reject this email. Reason:', result.reason);
  // reason values: 'INVALID_SYNTAX' | 'DISPOSABLE_EMAIL' | 'NO_MX_RECORD'
}

5. Domain age check (naye/suspicious registered domains pakadne ke liye)

Ye check RDAP protocol (free, no API key) use karke domain ka registration date pata karta hai. Bahut naye domains (kuch din pehle hi register hue) aksar fake/throwaway signups ka signal hote hain.

const result = await tempMailTracker.validate('[email protected]', {
  checkDomainAge: true,   // default: false
  minDomainAgeDays: 30,   // isse kam age wale domains "suspicious" maane jayenge
  domainAgeTimeoutMs: 4000,
});

console.log(result.domainAge);
/*
{
  domain: 'somebrandnewsite.xyz',
  createdDate: '2026-07-20T00:00:00Z',
  ageInDays: 12,
  suspicious: true,
  checked: true
}
*/

Note: checked: false ka matlab hai RDAP data available nahi mila (kuch TLDs/registrars RDAP support nahi karte, ya network issue) — isko "unknown" treat karo, "safe" ya "suspicious" nahi. Ye check bhi runtime par outbound internet access maangta hai.

Direct standalone use bhi kar sakte ho:

const age = await tempMailTracker.checkDomainAge('somebrandnewsite.xyz');

6. Apna custom blocklist / allowlist add karna

const tempMailTracker = require('tempmailtracker');

// Apni company ka koi specific domain bhi block karna hai
tempMailTracker.addBlockedDomain('competitor-temp-mail.com');
tempMailTracker.addBlockedDomain(['xyz.com', 'abc.io']); // multiple ek saath

// Agar builtin list me koi domain galti se block ho raha hai (false positive),
// use allowlist me daal do — ye builtin list se zyada priority leta hai
tempMailTracker.addAllowedDomain('mycompany-mail.com');

7. Sirf ek domain allow karna (e.g. sirf @gmail.com) + tricks block karna

Do cheezein chahiye hoti hain isके liye:

A) allowedDomains — har doosra domain reject ho jayega:

const result = await tempMailTracker.validate('[email protected]', {
  allowedDomains: ['gmail.com'], // sirf gmail.com allow, baaki sab (real ho ya fake) reject
});
console.log(result.valid);   // false
console.log(result.reason);  // 'DOMAIN_NOT_ALLOWED'

B) normalizeEmail() — Gmail ke "tricks" pakadne ke liye:

Gmail khud dots ignore karta hai aur +tag ko bhi ignore karta hai — matlab ye teeno emails asal me ek hi real inbox hain:

[email protected]
[email protected]
[email protected]
[email protected]

Agar tum inhe alag-alag "unique" email maan loge, to koi bhi user in tricks se multiple fake accounts bana sakta hai (jaise multiple free-trials lene ke liye). Isse rokne ke liye, signup ke time email ko normalize karke duplicate check karo — raw email nahi:

const tempMailTracker = require('tempmailtracker');

async function registerUser(email, password) {
  // Step 1: sirf gmail allow
  const validation = await tempMailTracker.validate(email, {
    allowedDomains: ['gmail.com'],
  });
  if (!validation.valid) {
    throw new Error('Sirf Gmail addresses allowed hain: ' + validation.reason);
  }

  // Step 2: canonical form nikaalo aur usi se duplicate check karo
  const canonicalEmail = tempMailTracker.normalizeEmail(email);
  // '[email protected]' aur '[email protected]' dono → '[email protected]'

  const alreadyExists = await db.findUserByCanonicalEmail(canonicalEmail);
  if (alreadyExists) {
    throw new Error('Is Gmail se account pehle se bana hua hai (dot/plus trick detect hui)');
  }

  await db.createUser({ email, canonicalEmail, password });
}

Isse register karte waqt agar koi [email protected] se already account bana chuka hai, aur wahi user dobara [email protected] se register karne ki koshish kare, to canonicalEmail same ([email protected]) niklega aur signup duplicate ke roop me block ho jayega.

8. Express.js middleware (direct signup route me plug-in)

const express = require('express');
const tempMailTracker = require('tempmailtracker');

const app = express();
app.use(express.json());

app.post(
  '/signup',
  tempMailTracker.middleware({ field: 'email', checkMx: true }),
  (req, res) => {
    // Yahan tak request tabhi pahunchegi jab email valid + non-disposable ho
    // req.emailValidation me full result available hai
    res.json({ message: 'Signup successful!' });
  }
);

app.use((err, req, res, next) => {
  res.status(500).json({ error: 'Something went wrong' });
});

app.listen(3000, () => console.log('Server running on port 3000'));

Agar disposable/fake email aayi to middleware khud hi response bhej dega:

{
  "error": "Invalid or disposable email address",
  "reason": "DISPOSABLE_EMAIL"
}

API Reference

isDisposable(email: string): boolean

Sync check — sirf built-in + custom list ke against check karta hai (no network call).

isDisposableLive(domain: string, options?): Promise<boolean|null>

Live/real-time check ek continuously-updated database se (Kickbox API, free, no key). Rotating temp-mail domains (jaise temp-mail.org) ke liye best hai. Returns true/false, ya null agar API unreachable ho.

isValidSyntax(email: string): boolean

Basic email format validation.

normalizeEmail(email: string): string | null

Email ko canonical form me convert karta hai — Gmail ke dots aur +tag tricks ko strip karta hai, googlemail.com ko gmail.com bana deta hai, aur baaki domains ke liye sirf +tag strip karta hai. Duplicate-account detection ke liye use karo. Invalid email par null return karta hai.

validate(email: string, options?): Promise<ValidationResult>

Full check. Options: | Option | Type | Default | Description | |---|---|---|---| | allowedDomains | string[] | undefined | Sirf inhi domains ko allow karega, baaki sab reject (real domains bhi) | | checkLive | boolean | false | Recommended. Live/real-time database check — rotating temp-mail domains ke liye | | liveTimeoutMs | number | 3000 | Live check ka max wait time | | checkMx | boolean | false | Domain ke MX DNS records verify karega | | mxTimeoutMs | number | 3000 | MX lookup ka max wait time | | checkDomainAge | boolean | false | RDAP se domain ki registration age check karega | | minDomainAgeDays | number | 30 | Isse kam age wale domains suspicious flag honge | | domainAgeTimeoutMs | number | 4000 | RDAP lookup ka max wait time |

Return value:

{
  email: string,
  valid: boolean,
  syntaxValid: boolean,
  disposable: boolean,
  disposableSource: 'builtin-list' | 'live-api' | null,
  mxValid: boolean | null,
  domainAge: {
    domain: string,
    createdDate: string | null,
    ageInDays: number | null,
    suspicious: boolean,
    checked: boolean
  } | null,
  reason: 'INVALID_SYNTAX' | 'DOMAIN_NOT_ALLOWED' | 'DISPOSABLE_EMAIL' | 'NO_MX_RECORD' | 'DOMAIN_TOO_NEW' | null
}

addBlockedDomain(domain: string | string[]): void

Runtime par apna custom blocklist add karo.

addAllowedDomain(domain: string | string[]): void

False-positives ke liye allowlist (builtin list ko override karta hai).

hasMxRecord(domain: string): Promise<boolean>

Direct MX-record check kisi bhi domain ke liye.

checkDomainAge(domain: string, options?): Promise<DomainAgeResult>

Direct RDAP-based domain age check kisi bhi domain ke liye. Options: { timeoutMs?: number, minAgeDays?: number }.

middleware(options?)

Express/Connect style middleware. Options: { field?: string, checkMx?: boolean, checkDomainAge?: boolean, minDomainAgeDays?: number }.

builtinListSize: number

Kitne domains built-in list me currently maujood hain.

Disposable domain list update karna

Bundled list lib/domains.json me hai (open-source disposable-email-domains project se, MIT licensed — attribution NOTICE file me hai). Latest list khींchne ke liye:

npm run update-list

Ye script GitHub se latest list download karke lib/domains.json ko refresh kar degi.

Testing

npm test

Best Practices / Suggestions

1. checkLive: true production me use karo — ye rotating temp-mail domains (jaise temp-mail.org) ke against sabse effective hai, kyunki static list unko catch nahi kar payegi.
2. Sirf list-based check kaafi nahi hoti — critical signups (jaise banking, paid trials) ke liye OTP/email-verification link bhi bhejo.
3. checkMx: true production me use karo (extra ~100-300ms lagta hai, but fake/typo domains catch karta hai).
4. List ko periodically npm run update-list se refresh karte raho, kyunki naye temp-mail services aate rehte hain.
5. False positive mile to addAllowedDomain() se turant fix kar sakte ho, bina naya deploy kiye (agar runtime config se load ho raha ho).

License

MIT — free to use in personal & commercial projects. Bundled domain list attribution NOTICE file me hai.