@emailcheck/email-validator-js 5.0.0 → 5.1.0

package/README.md

@@ -268,6 +268,14 @@ Comprehensive email verification with detailed results and error codes.
   - `smtpMaxConsecutiveFailures` (number) — Bail after N connection-class failures in a row (`connection_error` / `connection_timeout` / `connection_closed`). Default: unbounded.
   - `smtpMaxMxHosts` (number) — Cap the MX walk to the first N hostnames. Default: unbounded.
   - `smtpRetry` (`{ attempts, delayMs?, backoff? }`) — Retry connection-class failures on the same MX × port. Default: no retries.
+- **SMTP envelope controls** (anti-spam — recommended for production):
+  - `smtpSender` (`SMTPSenderStrategy`) — Strategy for the `MAIL FROM:` envelope. The library default is `<recipient@domain>`, which blocklists key on as the textbook verification-probe fingerprint. Pick a deliberate strategy:
+    - `{ kind: 'null-sender' }` → `MAIL FROM:<>` (RFC 5321 §4.5.5; DSN-shaped, best on Gmail / Outlook).
+    - `{ kind: 'fixed', address: 'verify@your-domain.com' }` → fixed real address (best with valid SPF / PTR / DMARC).
+    - `{ kind: 'random-at-recipient', localPrefix? }` → random local-part on the recipient's domain.
+    - `{ kind: 'random-at-domain', domain, localPrefix? }` → random local-part on a configured domain.
+    - `{ kind: 'custom', build: r => ... }` → full escape hatch.
+  - `smtpHeloHostname` (string) — Hostname presented to the MX in `EHLO` / `HELO`. Default: `'localhost'` (a spam-bot signature from a public IP — override with a real FQDN in production).
 - `whoisTimeoutMs` (number) — Per-WHOIS-query timeout (default: `5000`).
 - `debug` (boolean) — Per-line `console.debug` trace (default: `false`).
 - `captureTranscript` (boolean) — Populate `result.transcript` with a per-step structured trace (default: `false`).
@@ -1133,10 +1141,38 @@ clearAllCaches();
 
 ## 💻 Command-line Tool (`email-validate`)
 
-`bun add -g @emailcheck/email-validator-js` (or the npm equivalent) installs an
-`email-validate` binary. It runs the full validation pipeline against one
-address, captures a structured transcript, prints the result to stdout, and
-saves the JSON result to `./logs/` by default.
+The package ships an `email-validate` binary that runs the full validation
+pipeline against one address, captures a structured transcript, prints the
+result to stdout, and saves the JSON result to `./logs/` by default.
+
+### Run without installing (npx / bunx / pnpm dlx)
+
+```bash
+# One-off check — pulls the latest published version, no install required
+npx -p @emailcheck/email-validator-js email-validate alice@example.com
+
+# Same with bunx / pnpm dlx
+bunx -p @emailcheck/email-validator-js email-validate alice@example.com
+pnpm dlx -p @emailcheck/email-validator-js email-validate alice@example.com
+
+# Pin a version (avoids npx caching surprises in CI)
+npx -p @emailcheck/email-validator-js@4.0.0 email-validate alice@example.com
+```
+
+> The `-p <package>` form is the safest because the bin name
+> (`email-validate`) differs from the package name. The shorthand
+> `npx @emailcheck/email-validator-js alice@example.com` also works since the
+> package has exactly one bin.
+
+### Install globally
+
+```bash
+bun add -g @emailcheck/email-validator-js
+# or: npm i -g @emailcheck/email-validator-js
+# or: pnpm add -g @emailcheck/email-validator-js
+```
+
+### Examples
 
 ```bash
 # Quick interactive check — full pipeline, pretty colored output

package/dist/cli/index.js

@@ -1015,6 +1015,31 @@ function detectNameFromEmail(params) {
   return defaultNameDetectionMethod(email);
 }
 
+const DEFAULT_LOCAL_PREFIX = "probe";
+function resolveSenderAddress(strategy, recipient) {
+  switch (strategy.kind) {
+    case "null-sender":
+      return "<>";
+    case "fixed":
+      return wrap(strategy.address);
+    case "random-at-recipient":
+      return wrap(`${randomLocal(strategy.localPrefix)}@${recipient.domain}`);
+    case "random-at-domain":
+      return wrap(`${randomLocal(strategy.localPrefix)}@${strategy.domain}`);
+    case "custom":
+      return strategy.build({ local: recipient.local, domain: recipient.domain });
+  }
+}
+function wrap(address) {
+  if (address.startsWith("<") && address.endsWith(">")) return address;
+  return `<${address}>`;
+}
+function randomLocal(prefix) {
+  const random = node_crypto.randomBytes(8).toString("hex");
+  const safePrefix = prefix ?? DEFAULT_LOCAL_PREFIX;
+  return `${safePrefix}-${random}`;
+}
+
 const DEFAULT_PORTS = [25, 587, 465];
 const DEFAULT_TIMEOUT_MS = 3e3;
 const QUIT_DRAIN_MS = 100;
@@ -1058,6 +1083,7 @@ async function verifyMailboxSMTP(params) {
   const debug = options.debug ?? false;
   const captureTranscript = options.captureTranscript ?? false;
   const sequence = options.sequence;
+  const sender = options.sender;
   const cache = options.cache;
   const log = debug ? (...args) => console.log("[SMTP]", ...args) : () => {
   };
@@ -1084,6 +1110,7 @@ async function verifyMailboxSMTP(params) {
     tlsConfig,
     heloHostname,
     sequence,
+    sender,
     log,
     catchAllProbeLocal: options.catchAllProbeLocal,
     pipelining: options.pipelining ?? "auto",
@@ -1354,7 +1381,7 @@ class SMTPProbeConnection {
         this.executeStartTls();
         return;
       case SMTPStep.mailFrom: {
-        const from = this.p.sequence?.from ?? `<${this.p.local}@${this.p.domain}>`;
+        const from = this.p.sender ? resolveSenderAddress(this.p.sender, { local: this.p.local, domain: this.p.domain }) : this.p.sequence?.from ?? `<${this.p.local}@${this.p.domain}>`;
         this.send(`MAIL FROM:${from}`);
         return;
       }
@@ -2471,7 +2498,12 @@ async function runSmtp(local, domain, mxRecords, params, result, log, collector)
             debug: params.debug ?? false,
             // Forward transcript capture so the SMTP step's details include
             // the full per-port transcript when the caller asked for it.
-            captureTranscript: params.captureTranscript ?? false
+            captureTranscript: params.captureTranscript ?? false,
+            // Forward the high-level envelope strategy and HELO override so
+            // callers can control the spam-fingerprint of the probe without
+            // dropping down to `verifyMailboxSMTP` directly.
+            ...params.smtpSender !== void 0 && { sender: params.smtpSender },
+            ...params.smtpHeloHostname !== void 0 && { heloHostname: params.smtpHeloHostname }
           }
         });
         await smtpCache.set(cacheKey, probe.smtpResult);