@emailsherlock/node 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +30 -2
- package/dist/index.d.ts +1 -1
- package/dist/types.d.ts +50 -2
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @emailsherlock/node
|
|
2
2
|
|
|
3
|
-
Official Node.js client for the [EmailSherlock](https://emailsherlock.com) email-verification API. Verify one address or a batch over HTTPS with an API key.
|
|
3
|
+
Official Node.js client for the [EmailSherlock](https://emailsherlock.com) email-verification API. Verify one address or a batch over HTTPS with an API key. Get an API key at https://emailsherlock.com/api. Want to try a single address by hand first? The free [email verification](https://emailsherlock.com/verify) tool runs the same checks in the browser.
|
|
4
4
|
|
|
5
5
|
Zero dependencies. Works on Node 18+ (uses the built-in `fetch`).
|
|
6
6
|
|
|
@@ -65,8 +65,36 @@ for (const item of results) {
|
|
|
65
65
|
| `disposable` | boolean | throwaway / temporary-mail provider |
|
|
66
66
|
| `role` | boolean | role address such as `info@` or `sales@` |
|
|
67
67
|
| `catch_all` | boolean | host accepts mail for any local part |
|
|
68
|
-
| `score` | number
|
|
68
|
+
| `score` | number / null | 0–1 confidence, higher is safer to send to (`null` when the verdict is `unknown`) |
|
|
69
69
|
| `freshness` | string | `fresh` · `cached_recent` · `cached_stale_refreshed` |
|
|
70
|
+
| `deliverable`| boolean / null | SMTP-proven: `true` only after an SMTP accept, `false` only on a provable failure, `null` when unproven |
|
|
71
|
+
| `reason` | string / null | why the verdict came out the way it did, e.g. `mailbox_accepts` · `mailbox_not_found` · `no_mx` · `bad_syntax` · `disposable_provider` · `role_address` · `catch_all_domain` · `greylisted` · `smtp_timeout` · `smtp_unreachable` · `verification_pending` |
|
|
72
|
+
| `mx_record` | string / null | the primary MX host for the domain |
|
|
73
|
+
| `free_email` | boolean / null | the address belongs to a free webmail provider |
|
|
74
|
+
| `checked_at` | string / null | when the check ran, ISO 8601 |
|
|
75
|
+
| `domain` | object / null | domain-level intelligence, see below |
|
|
76
|
+
|
|
77
|
+
The fields from `deliverable` down are additive and may be missing until the
|
|
78
|
+
API rollout completes; once present they are always set but nullable.
|
|
79
|
+
|
|
80
|
+
### The domain object
|
|
81
|
+
|
|
82
|
+
| field | type | meaning |
|
|
83
|
+
|----------------|-----------|----------------------------------------------------------|
|
|
84
|
+
| `name` | string | the domain part of the address |
|
|
85
|
+
| `types` | string[] / null | host types: `freemail` · `disposable` · `custom` · `company` · `government` · `education` · `public` · `isp` |
|
|
86
|
+
| `score` | number / null | domain trust score, 0-100, higher is better |
|
|
87
|
+
| `spf` | boolean / null | the domain publishes an SPF record |
|
|
88
|
+
| `dkim` | boolean / null | the domain publishes at least one DKIM key |
|
|
89
|
+
| `dmarc` | boolean / null | the domain publishes a DMARC record |
|
|
90
|
+
| `dmarc_policy` | string / null | `none` · `quarantine` · `reject` |
|
|
91
|
+
| `mta_sts` | boolean / null | the domain publishes an MTA-STS policy |
|
|
92
|
+
| `tls_rpt` | boolean / null | the domain publishes a TLS-RPT record |
|
|
93
|
+
| `bimi` | boolean / null | the domain publishes a BIMI record |
|
|
94
|
+
| `dane` | boolean / null | the MX hosts publish DANE/TLSA records |
|
|
95
|
+
| `blacklists` | number / null | DNS blacklists currently listing the domain's mail IPs |
|
|
96
|
+
| `dnssec` | string / null | `secure` · `insecure` · `bogus` |
|
|
97
|
+
| `caa` | boolean / null | the domain publishes a CAA record |
|
|
70
98
|
|
|
71
99
|
## Credits and rate limits
|
|
72
100
|
|
package/dist/index.d.ts
CHANGED
|
@@ -3,6 +3,6 @@ export type { ClientOptions } from './client.js';
|
|
|
3
3
|
export { VERSION } from './version.js';
|
|
4
4
|
export { EmailsherlockError, AuthenticationError, ForbiddenError, InsufficientCreditsError, RateLimitError, ValidationError, ServiceUnavailableError, } from './errors.js';
|
|
5
5
|
export { isVerifyResult, } from './types.js';
|
|
6
|
-
export type { VerifyResult, VerifyVerdict, Freshness, BatchItem, BatchItemError, BatchResponse, RateLimit, } from './types.js';
|
|
6
|
+
export type { VerifyResult, VerifyVerdict, VerifyReason, VerifyDomain, Freshness, BatchItem, BatchItemError, BatchResponse, RateLimit, } from './types.js';
|
|
7
7
|
import { Emailsherlock } from './client.js';
|
|
8
8
|
export default Emailsherlock;
|
package/dist/types.d.ts
CHANGED
|
@@ -2,6 +2,39 @@
|
|
|
2
2
|
export type VerifyVerdict = 'valid' | 'invalid' | 'catch_all' | 'disposable' | 'role' | 'unknown';
|
|
3
3
|
/** How recent the underlying data is. Mirrors the API `freshness` enum. */
|
|
4
4
|
export type Freshness = 'fresh' | 'cached_recent' | 'cached_stale_refreshed';
|
|
5
|
+
/** Why the verdict came out the way it did. Mirrors the API `reason` enum. */
|
|
6
|
+
export type VerifyReason = 'bad_syntax' | 'no_mx' | 'mailbox_accepts' | 'mailbox_not_found' | 'disposable_provider' | 'role_address' | 'catch_all_domain' | 'greylisted' | 'smtp_timeout' | 'smtp_unreachable' | 'verification_pending';
|
|
7
|
+
/** Domain-level intelligence for the verified address. Mirrors the wire JSON. */
|
|
8
|
+
export interface VerifyDomain {
|
|
9
|
+
/** The domain part of the address. */
|
|
10
|
+
name: string;
|
|
11
|
+
/** Host types such as freemail, disposable, custom, company, government, education, public, isp. */
|
|
12
|
+
types: string[] | null;
|
|
13
|
+
/** Domain trust score, 0-100, higher is better. */
|
|
14
|
+
score: number | null;
|
|
15
|
+
/** The domain publishes an SPF record. */
|
|
16
|
+
spf: boolean | null;
|
|
17
|
+
/** The domain publishes at least one DKIM key. */
|
|
18
|
+
dkim: boolean | null;
|
|
19
|
+
/** The domain publishes a DMARC record. */
|
|
20
|
+
dmarc: boolean | null;
|
|
21
|
+
/** none · quarantine · reject */
|
|
22
|
+
dmarc_policy: 'none' | 'quarantine' | 'reject' | null;
|
|
23
|
+
/** The domain publishes an MTA-STS policy. */
|
|
24
|
+
mta_sts: boolean | null;
|
|
25
|
+
/** The domain publishes a TLS-RPT record. */
|
|
26
|
+
tls_rpt: boolean | null;
|
|
27
|
+
/** The domain publishes a BIMI record. */
|
|
28
|
+
bimi: boolean | null;
|
|
29
|
+
/** The MX hosts publish DANE/TLSA records. */
|
|
30
|
+
dane: boolean | null;
|
|
31
|
+
/** Number of DNS blacklists currently listing the domain's mail IPs. */
|
|
32
|
+
blacklists: number | null;
|
|
33
|
+
/** secure · insecure · bogus */
|
|
34
|
+
dnssec: 'secure' | 'insecure' | 'bogus' | null;
|
|
35
|
+
/** The domain publishes a CAA record. */
|
|
36
|
+
caa: boolean | null;
|
|
37
|
+
}
|
|
5
38
|
/** The result object returned for a verified address. Mirrors the wire JSON. */
|
|
6
39
|
export interface VerifyResult {
|
|
7
40
|
/** The address that was checked. */
|
|
@@ -16,10 +49,25 @@ export interface VerifyResult {
|
|
|
16
49
|
role: boolean;
|
|
17
50
|
/** Host accepts mail for any local part. */
|
|
18
51
|
catch_all: boolean;
|
|
19
|
-
/** 0–1 confidence, higher is safer to send to. */
|
|
20
|
-
score: number;
|
|
52
|
+
/** 0–1 confidence, higher is safer to send to. Null when the verdict is unknown. */
|
|
53
|
+
score: number | null;
|
|
21
54
|
/** fresh · cached_recent · cached_stale_refreshed */
|
|
22
55
|
freshness: Freshness;
|
|
56
|
+
/**
|
|
57
|
+
* SMTP-proven deliverability: true only after an SMTP accept, false only on
|
|
58
|
+
* a provable failure, null when unproven. Missing on older API versions.
|
|
59
|
+
*/
|
|
60
|
+
deliverable?: boolean | null;
|
|
61
|
+
/** Why the verdict came out the way it did. Missing on older API versions. */
|
|
62
|
+
reason?: VerifyReason | null;
|
|
63
|
+
/** The primary MX host for the domain. Missing on older API versions. */
|
|
64
|
+
mx_record?: string | null;
|
|
65
|
+
/** The address belongs to a free webmail provider. Missing on older API versions. */
|
|
66
|
+
free_email?: boolean | null;
|
|
67
|
+
/** When the check ran, ISO 8601. Missing on older API versions. */
|
|
68
|
+
checked_at?: string | null;
|
|
69
|
+
/** Domain-level intelligence. Missing on older API versions. */
|
|
70
|
+
domain?: VerifyDomain | null;
|
|
23
71
|
}
|
|
24
72
|
/** A per-address failure inside a batch response. */
|
|
25
73
|
export interface BatchItemError {
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const VERSION = "0.
|
|
1
|
+
export declare const VERSION = "0.2.0";
|
package/dist/version.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export const VERSION = '0.
|
|
1
|
+
export const VERSION = '0.2.0';
|