@emailcheck/email-validator-js
Version:
Advanced email validation with MX records, SMTP verification, disposable email detection, batch processing, and caching. Production-ready with TypeScript support.
59 lines (58 loc) • 2.6 kB
TypeScript
/**
* SMTP mailbox probe.
*
* Walks `mxRecords` in priority order, then `ports` in the configured order.
* Returns the first attempt that yields a definitive answer (250 / 550 / 552 /
* 452); on indeterminate outcomes (timeouts, connection resets, EHLO failures,
* unrecognized responses), falls through to the next MX×port pair.
*
* Per-attempt dialogue:
* greeting → EHLO → MAIL FROM → RCPT TO real → RCPT TO probe → RSET
*
* The probe RCPT uses a guaranteed-nonexistent random local-part so we can
* detect catch-all MXes (Outlook / Yahoo / Office 365 / ProtonMail / many
* corporates accept every recipient at the MX layer and bounce later).
* When both real + probe return 250, `result.isCatchAll = true` and callers
* know the deliverability signal is unreliable but that the address syntax
* was at least accepted.
*
* The envelope (real RCPT + probe RCPT + RSET) is batched via PIPELINING
* (RFC 2920) when the MX advertises support — roughly halves wire-level
* latency. Tests can disable with `pipelining: 'never'` for deterministic
* `socket.write()` call counts.
*
* Every result carries a `metrics` block with `mxAttempts`, `portAttempts`,
* `mxHostsTried`, `mxHostUsed?`, `totalDurationMs` — useful for region-health
* dashboards and root-cause-analysis when probes go wrong.
*/
import type { SmtpVerificationResult, VerifyMailboxSMTPParams } from './types';
export interface ParsedDsn {
/** 2 = success, 4 = transient, 5 = permanent */
class: number;
/** 1 addressing, 2 mailbox, 3 mail-system, 4 network, 5 protocol, 6 message, 7 security/policy */
subject: number;
detail: number;
}
/**
* Parse an RFC 3463 enhanced status code at the start of an SMTP reply.
* Examples: "550 5.1.1 user unknown" → {5,1,1}; "421 4.7.0 try later" → {4,7,0}.
*/
export declare function parseDsn(reply: string): ParsedDsn | null;
/**
* Public entry point. Walks `mxRecords × ports` and returns the first
* definitive answer. Always:
* - iterates MX records on indeterminate outcomes (no flag)
* - runs the catch-all dual-probe (no flag)
* - populates `result.metrics` and `result.enhancedStatus`
*
* Opt-in only:
* - `captureTranscript: true` returns the wire transcript on the result
* - `pipelining: 'never'` disables PIPELINING for deterministic tests
* - `catchAllProbeLocal` overrides the random-local generator
*/
export declare function verifyMailboxSMTP(params: VerifyMailboxSMTPParams): Promise<{
smtpResult: SmtpVerificationResult;
cached: boolean;
port: number;
portCached: boolean;
}>;