mailproof/README.md

A lightweight and efficient email validation library that checks email format, MX records, and SMTP response.

# MailProof

MailProof is a powerful email validation library that checks email addresses for correct format, valid MX records, and SMTP server response. It also filters out disposable email addresses to enhance your email verification process.

## Features

- **Format Validation**: Ensures the email follows the correct syntax.
- **MX Record Check**: Verifies that the domain has valid mail exchange (MX) records.
- **SMTP Verification**: Attempts to establish an SMTP connection to confirm the recipient exists.
- **Disposable Email Filtering**: Detects and blocks disposable email addresses.
- **Customizable DNS Servers & Timeout**: Allows configuration of DNS servers and request timeouts.

## Installation

You can install MailProof via npm:

```sh
npm install mailproof
```

or using Yarn:

```sh
yarn add mailproof
```

## Usage

```typescript
import EmailValidator from "mailproof";

const validator = new EmailValidator({
  checkMX: true,
  checkSMTP: true,
  timeout: 10000,
  dnsServers: ["1.1.1.1", "8.8.8.8"],
  smtpFrom: "singhalutkarsh26@gmail.com",
});

(async () => {
  const result = await validator.validate("test@example.com");
  console.log(result);
})();
```

## Configuration Options

| Option     | Type     | Required | Default Value            | Description                  |
| ---------- | -------- | -------- | ------------------------ | ---------------------------- |
| smtpFrom   | string   | Required | -                        | Sender email for SMTP check. |
| checkMX    | boolean  | Optional | `true`                   | Check for valid MX records.  |
| checkSMTP  | boolean  | Optional | `true`                   | Verify SMTP response.        |
| timeout    | number   | Optional | `10000` (10s)            | Timeout for SMTP checks.     |
| dnsServers | string[] | Optional | `["1.1.1.1", "8.8.8.8"]` | DNS servers for MX lookup.   |

### Important Configuration Notes

- The `smtpFrom` parameter is **required** and must be provided when creating an instance of EmailValidator.
- All other parameters are optional and will use their default values if not specified.
- If `checkSMTP` is set to `true`, `checkMX` must also be set to `true`. Otherwise, an error will be thrown.

Examples of valid configurations:

```typescript
// Minimal configuration with only required fields
const minimalValidator = new EmailValidator({
  smtpFrom: "singhalutkarsh26@gmail.com",
  // All other options will use defaults
});

// Full validation with all checks
const fullValidator = new EmailValidator({
  checkMX: true,
  checkSMTP: true,
  timeout: 15000, // Custom timeout
  dnsServers: ["1.1.1.1", "9.9.9.9"], // Custom DNS servers
  smtpFrom: "singhalutkarsh26@gmail.com",
});

// Only MX check, no SMTP check
const mxOnlyValidator = new EmailValidator({
  checkMX: true,
  checkSMTP: false,
  smtpFrom: "singhalutkarsh26@gmail.com",
});

// No DNS checks, just format and disposable domain validation
const basicValidator = new EmailValidator({
  checkMX: false,
  checkSMTP: false,
  smtpFrom: "singhalutkarsh26@gmail.com",
});

// Invalid configuration - will throw an error
try {
  const invalidValidator = new EmailValidator({
    checkMX: false,
    checkSMTP: true, // ERROR: Cannot enable SMTP check without MX check
    smtpFrom: "singhalutkarsh26@gmail.com",
  });
} catch (error) {
  console.error(error.message); // "checkSMTP requires checkMX to be true. Please enable checkMX or disable checkSMTP."
}
```

## Validation Result

The `validate` method returns a Promise that resolves to an object:

```typescript
interface ValidationResult {
  valid: boolean; // True if email is valid
  errors: string[]; // List of validation errors (if any)
}
```

### Possible Validation Errors

Depending on your configuration and the email being validated, these are the possible errors you might receive:

| Error Message                 | Description                                           |
| ----------------------------- | ----------------------------------------------------- |
| "Invalid email format"        | The email does not match the required format pattern. |
| "Invalid email domain"        | The email domain part is missing or invalid.          |
| "Disposable email domain"     | The email uses a known disposable email service.      |
| "No MX records found"         | No MX records exist for the email domain.             |
| "MX record validation failed" | The MX record check encountered an error.             |
| "SMTP validation failed"      | The email address was rejected during SMTP check.     |
| "SMTP verification error"     | The SMTP check encountered an error.                  |

### Example Responses:

**Valid Email:**

```json
{
  "valid": true,
  "errors": []
}
```

**Format Error:**

```json
{
  "valid": false,
  "errors": ["Invalid email format"]
}
```

**Multiple Validation Errors:**

```json
{
  "valid": false,
  "errors": ["Disposable email domain", "SMTP validation failed"]
}
```

**MX Record Error:**

```json
{
  "valid": false,
  "errors": ["No MX records found"]
}
```

## Performance Considerations

- **Format Validation**: Fast, performed synchronously.
- **Disposable Domain Check**: Relies on a pre-loaded list, relatively fast.
- **MX Record Check**: Requires DNS lookup, moderately fast.
- **SMTP Verification**: Most time-consuming, involves establishing a connection.

For high-volume systems, consider disabling SMTP checks and only using format validation, disposable domain filtering, and MX checks.

## Author

Developed by [Utkarsh Singhal](https://utkarsh-singhal.is-a.dev/).

## License

MIT