# mailintel

> Email domain intelligence. Give it an email address or a domain and it returns the mail provider plus exact IMAP and SMTP connection settings. Zero dependencies, runs anywhere `fetch` exists, including the browser.

mailintel is an open-source (MIT) TypeScript library and CLI. It resolves MX records over DNS-over-HTTPS, matches them against ~30 provider patterns, falls back to Thunderbird's ISPDB, and maps the result to connection settings. Known domains resolve from a built-in map with zero network requests.

## When to use it

- Autofill IMAP/SMTP settings during mailbox onboarding instead of asking users for server details.
- Detect whether a contact is on Google Workspace, Microsoft 365, Zoho or a regional host.
- Flag domains on a curated temporary-email list (a heuristic, not mailbox verification).
- Build mail client, CRM, helpdesk or migration tooling that needs to connect to arbitrary mailboxes.
- Give an AI agent a reliable way to find mail server settings without scraping support pages.

## Install

```bash
npm install mailintel
```

## Usage

```ts
import { mailintel } from "mailintel";

const result = await mailintel("ceo@acme.dev");

result.provider;              // "google"
result.providerDisplayName;   // "Google Workspace"
result.type;                  // "business" | "free" | "unknown"
result.confidence;            // "high" | "medium" | "low"
result.connection.imap;       // { host: "imap.gmail.com", port: 993, security: "tls" }
result.connection.smtp;       // { host: "smtp.gmail.com", port: 465, security: "tls" }
result.connection.username;   // "ceo@acme.dev"
```

Accepts an array for batch lookups. Accepts a bare domain (`acme.dev`) and returns the username template (`%EMAILADDRESS%`) instead of a resolved username.

## HTTP API

Free, no key, CORS enabled, 60 requests per minute per IP.

```
GET https://mailintel.atef.dev/api/lookup?q=ceo@acme.dev
```

Returns `{ result, meta }`. `meta.disposable` is a heuristic from a curated temporary-email domain list. OpenAPI spec: https://mailintel.atef.dev/openapi.json

## CLI

```bash
npx mailintel ceo@acme.dev
npx mailintel acme.dev --json
```

## Result status

- `ok` — connection settings found.
- `no-mx-records` — the domain cannot receive mail.
- `unknown-provider` — mail servers exist but no IMAP/SMTP mapping is known.
- `lookup-disabled` — network lookups were disabled.

`connection` is `null` unless status is `ok`.

## Caveats

- Microsoft 365 requires OAuth2 for IMAP/SMTP; basic auth is disabled for Exchange Online. Business tenants use `outlook.office365.com` / `smtp.office365.com`.
- Google Workspace ended password-only IMAP/SMTP access on March 14, 2025; OAuth is required, with app passwords as an exception where enabled.
- Zoho Mail uses regional hosts; match the MX (`mx.zoho.eu` → `imappro.zoho.eu`). The site and API refine this automatically.
- Google, Yahoo, iCloud, Fastmail and Yandex require app passwords when 2FA is enabled.
- Proton Mail has no hosted IMAP/SMTP; it requires the local Proton Mail Bridge (127.0.0.1:1143 / 1025).
- The library resolves settings, not credentials. Host and port alone do not authenticate a mailbox.

## Links

- Website and playground: https://mailintel.atef.dev
- Provider directory: https://mailintel.atef.dev/providers
- Temporary email checker: https://mailintel.atef.dev/temporary-email-checker
- Documentation: https://mailintel.atef.dev/docs
- Privacy: https://mailintel.atef.dev/privacy
- npm: https://www.npmjs.com/package/mailintel
- GitHub: https://github.com/AhmedAtef07/mailintel
- License: MIT
- Author: Ahmed Atef (https://atef.dev)