# email-domain-check

> Comprehensive email domain validation library with DNS, MX, SMTP, DKIM, DMARC and MTA-STS support.

Latest version **2.0.5** (published 2025-11-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install email-domain-check
pnpm add email-domain-check
yarn add email-domain-check
bun add email-domain-check
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.5 |
| Published | 2025-11-27 |
| First published | 2017-12-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 93.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 9 |
| Author | Mehmet Kozan |
| Maintainers | mehmet.kozan |
| Keywords | email, dkim, spf, arc, dmarc, bimi, mta-sts, email-domain, mx, smtp, mta, email-validation, validate-email, mailcheck, email-checker, email-validator |

## Links

- npm: https://www.npmjs.com/package/email-domain-check
- Repository: https://github.com/mehmet-kozan/email-domain-check
- Issues: https://github.com/mehmet-kozan/email-domain-check/issues
- npm.io page: https://npm.io/package/email-domain-check

## Dependencies (1)

- [tldts](https://npm.io/package/tldts.md) ^7.0.19

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 2.0.5 (latest) — 2025-11-27
- 2.0.4 — 2025-11-27
- 2.0.3 — 2025-11-27
- 2.0.2 — 2025-11-25
- 2.0.1 — 2025-11-25
- 2.0.0 — 2025-11-25
- 1.1.5 — 2025-11-19
- 1.1.4 — 2017-12-29
- 1.1.3 — 2017-12-15
- 1.1.0 — 2017-12-15
- 0.1.0 — 2017-12-03

## README

<div align="center"> 

# email-domain-check

**A comprehensive email domain validation library.** 
**Supports DNS, MX, SMTP, DKIM, DMARC, and MTA-STS.**  

</div> 

<div align="center">  

[![version](https://img.shields.io/npm/v/email-domain-check.svg)](https://www.npmjs.org/package/email-domain-check)
[![downloads](https://img.shields.io/npm/dt/email-domain-check.svg)](https://www.npmjs.org/package/email-domain-check)
[![node](https://img.shields.io/node/v/email-domain-check.svg)](https://nodejs.org/)  

</div>

<br />

## Features

-  MX record validation
-  SMTP server connection testing
-  DKIM record lookup
-  DMARC policy validation
-  MTA-STS support (RFC 8461)
-  IPv4/IPv6 support
-  Local IP blocking
-  DNS failover resolvers
-  Punycode/IDN support
-  TypeScript support

## Installation

```bash
npm install email-domain-check
# or
pnpm add email-domain-check
# or
yarn add email-domain-check
# or
bun add email-domain-check
```

## Usage (ESM / TypeScript)  

```ts
import { Address, DomainChecker } from 'email-domain-check';

const checker = new DomainChecker();

// Check if domain has MX records
const hasMx = await checker.hasMxRecord('user@gmail.com');
console.log('Has MX:', hasMx);

// Get MX records with priority
const mxRecords = await checker.getMxRecord({
	target: 'gmail.com', // string, URL or Address
	useCache: false,
	preferDomainNS: false, // use authoritative ns `ns1.google.com`
});
console.log('MX Records:', mxRecords);
// [{ exchange: 'gmail-smtp-in.l.google.com', priority: 5 }]

// use url, domain or email
const url = new URL('https://gmail.com');
const addr_01 = Address.loadFromTarget(url);
const addr_02 = Address.loadFromTarget('gmail.com');
const addr_03 = Address.loadFromTarget('user@gmail.com');
const addr_04 = new Address('mehmet.kozan@gmail.com'); // email or domain

console.log('Has MX 01:', await checker.hasMxRecord(addr_01));
console.log('Has MX 02:', await checker.hasMxRecord(addr_02));
console.log('Has MX 03:', await checker.hasMxRecord(addr_03));
console.log('Has MX 04:', await checker.hasMxRecord(addr_04));
// or direct use
console.log('Has MX 05:', await checker.hasMxRecord(new URL('https://gmail.com')));
console.log('Has MX 06:', await checker.hasMxRecord('gmail.com'));
console.log('Has MX 07:', await checker.hasMxRecord('user@gmail.com'));
console.log('Has MX 08:', await checker.hasMxRecord('mehmet.kozan@gmail.com'));
```

## Usage (CommonJS)

```js
const { DomainChecker } = require('email-domain-check');

async function run() {
	const checker = new DomainChecker();

	// Check if domain has MX records
	const hasMx = await checker.hasMxRecord('user@gmail.com');
	console.log('Has MX:', hasMx);

	// Get MX records with priority
	const mxRecords = await checker.getMxRecord({
		target: 'gmail.com', // string, URL or Address
		useCache: false,
		preferDomainNS: false, // use authoritative ns `ns1.google.com`
	});
	console.log('MX Records:', mxRecords);
	// [{ exchange: 'gmail-smtp-in.l.google.com', priority: 5 }]
}

run();
```

## Advance Usage

#### Get Records
```ts
import { DomainChecker } from 'email-domain-check';

const checker = new DomainChecker();

// Get SPF record
const spf = await checker.getSpfRecord({
	target: 'mehmet.kozan@cambly.com',
	dkimSelector: 'k1',
});
console.log('SPF:', spf);

// Get DKIM record
const dkim = await checker.getDkimRecord({
	target: 'mehmet.kozan@cambly.com',
	dkimSelector: 'k1',
});
console.log('DKIM:', dkim);

// Get DMARC record
const dmarc = await checker.getDmarcRecord({
	target: 'gmail.com',
});
console.log('DMARC:', dmarc);

// Get MTA-STS record
const sts = await checker.getStsRecord({
	target: 'user@gmail.com',
});
console.log('MTA-STS:', sts);

// Get custom records
const customRecords = await checker.getCustomRecords({
	target: 'user@gmail.com',
});
console.log('Custom Records:', customRecords);

// Get custom kv record
const kvRecord = await checker.getCustomKVRecord(
	{
		target: 'user@gmail.com',
	},
	'yahoo-verification-key',
);
console.log('KV Record:', kvRecord);

// Get custom kv record
const allKVRecord = await checker.getAllKVRecords({
	target: 'user@gmail.com',
});
console.log('All KV Records:', allKVRecord);
```

#### Get Authoritative Name Servers

```ts
import { DomainChecker } from "email-domain-check";
const checker = new DomainChecker();

// Get name servers
const nameServers = await checker.getNameServers("gmail.com");
console.log("Name Servers:", nameServers);


```

#### Get SMTP Connection
```ts
import { DomainChecker } from "email-domain-check";

const checker = new DomainChecker();
// Test or Get SMTP connection for mail sending
const socket = await checker.getSmtpConnection("user@example.com");
if (socket) {
  console.log("SMTP connection successful");
  socket.end();
}
```

#### MTA-STS Policy
```ts
import { getMtaStsPolicy, isMxAllowed } from "email-domain-check";

const policy = await getMtaStsPolicy("gmail.com");
if (policy) {
  console.log("MTA-STS Policy:", policy);
  // { version: 'STSv1', mode: 'enforce', mx: ['*.google.com'], max_age: 86400 }
  
  const allowed = isMxAllowed("alt1.gmail-smtp-in.l.google.com", policy);
  console.log("MX Allowed:", allowed);
}
```

#### Address Parsing and Validation
```ts
import {Address } from "email-domain-check";
// Address parsing and validation
const addr = Address.loadFromTarget("user@example.com");
console.log("Hostname:", addr.hostname); // example.com
console.log("User:", addr.user); // user
console.log("Is IP:", addr.isIP); // false
console.log("Is Local:", addr.isLocal); // false
console.log("Has Punycode:", addr.hasPunycode); // false

// Parse from URL
const url = new URL("https://example.com/path");
const urlAddr = Address.loadFromTarget(url);
console.log("From URL:", urlAddr.hostname); // example.com

// IP address validation
const Addr_01 = new Address("192.168.1.1");
console.log("Is Local IP:", Addr_01.isLocal); // true

const Addr_02 = new Address("8.8.8.8");
console.log("Is Local IP:", Addr_02.isLocal); // false
```

## API

### DomainChecker Class

#### Constructor Options

```ts
interface DomainCheckerOptions {
  server?: string[];            // Custom DNS servers
  dkimSelector?: string;        // Default: 'default'
  useCache?: boolean;           // Enable DNS caching
  cacheTTL?: number;            // Cache TTL in ms
  smtpTimeout?: number;         // Default: 10000
  dnsTimeout?: number;          // Default: 5000
  httpTimeout?: number;         // Default: 8000
  socketIdleTimeout?: number;   // RFC 5321 socket idle timeout
  useDomainNS?: boolean;        // Query domain's authoritative nameservers (Default: false)
  useMtaSts?: boolean;          // Enable MTA-STS related lookups (Default: false)
  ignoreIPv6?: boolean;         // Ignore IPv6 addresses
  tries?: number;               // Default: 3
  failoverServers?: string[][]; // Default: [['1.1.1.1','1.0.0.1'], ['8.8.8.8','8.8.4.4']]
  blockLocalIPs?: boolean;      // Block local/private IPs (Default: false)
  deliveryPort?: number;        // Default: 25
}
```

#### Methods

- `hasMxRecord(target: Target): Promise<boolean>` - Check if domain has MX records
- `getMxRecord(options: ResolveOptions): Promise<MxRecord[]>` - Get MX records
- `getSmtpConnection(target: Target): Promise<Socket | null>` - Test SMTP connection
- `getTxtRecord(options: ResolveOptions): Promise<TXTResult | null>` - Get all TXT records parsed
- `getSpfRecord(options: ResolveOptions): Promise<SPF1Record | null>` - Get SPF record
- `getDkimRecord(options: ResolveOptions): Promise<DKIM1Record | null>` - Get DKIM record
- `getDmarcRecord(options: ResolveOptions): Promise<DMARC1Record | null>` - Get DMARC record
- `getStsRecord(options: ResolveOptions): Promise<STSv1Record | null>` - Get MTA-STS record
- `getCustomRecords(options: ResolveOptions): Promise<CustomRecord[] | null>` - Get custom TXT records
- `getCustomKVRecord(options: ResolveOptions, key: string): Promise<CustomKVRecord | null>` - Get specific key-value record
- `getAllKVRecords(options: ResolveOptions): Promise<CustomKVRecord[] | null>` - Get all key-value records
- `getNameServers(target: Target): Promise<string[]>` - Get authoritative name servers

### Address Class

#### Constructor

- `new Address(mailOrHost: string) - Create new Address instance`

```ts
import {Address } from "email-domain-check";
const addr_01 = new Address('user@gmail.com'); // string email or domain
const addr_02 = new Address('gmail.com'); 

```

#### Static Constructor Method

- `Address.loadFromTarget(target: string | URL | Address): Address` - Parse email/domain/URL

#### Properties

- `source: string` - Original input
- `hostname: string` - Domain name or IP
- `user?: string` - Email local part (if email)
- `ipKind: IPKind` - IP type (None, IPv4, IPv6)
- `isIP: boolean` - Is an IP address
- `isLocal: boolean` - Is local/private IP
- `hasPunycode: boolean` - Contains punycode

---
_Source: https://npm.io/package/email-domain-check · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._