@mailtester-ninja/client 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # MailTester Ninja for JavaScript and TypeScript
 
-Official client for the [MailTester Ninja](https://mailtester.ninja) email verification API. Check in real time whether an email address is valid and deliverable: each address is checked against the recipient's mail server, and nothing is stored.
+Official client for the [MailTester Ninja](https://mailtester.ninja) email verification API. Check in real time whether an email address is valid and deliverable: each address is checked against the recipient's mail server, and nothing is stored. With a paid key, `find` also looks up a person's work email from their name and company domain.
 
 - Zero dependencies, typed, ESM and CommonJS
 - Node.js 18+, Deno, Bun and browsers (CORS is open)
@@ -48,14 +48,32 @@ for await (const { email, result, error } of mt.verifyMany(['info@apple.com', 's
 }
 ```
 
+## Find a work email (paid key)
+
+`find` calls the Finder API: it tests the most common address formats one by one (first.last, flast, first, firstlast, first_last, f.last) and returns the first one the mail server accepts.
+
+```js
+const r = await mt.find('Jean-Pierre', 'De La Tour', 'example.com');
+if (r.found) console.log(r.email);       // an address the mail server just accepted
+else console.log(r.message, r.guess);    // e.g. "Catch-All" and the most common format
+console.log(r.permutations);             // formats tested, each one counted as a verification
+console.log(r.format, r.confidence);     // e.g. "flast" "medium": an initial, a namesake may share it
+```
+
+- Each format tested counts as one verification against your daily limit, even when nothing is found. The search paces itself within the rate of your key.
+- `confidence` tells how sure the address is to belong to this person: `high` when it holds the first and last name, `medium` with an initial, `low` with the first name only. `tested` lists every address checked, with its verdict.
+- On a catch-all domain nothing can be confirmed: `found` is `false` and `guess` holds the most common format.
+- Personal email providers such as gmail.com are not searched (`message` is `Webmail`).
+- A free key is refused with `MailTesterKeyError`; over the rate of your key, `MailTesterRateLimitError` carries `retryAfterSeconds`.
+
 ## Errors
 
 An error is never a verdict: do not drop an address because of it.
 
 | Error | When |
 |-------|------|
-| `MailTesterKeyError` | The key is invalid or disabled. |
-| `MailTesterRateLimitError` | A limit was reached (HTTP 429). `retryAfterSeconds` is set on the free tier. |
+| `MailTesterKeyError` | The key is invalid or disabled, or `find` was called with a free key. |
+| `MailTesterRateLimitError` | A limit was reached (HTTP 429). `retryAfterSeconds` is set on the free tier and by `find`. |
 | `MailTesterError` | Any other HTTP or network error (`status` when there is one). |
 
 ## Keys and limits

package/dist/index.cjs

@@ -30,7 +30,7 @@ __export(index_exports, {
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
-var VERSION = "1.0.0";
+var VERSION = "1.1.0";
 var DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
 var FREE_KEY = "free";
 var MailTesterError = class extends Error {
@@ -90,9 +90,7 @@ var MailTester = class {
   get isFree() {
     return this.key === FREE_KEY || this.key.startsWith("mtf_");
   }
-  /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
-  async verify(email) {
-    const url = `${this.baseUrl}/ninja?email=${encodeURIComponent(email.trim())}&key=${encodeURIComponent(this.key)}`;
+  async request(url) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     let res;
@@ -105,7 +103,11 @@ var MailTester = class {
       clearTimeout(timer);
     }
     const text = await res.text();
-    const body = parseJson(text);
+    return { res, text, body: parseJson(text) };
+  }
+  /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
+  async verify(email) {
+    const { res, text, body } = await this.request(`${this.baseUrl}/ninja?email=${encodeURIComponent(email.trim())}&key=${encodeURIComponent(this.key)}`);
     const message = typeof body?.message === "string" ? body.message : text.trim();
     if (res.status === 429) throw new MailTesterRateLimitError(message, retryAfter(message));
     if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
@@ -113,6 +115,30 @@ var MailTester = class {
     if (body.code === "--") throw new MailTesterKeyError(message, res.status);
     return body;
   }
+  /**
+   * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+   * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+   * and returns the first address the mail server accepts. Each format tested counts as one verification.
+   * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+   */
+  async find(first, last, domain) {
+    if (this.isFree) {
+      throw new MailTesterKeyError("The Finder API needs a paid key: https://mailtester.ninja/verify-emails-unlimited/", 403);
+    }
+    const qs = new URLSearchParams({ first: first.trim(), last: last.trim(), domain: domain.trim(), key: this.key });
+    const { res, text, body } = await this.request(`${this.baseUrl}/find?${qs}`);
+    const reason = typeof body?.reason === "string" && body.reason ? body.reason : void 0;
+    const message = reason ?? (typeof body?.message === "string" ? body.message : text.trim());
+    if (res.status === 429) {
+      const wait = Number(res.headers.get("retry-after"));
+      throw new MailTesterRateLimitError(message, Number.isFinite(wait) && wait > 0 ? wait : void 0);
+    }
+    if (res.status === 403 && body) throw new MailTesterKeyError(message, 403);
+    if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
+    if (!body) throw new MailTesterError("Unexpected response from the API", res.status);
+    if (body.code === "--") throw new MailTesterKeyError(message, res.status);
+    return body;
+  }
   /** True only when the address is clearly valid and deliverable (`code` "ok"). */
   async isDeliverable(email) {
     return (await this.verify(email)).code === "ok";

package/dist/index.d.cts

@@ -2,7 +2,7 @@
  * Official JavaScript and TypeScript client for the MailTester Ninja email verification API.
  * https://mailtester.ninja/api/
  */
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
 /** Keyless free tier: 10 checks a day per IP, one request every 30 seconds. */
 declare const FREE_KEY = "free";
@@ -27,6 +27,47 @@ interface VerificationResult {
     /** Requests made with the key over the last 10 seconds. */
     rate?: number;
 }
+/** Result of a Finder API search (`find`). Check `found` first. */
+interface FindResult {
+    /** `ok` found, `ko` not found, `mb` uncertain (catch-all domain, personal email provider, server not checked). */
+    code: Verdict;
+    /** Accepted, Rejected, Catch-All, Limited, No MX, Disposable, SPAM Block, Timeout, Webmail... */
+    message: string;
+    /** True when the mail server accepted one of the formats. */
+    found: boolean;
+    /** The address found, otherwise null. */
+    email: string | null;
+    /** Pattern of the returned address (email, or guess when not found): first.last, flast, first, firstlast, first_last or f.last. */
+    format: string | null;
+    /** For an address found: `high` (first and last name in it), `medium` (an initial, a namesake may share it), `low` (first name only). */
+    confidence: 'high' | 'medium' | 'low' | null;
+    /** Not verified: on a catch-all domain the most common format, for a full mailbox (Limited) that address. */
+    guess: string | null;
+    first: string;
+    last: string;
+    /** The normalised domain that was searched. */
+    domain: string;
+    /** Mail server used for the search. */
+    mx: string;
+    /** Address formats tested, each one counted as a verification, even when nothing is found. */
+    permutations: number;
+    /** Every address tested, in order, with its verdict. */
+    tested: {
+        email: string;
+        code: string;
+        message: string;
+    }[];
+    /** Simultaneous connections used by the key. */
+    connections?: number;
+    /** Daily limit of the key. */
+    limit?: number;
+    /** Verifications made with the key over the last 10 seconds, permutations included. */
+    rate?: number;
+    /** Seconds taken by the search. */
+    duration?: number;
+    /** Why nothing was found, in plain English. Null when found. */
+    reason: string | null;
+}
 interface MailTesterOptions {
     /**
      * `free` (no signup), a free token `mtf_...` from https://mailtester.ninja/free-email-verification-api/,
@@ -72,8 +113,16 @@ declare class MailTester {
     constructor(options?: MailTesterOptions | string);
     /** True on the free tier (`free` or a free token), limited to one request every 30 seconds. */
     get isFree(): boolean;
+    private request;
     /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
     verify(email: string): Promise<VerificationResult>;
+    /**
+     * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+     * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+     * and returns the first address the mail server accepts. Each format tested counts as one verification.
+     * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+     */
+    find(first: string, last: string, domain: string): Promise<FindResult>;
     /** True only when the address is clearly valid and deliverable (`code` "ok"). */
     isDeliverable(email: string): Promise<boolean>;
     /**
@@ -83,4 +132,4 @@ declare class MailTester {
     verifyMany(emails: Iterable<string> | AsyncIterable<string>, options?: VerifyManyOptions): AsyncGenerator<VerifyManyItem>;
 }
 
-export { DEFAULT_BASE_URL, FREE_KEY, MailTester, MailTesterError, MailTesterKeyError, type MailTesterOptions, MailTesterRateLimitError, VERSION, type Verdict, type VerificationResult, type VerifyManyItem, type VerifyManyOptions, MailTester as default };
+export { DEFAULT_BASE_URL, FREE_KEY, type FindResult, MailTester, MailTesterError, MailTesterKeyError, type MailTesterOptions, MailTesterRateLimitError, VERSION, type Verdict, type VerificationResult, type VerifyManyItem, type VerifyManyOptions, MailTester as default };

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * Official JavaScript and TypeScript client for the MailTester Ninja email verification API.
  * https://mailtester.ninja/api/
  */
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.1.0";
 declare const DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
 /** Keyless free tier: 10 checks a day per IP, one request every 30 seconds. */
 declare const FREE_KEY = "free";
@@ -27,6 +27,47 @@ interface VerificationResult {
     /** Requests made with the key over the last 10 seconds. */
     rate?: number;
 }
+/** Result of a Finder API search (`find`). Check `found` first. */
+interface FindResult {
+    /** `ok` found, `ko` not found, `mb` uncertain (catch-all domain, personal email provider, server not checked). */
+    code: Verdict;
+    /** Accepted, Rejected, Catch-All, Limited, No MX, Disposable, SPAM Block, Timeout, Webmail... */
+    message: string;
+    /** True when the mail server accepted one of the formats. */
+    found: boolean;
+    /** The address found, otherwise null. */
+    email: string | null;
+    /** Pattern of the returned address (email, or guess when not found): first.last, flast, first, firstlast, first_last or f.last. */
+    format: string | null;
+    /** For an address found: `high` (first and last name in it), `medium` (an initial, a namesake may share it), `low` (first name only). */
+    confidence: 'high' | 'medium' | 'low' | null;
+    /** Not verified: on a catch-all domain the most common format, for a full mailbox (Limited) that address. */
+    guess: string | null;
+    first: string;
+    last: string;
+    /** The normalised domain that was searched. */
+    domain: string;
+    /** Mail server used for the search. */
+    mx: string;
+    /** Address formats tested, each one counted as a verification, even when nothing is found. */
+    permutations: number;
+    /** Every address tested, in order, with its verdict. */
+    tested: {
+        email: string;
+        code: string;
+        message: string;
+    }[];
+    /** Simultaneous connections used by the key. */
+    connections?: number;
+    /** Daily limit of the key. */
+    limit?: number;
+    /** Verifications made with the key over the last 10 seconds, permutations included. */
+    rate?: number;
+    /** Seconds taken by the search. */
+    duration?: number;
+    /** Why nothing was found, in plain English. Null when found. */
+    reason: string | null;
+}
 interface MailTesterOptions {
     /**
      * `free` (no signup), a free token `mtf_...` from https://mailtester.ninja/free-email-verification-api/,
@@ -72,8 +113,16 @@ declare class MailTester {
     constructor(options?: MailTesterOptions | string);
     /** True on the free tier (`free` or a free token), limited to one request every 30 seconds. */
     get isFree(): boolean;
+    private request;
     /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
     verify(email: string): Promise<VerificationResult>;
+    /**
+     * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+     * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+     * and returns the first address the mail server accepts. Each format tested counts as one verification.
+     * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+     */
+    find(first: string, last: string, domain: string): Promise<FindResult>;
     /** True only when the address is clearly valid and deliverable (`code` "ok"). */
     isDeliverable(email: string): Promise<boolean>;
     /**
@@ -83,4 +132,4 @@ declare class MailTester {
     verifyMany(emails: Iterable<string> | AsyncIterable<string>, options?: VerifyManyOptions): AsyncGenerator<VerifyManyItem>;
 }
 
-export { DEFAULT_BASE_URL, FREE_KEY, MailTester, MailTesterError, MailTesterKeyError, type MailTesterOptions, MailTesterRateLimitError, VERSION, type Verdict, type VerificationResult, type VerifyManyItem, type VerifyManyOptions, MailTester as default };
+export { DEFAULT_BASE_URL, FREE_KEY, type FindResult, MailTester, MailTesterError, MailTesterKeyError, type MailTesterOptions, MailTesterRateLimitError, VERSION, type Verdict, type VerificationResult, type VerifyManyItem, type VerifyManyOptions, MailTester as default };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-var VERSION = "1.0.0";
+var VERSION = "1.1.0";
 var DEFAULT_BASE_URL = "https://happy.mailtester.ninja";
 var FREE_KEY = "free";
 var MailTesterError = class extends Error {
@@ -59,9 +59,7 @@ var MailTester = class {
   get isFree() {
     return this.key === FREE_KEY || this.key.startsWith("mtf_");
   }
-  /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
-  async verify(email) {
-    const url = `${this.baseUrl}/ninja?email=${encodeURIComponent(email.trim())}&key=${encodeURIComponent(this.key)}`;
+  async request(url) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     let res;
@@ -74,7 +72,11 @@ var MailTester = class {
       clearTimeout(timer);
     }
     const text = await res.text();
-    const body = parseJson(text);
+    return { res, text, body: parseJson(text) };
+  }
+  /** Verify one address. Resolves to a verdict, rejects with a MailTesterError when there is none. */
+  async verify(email) {
+    const { res, text, body } = await this.request(`${this.baseUrl}/ninja?email=${encodeURIComponent(email.trim())}&key=${encodeURIComponent(this.key)}`);
     const message = typeof body?.message === "string" ? body.message : text.trim();
     if (res.status === 429) throw new MailTesterRateLimitError(message, retryAfter(message));
     if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
@@ -82,6 +84,30 @@ var MailTester = class {
     if (body.code === "--") throw new MailTesterKeyError(message, res.status);
     return body;
   }
+  /**
+   * Find a work email address from a first name, a last name and a company domain (Finder API, paid key).
+   * The API tests the most common formats one by one (first.last, flast, first, firstlast, first_last, f.last)
+   * and returns the first address the mail server accepts. Each format tested counts as one verification.
+   * Resolves to a FindResult (check `found`), rejects with a MailTesterError when the search did not run.
+   */
+  async find(first, last, domain) {
+    if (this.isFree) {
+      throw new MailTesterKeyError("The Finder API needs a paid key: https://mailtester.ninja/verify-emails-unlimited/", 403);
+    }
+    const qs = new URLSearchParams({ first: first.trim(), last: last.trim(), domain: domain.trim(), key: this.key });
+    const { res, text, body } = await this.request(`${this.baseUrl}/find?${qs}`);
+    const reason = typeof body?.reason === "string" && body.reason ? body.reason : void 0;
+    const message = reason ?? (typeof body?.message === "string" ? body.message : text.trim());
+    if (res.status === 429) {
+      const wait = Number(res.headers.get("retry-after"));
+      throw new MailTesterRateLimitError(message, Number.isFinite(wait) && wait > 0 ? wait : void 0);
+    }
+    if (res.status === 403 && body) throw new MailTesterKeyError(message, 403);
+    if (!res.ok) throw new MailTesterError(message || `HTTP ${res.status}`, res.status);
+    if (!body) throw new MailTesterError("Unexpected response from the API", res.status);
+    if (body.code === "--") throw new MailTesterKeyError(message, res.status);
+    return body;
+  }
   /** True only when the address is clearly valid and deliverable (`code` "ok"). */
   async isDeliverable(email) {
     return (await this.verify(email)).code === "ok";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailtester-ninja/client",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Official client for the MailTester Ninja email verification API: check in real time if an email address is valid and deliverable.",
   "keywords": [
     "email",