@emailsherlock/node 0.2.1 → 0.3.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 +47 -29
- package/dist/client.d.ts +26 -12
- package/dist/client.js +75 -55
- package/dist/errors.d.ts +8 -10
- package/dist/errors.js +37 -2
- package/dist/generated/apis/AccountApi.d.ts +30 -0
- package/dist/generated/apis/AccountApi.js +51 -0
- package/dist/generated/apis/GuardApi.d.ts +33 -0
- package/dist/generated/apis/GuardApi.js +55 -0
- package/dist/generated/apis/VerifyApi.d.ts +84 -0
- package/dist/generated/apis/VerifyApi.js +172 -0
- package/dist/generated/apis/index.d.ts +3 -0
- package/dist/generated/apis/index.js +5 -0
- package/dist/generated/index.d.ts +3 -0
- package/dist/generated/index.js +5 -0
- package/dist/generated/models/index.d.ts +574 -0
- package/dist/generated/models/index.js +87 -0
- package/dist/generated/runtime.d.ts +181 -0
- package/dist/generated/runtime.js +341 -0
- package/dist/index.d.ts +4 -3
- package/dist/index.js +2 -2
- package/dist/types.d.ts +8 -82
- package/dist/types.js +5 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -67,34 +67,52 @@ for (const item of results) {
|
|
|
67
67
|
| `catch_all` | boolean | host accepts mail for any local part |
|
|
68
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
|
|
71
|
-
| `reason` | string
|
|
72
|
-
| `mx_record` | string
|
|
73
|
-
| `free_email` | boolean
|
|
74
|
-
| `checked_at` | string
|
|
75
|
-
| `domain` | object
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
70
|
+
| `deliverable`| boolean? | proven via SMTP: `true` accepted, `false` provably bad, `null` unproven |
|
|
71
|
+
| `reason` | string? | why the pipeline decided (`mailbox_accepts`, `greylisted`, …) |
|
|
72
|
+
| `mx_record` | string? | the primary MX host, when one was resolved |
|
|
73
|
+
| `free_email` | boolean? | the domain is a freemail provider |
|
|
74
|
+
| `checked_at` | string? | when the verification ran (ISO 8601) |
|
|
75
|
+
| `domain` | object? | domain-level intelligence (SPF, DKIM, DMARC, score, blacklists, …) |
|
|
76
|
+
| `decision` | object | `{ recommendation: allow·deny·review, reasons[] }` |
|
|
77
|
+
|
|
78
|
+
Every field and model type is generated from the [OpenAPI spec](https://www.hostsherlock.com/api/docs) and exported, so your editor autocompletes the full shape.
|
|
79
|
+
|
|
80
|
+
## Async jobs
|
|
81
|
+
|
|
82
|
+
For large lists, submit a job and poll it. Every address runs the full pipeline
|
|
83
|
+
including the SMTP probe, so the results carry definitive inbox verdicts:
|
|
84
|
+
|
|
85
|
+
```js
|
|
86
|
+
const job = await es.verify.submitJob({ emails: ['a@acme.com', 'b@acme.com'] });
|
|
87
|
+
|
|
88
|
+
let status = job;
|
|
89
|
+
while (status.status !== 'completed') {
|
|
90
|
+
await new Promise((r) => setTimeout(r, 2000));
|
|
91
|
+
status = await es.verify.getJob(job.id);
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
console.log(status.results);
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Account status
|
|
98
|
+
|
|
99
|
+
```js
|
|
100
|
+
const account = await es.credits();
|
|
101
|
+
account.credits.total; // spendable credits
|
|
102
|
+
account.rateLimit; // { limit, remaining, reset }
|
|
103
|
+
account.sandbox; // true on an es_test_ key
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Email-Guard events
|
|
107
|
+
|
|
108
|
+
Record Email-Guard decision events (free, no credits). The full address is never
|
|
109
|
+
sent, only the domain:
|
|
110
|
+
|
|
111
|
+
```js
|
|
112
|
+
await es.guard.recordEvents([
|
|
113
|
+
{ domain: 'mailinator.com', verdict: 'disposable', action: 'deny', reasons: ['disposable_provider'], degraded: false, source: 'local' },
|
|
114
|
+
]);
|
|
115
|
+
```
|
|
98
116
|
|
|
99
117
|
## Credits and rate limits
|
|
100
118
|
|
|
@@ -115,7 +133,7 @@ Every failure throws a subclass of `EmailsherlockError`:
|
|
|
115
133
|
| `ForbiddenError` | 403 | key lacks the endpoint's scope (`requiredScope`) |
|
|
116
134
|
| `InsufficientCreditsError` | 402 | not enough credits (`creditsRequired`, `creditsRemaining`) |
|
|
117
135
|
| `RateLimitError` | 429 | rate limit hit (`retryAfter`, `limit`, `remaining`, `reset`) |
|
|
118
|
-
| `ValidationError` | 400 / 422 | the request
|
|
136
|
+
| `ValidationError` | 400 / 404 / 422 | the request was rejected, or the job was not found |
|
|
119
137
|
| `ServiceUnavailableError` | 503 | verify engine unavailable (the credit is auto-refunded) |
|
|
120
138
|
|
|
121
139
|
```js
|
package/dist/client.d.ts
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
import
|
|
1
|
+
import { VerifyApi, GuardApi } from './generated/index.js';
|
|
2
|
+
import type { VerifyResultResponse, VerifyBatchResponse, VerifyJobResponse, AccountStatusResponse, GuardEventsRequest } from './generated/index.js';
|
|
3
|
+
import type { RateLimit } from './types.js';
|
|
2
4
|
export interface ClientOptions {
|
|
3
5
|
/** Your API key. Falls back to ES_KEY / EMAILSHERLOCK_API_KEY in the env. */
|
|
4
6
|
apiKey?: string;
|
|
@@ -11,29 +13,41 @@ export interface ClientOptions {
|
|
|
11
13
|
}
|
|
12
14
|
/** Verify-endpoint methods, reached as `client.verify`. */
|
|
13
15
|
export declare class VerifyResource {
|
|
14
|
-
private readonly
|
|
15
|
-
constructor(
|
|
16
|
+
private readonly api;
|
|
17
|
+
constructor(api: VerifyApi);
|
|
16
18
|
/** Verify a single address. */
|
|
17
19
|
single(params: {
|
|
18
20
|
email: string;
|
|
19
|
-
}): Promise<
|
|
20
|
-
/** Verify
|
|
21
|
+
}): Promise<VerifyResultResponse>;
|
|
22
|
+
/** Verify a batch of addresses in one call. */
|
|
21
23
|
batch(params: {
|
|
22
24
|
emails: string[];
|
|
23
|
-
}): Promise<
|
|
25
|
+
}): Promise<VerifyBatchResponse>;
|
|
26
|
+
/** Submit a list of addresses for asynchronous verification. Poll with `getJob`. */
|
|
27
|
+
submitJob(params: {
|
|
28
|
+
emails: string[];
|
|
29
|
+
}): Promise<VerifyJobResponse>;
|
|
30
|
+
/** Read the status and results of a verification job. */
|
|
31
|
+
getJob(id: string): Promise<VerifyJobResponse>;
|
|
32
|
+
}
|
|
33
|
+
/** Email-Guard event methods, reached as `client.guard`. */
|
|
34
|
+
export declare class GuardResource {
|
|
35
|
+
private readonly api;
|
|
36
|
+
constructor(api: GuardApi);
|
|
37
|
+
/** Record a batch of Email-Guard decision events (free, no credits). */
|
|
38
|
+
recordEvents(events: GuardEventsRequest['events']): Promise<void>;
|
|
24
39
|
}
|
|
25
40
|
export declare class Emailsherlock {
|
|
26
41
|
readonly verify: VerifyResource;
|
|
42
|
+
readonly guard: GuardResource;
|
|
27
43
|
/** Credits left after the most recent request (from X-Credits-Remaining). */
|
|
28
44
|
creditsRemaining: number | null;
|
|
29
45
|
/** Rate-limit window after the most recent request (from X-RateLimit-*). */
|
|
30
46
|
rateLimit: RateLimit;
|
|
31
|
-
private readonly
|
|
32
|
-
private readonly baseUrl;
|
|
33
|
-
private readonly timeoutMs;
|
|
34
|
-
private readonly fetchImpl;
|
|
47
|
+
private readonly account;
|
|
35
48
|
constructor(apiKey?: string | ClientOptions, options?: ClientOptions);
|
|
36
|
-
/**
|
|
37
|
-
|
|
49
|
+
/** Read the credit balance and rate-limit status. Free: consumes no credits. */
|
|
50
|
+
credits(): Promise<AccountStatusResponse>;
|
|
51
|
+
private withTimeout;
|
|
38
52
|
private captureMeta;
|
|
39
53
|
}
|
package/dist/client.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
+
import { Configuration, VerifyApi, AccountApi, GuardApi, } from './generated/index.js';
|
|
1
2
|
import { VERSION } from './version.js';
|
|
2
|
-
import {
|
|
3
|
+
import { EmailsherlockError, toEmailsherlockError } from './errors.js';
|
|
3
4
|
const DEFAULT_BASE_URL = 'https://api.emailsherlock.com';
|
|
4
5
|
function num(value) {
|
|
5
6
|
if (value === null)
|
|
@@ -7,88 +8,107 @@ function num(value) {
|
|
|
7
8
|
const n = Number(value);
|
|
8
9
|
return Number.isFinite(n) ? n : null;
|
|
9
10
|
}
|
|
10
|
-
|
|
11
|
+
/** Run a generated-client call, mapping any failure to a named error. */
|
|
12
|
+
async function call(fn) {
|
|
11
13
|
try {
|
|
12
|
-
return
|
|
14
|
+
return await fn();
|
|
13
15
|
}
|
|
14
|
-
catch {
|
|
15
|
-
|
|
16
|
+
catch (err) {
|
|
17
|
+
throw await toEmailsherlockError(err);
|
|
16
18
|
}
|
|
17
19
|
}
|
|
18
20
|
/** Verify-endpoint methods, reached as `client.verify`. */
|
|
19
21
|
export class VerifyResource {
|
|
20
|
-
|
|
21
|
-
constructor(
|
|
22
|
-
this.
|
|
22
|
+
api;
|
|
23
|
+
constructor(api) {
|
|
24
|
+
this.api = api;
|
|
23
25
|
}
|
|
24
26
|
/** Verify a single address. */
|
|
25
27
|
single(params) {
|
|
26
|
-
return this.
|
|
28
|
+
return call(() => this.api.verifySingle({ verifySingleRequest: { email: params.email } }));
|
|
27
29
|
}
|
|
28
|
-
/** Verify
|
|
30
|
+
/** Verify a batch of addresses in one call. */
|
|
29
31
|
batch(params) {
|
|
30
|
-
return this.
|
|
32
|
+
return call(() => this.api.verifyBatch({ verifyBatchRequest: { emails: params.emails } }));
|
|
33
|
+
}
|
|
34
|
+
/** Submit a list of addresses for asynchronous verification. Poll with `getJob`. */
|
|
35
|
+
submitJob(params) {
|
|
36
|
+
return call(() => this.api.submitVerifyJob({ verifyJobRequest: { emails: params.emails } }));
|
|
37
|
+
}
|
|
38
|
+
/** Read the status and results of a verification job. */
|
|
39
|
+
getJob(id) {
|
|
40
|
+
return call(() => this.api.getVerifyJob({ id }));
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
/** Email-Guard event methods, reached as `client.guard`. */
|
|
44
|
+
export class GuardResource {
|
|
45
|
+
api;
|
|
46
|
+
constructor(api) {
|
|
47
|
+
this.api = api;
|
|
48
|
+
}
|
|
49
|
+
/** Record a batch of Email-Guard decision events (free, no credits). */
|
|
50
|
+
recordEvents(events) {
|
|
51
|
+
return call(() => this.api.recordGuardEvents({ guardEventsRequest: { events } }));
|
|
31
52
|
}
|
|
32
53
|
}
|
|
33
54
|
export class Emailsherlock {
|
|
34
55
|
verify;
|
|
56
|
+
guard;
|
|
35
57
|
/** Credits left after the most recent request (from X-Credits-Remaining). */
|
|
36
58
|
creditsRemaining = null;
|
|
37
59
|
/** Rate-limit window after the most recent request (from X-RateLimit-*). */
|
|
38
60
|
rateLimit = { limit: null, remaining: null, reset: null };
|
|
39
|
-
|
|
40
|
-
baseUrl;
|
|
41
|
-
timeoutMs;
|
|
42
|
-
fetchImpl;
|
|
61
|
+
account;
|
|
43
62
|
constructor(apiKey, options = {}) {
|
|
44
63
|
const opts = typeof apiKey === 'string' ? { ...options, apiKey } : (apiKey ?? {});
|
|
45
64
|
const key = opts.apiKey ?? process.env.ES_KEY ?? process.env.EMAILSHERLOCK_API_KEY;
|
|
46
65
|
if (!key) {
|
|
47
66
|
throw new EmailsherlockError('No API key provided. Pass it to the constructor or set ES_KEY.', { code: 'config_error' });
|
|
48
67
|
}
|
|
49
|
-
const
|
|
50
|
-
if (!
|
|
68
|
+
const baseFetch = opts.fetch ?? globalThis.fetch;
|
|
69
|
+
if (!baseFetch) {
|
|
51
70
|
throw new EmailsherlockError('No fetch implementation available. Use Node 18+ or pass options.fetch.', { code: 'config_error' });
|
|
52
71
|
}
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
72
|
+
const timeoutMs = opts.timeoutMs ?? 30_000;
|
|
73
|
+
// Capture credit + rate-limit headers off every response, success or error.
|
|
74
|
+
const captureMeta = {
|
|
75
|
+
post: async (context) => {
|
|
76
|
+
this.captureMeta(context.response.headers);
|
|
77
|
+
},
|
|
78
|
+
};
|
|
79
|
+
const configuration = new Configuration({
|
|
80
|
+
basePath: (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ''),
|
|
81
|
+
apiKey: key, // sets the X-API-Key header for ApiKeyAuth
|
|
82
|
+
headers: { 'User-Agent': `emailsherlock-node/${VERSION}` },
|
|
83
|
+
fetchApi: this.withTimeout(baseFetch, timeoutMs),
|
|
84
|
+
middleware: [captureMeta],
|
|
85
|
+
});
|
|
86
|
+
this.verify = new VerifyResource(new VerifyApi(configuration));
|
|
87
|
+
this.guard = new GuardResource(new GuardApi(configuration));
|
|
88
|
+
this.account = new AccountApi(configuration);
|
|
58
89
|
}
|
|
59
|
-
/**
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
}
|
|
82
|
-
finally {
|
|
83
|
-
clearTimeout(timer);
|
|
84
|
-
}
|
|
85
|
-
this.captureMeta(res.headers);
|
|
86
|
-
const text = await res.text();
|
|
87
|
-
const json = text ? safeParse(text) : null;
|
|
88
|
-
if (!res.ok) {
|
|
89
|
-
throw errorFromResponse(res.status, json, res.headers);
|
|
90
|
-
}
|
|
91
|
-
return json;
|
|
90
|
+
/** Read the credit balance and rate-limit status. Free: consumes no credits. */
|
|
91
|
+
credits() {
|
|
92
|
+
return call(() => this.account.getCredits());
|
|
93
|
+
}
|
|
94
|
+
withTimeout(baseFetch, timeoutMs) {
|
|
95
|
+
return async (input, init) => {
|
|
96
|
+
const controller = new AbortController();
|
|
97
|
+
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
98
|
+
const upstream = init?.signal;
|
|
99
|
+
if (upstream) {
|
|
100
|
+
if (upstream.aborted)
|
|
101
|
+
controller.abort();
|
|
102
|
+
else
|
|
103
|
+
upstream.addEventListener('abort', () => controller.abort(), { once: true });
|
|
104
|
+
}
|
|
105
|
+
try {
|
|
106
|
+
return await baseFetch(input, { ...init, signal: controller.signal });
|
|
107
|
+
}
|
|
108
|
+
finally {
|
|
109
|
+
clearTimeout(timer);
|
|
110
|
+
}
|
|
111
|
+
};
|
|
92
112
|
}
|
|
93
113
|
captureMeta(headers) {
|
|
94
114
|
const credits = headers.get('X-Credits-Remaining');
|
package/dist/errors.d.ts
CHANGED
|
@@ -1,10 +1,3 @@
|
|
|
1
|
-
interface ApiErrorEnvelope {
|
|
2
|
-
error?: {
|
|
3
|
-
code?: string;
|
|
4
|
-
message?: string;
|
|
5
|
-
required_scope?: string;
|
|
6
|
-
};
|
|
7
|
-
}
|
|
8
1
|
export interface ErrorOptions {
|
|
9
2
|
status?: number;
|
|
10
3
|
code?: string;
|
|
@@ -34,11 +27,16 @@ export declare class RateLimitError extends EmailsherlockError {
|
|
|
34
27
|
remaining?: number | null;
|
|
35
28
|
reset?: number | null;
|
|
36
29
|
}
|
|
37
|
-
/** 400 / 422 — the request
|
|
30
|
+
/** 400 / 404 / 422 — the request was rejected. */
|
|
38
31
|
export declare class ValidationError extends EmailsherlockError {
|
|
39
32
|
}
|
|
40
33
|
/** 503 — the verify engine could not answer; the credit was auto-refunded. */
|
|
41
34
|
export declare class ServiceUnavailableError extends EmailsherlockError {
|
|
42
35
|
}
|
|
43
|
-
|
|
44
|
-
|
|
36
|
+
/**
|
|
37
|
+
* Map a thrown value from the generated runtime to one of our named errors.
|
|
38
|
+
* The runtime throws `ResponseError` (carries the `Response`) for non-2xx and
|
|
39
|
+
* `FetchError` for transport failures. Anything else is rewrapped so callers
|
|
40
|
+
* only ever catch `EmailsherlockError`.
|
|
41
|
+
*/
|
|
42
|
+
export declare function toEmailsherlockError(err: unknown): Promise<EmailsherlockError>;
|
package/dist/errors.js
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { ResponseError, FetchError } from './generated/runtime.js';
|
|
1
2
|
function num(value) {
|
|
2
3
|
if (value === null)
|
|
3
4
|
return null;
|
|
@@ -35,13 +36,21 @@ export class RateLimitError extends EmailsherlockError {
|
|
|
35
36
|
remaining;
|
|
36
37
|
reset;
|
|
37
38
|
}
|
|
38
|
-
/** 400 / 422 — the request
|
|
39
|
+
/** 400 / 404 / 422 — the request was rejected. */
|
|
39
40
|
export class ValidationError extends EmailsherlockError {
|
|
40
41
|
}
|
|
41
42
|
/** 503 — the verify engine could not answer; the credit was auto-refunded. */
|
|
42
43
|
export class ServiceUnavailableError extends EmailsherlockError {
|
|
43
44
|
}
|
|
44
|
-
|
|
45
|
+
async function safeJson(response) {
|
|
46
|
+
try {
|
|
47
|
+
return (await response.clone().json());
|
|
48
|
+
}
|
|
49
|
+
catch {
|
|
50
|
+
return null;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
function fromStatus(status, body, headers) {
|
|
45
54
|
const envelope = body?.error ?? {};
|
|
46
55
|
const code = envelope.code;
|
|
47
56
|
const message = envelope.message ?? `HTTP ${status}`;
|
|
@@ -69,6 +78,7 @@ export function errorFromResponse(status, body, headers) {
|
|
|
69
78
|
return err;
|
|
70
79
|
}
|
|
71
80
|
case 400:
|
|
81
|
+
case 404:
|
|
72
82
|
case 422:
|
|
73
83
|
return new ValidationError(message, opts);
|
|
74
84
|
case 503:
|
|
@@ -77,3 +87,28 @@ export function errorFromResponse(status, body, headers) {
|
|
|
77
87
|
return new EmailsherlockError(message, opts);
|
|
78
88
|
}
|
|
79
89
|
}
|
|
90
|
+
/**
|
|
91
|
+
* Map a thrown value from the generated runtime to one of our named errors.
|
|
92
|
+
* The runtime throws `ResponseError` (carries the `Response`) for non-2xx and
|
|
93
|
+
* `FetchError` for transport failures. Anything else is rewrapped so callers
|
|
94
|
+
* only ever catch `EmailsherlockError`.
|
|
95
|
+
*/
|
|
96
|
+
export async function toEmailsherlockError(err) {
|
|
97
|
+
if (err instanceof EmailsherlockError) {
|
|
98
|
+
return err;
|
|
99
|
+
}
|
|
100
|
+
if (err instanceof ResponseError) {
|
|
101
|
+
const { response } = err;
|
|
102
|
+
const body = await safeJson(response);
|
|
103
|
+
return fromStatus(response.status, body, response.headers);
|
|
104
|
+
}
|
|
105
|
+
if (err instanceof FetchError) {
|
|
106
|
+
const reason = err.cause instanceof Error ? err.cause.message : String(err.cause);
|
|
107
|
+
return new EmailsherlockError(`Request failed: ${reason}`, { code: 'network_error' });
|
|
108
|
+
}
|
|
109
|
+
if (err instanceof Error && err.name === 'AbortError') {
|
|
110
|
+
return new EmailsherlockError('Request timed out.', { code: 'timeout' });
|
|
111
|
+
}
|
|
112
|
+
const reason = err instanceof Error ? err.message : String(err);
|
|
113
|
+
return new EmailsherlockError(reason, { code: 'unknown_error' });
|
|
114
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* EmailSherlock API
|
|
3
|
+
* Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
|
|
4
|
+
*
|
|
5
|
+
* The version of the OpenAPI document: 1.0.0
|
|
6
|
+
*
|
|
7
|
+
*
|
|
8
|
+
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
|
|
9
|
+
* https://openapi-generator.tech
|
|
10
|
+
* Do not edit the class manually.
|
|
11
|
+
*/
|
|
12
|
+
import * as runtime from '../runtime.js';
|
|
13
|
+
import type { AccountStatusResponse } from '../models/index.js';
|
|
14
|
+
/**
|
|
15
|
+
*
|
|
16
|
+
*/
|
|
17
|
+
export declare class AccountApi extends runtime.BaseAPI {
|
|
18
|
+
/**
|
|
19
|
+
* Creates request options for getCredits without sending the request
|
|
20
|
+
*/
|
|
21
|
+
getCreditsRequestOpts(): Promise<runtime.RequestOpts>;
|
|
22
|
+
/**
|
|
23
|
+
* Read the credit balance and rate-limit status. Free: consumes no credits.
|
|
24
|
+
*/
|
|
25
|
+
getCreditsRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<AccountStatusResponse>>;
|
|
26
|
+
/**
|
|
27
|
+
* Read the credit balance and rate-limit status. Free: consumes no credits.
|
|
28
|
+
*/
|
|
29
|
+
getCredits(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<AccountStatusResponse>;
|
|
30
|
+
}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
/* tslint:disable */
|
|
2
|
+
/* eslint-disable */
|
|
3
|
+
/**
|
|
4
|
+
* EmailSherlock API
|
|
5
|
+
* Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
|
|
6
|
+
*
|
|
7
|
+
* The version of the OpenAPI document: 1.0.0
|
|
8
|
+
*
|
|
9
|
+
*
|
|
10
|
+
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
|
|
11
|
+
* https://openapi-generator.tech
|
|
12
|
+
* Do not edit the class manually.
|
|
13
|
+
*/
|
|
14
|
+
import * as runtime from '../runtime.js';
|
|
15
|
+
/**
|
|
16
|
+
*
|
|
17
|
+
*/
|
|
18
|
+
export class AccountApi extends runtime.BaseAPI {
|
|
19
|
+
/**
|
|
20
|
+
* Creates request options for getCredits without sending the request
|
|
21
|
+
*/
|
|
22
|
+
async getCreditsRequestOpts() {
|
|
23
|
+
const queryParameters = {};
|
|
24
|
+
const headerParameters = {};
|
|
25
|
+
if (this.configuration && this.configuration.apiKey) {
|
|
26
|
+
headerParameters["X-API-Key"] = await this.configuration.apiKey("X-API-Key"); // ApiKeyAuth authentication
|
|
27
|
+
}
|
|
28
|
+
let urlPath = `/v1/credits`;
|
|
29
|
+
return {
|
|
30
|
+
path: urlPath,
|
|
31
|
+
method: 'GET',
|
|
32
|
+
headers: headerParameters,
|
|
33
|
+
query: queryParameters,
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Read the credit balance and rate-limit status. Free: consumes no credits.
|
|
38
|
+
*/
|
|
39
|
+
async getCreditsRaw(initOverrides) {
|
|
40
|
+
const requestOptions = await this.getCreditsRequestOpts();
|
|
41
|
+
const response = await this.request(requestOptions, initOverrides);
|
|
42
|
+
return new runtime.JSONApiResponse(response);
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Read the credit balance and rate-limit status. Free: consumes no credits.
|
|
46
|
+
*/
|
|
47
|
+
async getCredits(initOverrides) {
|
|
48
|
+
const response = await this.getCreditsRaw(initOverrides);
|
|
49
|
+
return await response.value();
|
|
50
|
+
}
|
|
51
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* EmailSherlock API
|
|
3
|
+
* Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
|
|
4
|
+
*
|
|
5
|
+
* The version of the OpenAPI document: 1.0.0
|
|
6
|
+
*
|
|
7
|
+
*
|
|
8
|
+
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
|
|
9
|
+
* https://openapi-generator.tech
|
|
10
|
+
* Do not edit the class manually.
|
|
11
|
+
*/
|
|
12
|
+
import * as runtime from '../runtime.js';
|
|
13
|
+
import type { GuardEventsRequest } from '../models/index.js';
|
|
14
|
+
export interface RecordGuardEventsRequest {
|
|
15
|
+
guardEventsRequest: GuardEventsRequest;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
*
|
|
19
|
+
*/
|
|
20
|
+
export declare class GuardApi extends runtime.BaseAPI {
|
|
21
|
+
/**
|
|
22
|
+
* Creates request options for recordGuardEvents without sending the request
|
|
23
|
+
*/
|
|
24
|
+
recordGuardEventsRequestOpts(requestParameters: RecordGuardEventsRequest): Promise<runtime.RequestOpts>;
|
|
25
|
+
/**
|
|
26
|
+
* Record a batch of Email-Guard decision events (free).
|
|
27
|
+
*/
|
|
28
|
+
recordGuardEventsRaw(requestParameters: RecordGuardEventsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
|
|
29
|
+
/**
|
|
30
|
+
* Record a batch of Email-Guard decision events (free).
|
|
31
|
+
*/
|
|
32
|
+
recordGuardEvents(requestParameters: RecordGuardEventsRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;
|
|
33
|
+
}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/* tslint:disable */
|
|
2
|
+
/* eslint-disable */
|
|
3
|
+
/**
|
|
4
|
+
* EmailSherlock API
|
|
5
|
+
* Verify one email address or a batch over HTTPS with an API key. Authenticate with the X-API-Key header. Billing is user-level credits; each call returns the remaining balance in the X-Credits-Remaining header. Sandbox: a key that starts with es_test_ runs in sandbox mode. It returns deterministic fixtured data on the same endpoints and response shape, never spends credits, and marks every response with X-Sandbox: true. The local part drives the verdict so you can test each branch: valid@, invalid@, catch-all@, disposable@, role@, unknown@ and pending@ pin a result (pending@ yields reason verification_pending, the deferred-batch outcome to retry later); ratelimit@ returns 429 and servererror@ returns 503 so you can exercise error handling. On the async jobs endpoint (POST /v1/verify/jobs), put async@ or slowjob@ in the batch and the sandbox reproduces the real submit-poll-complete lifecycle: the submit returns processing and the job completes after a few seconds, so you can build and test your polling loop before going live; without it, sandbox jobs complete immediately. Any other address maps to a stable result. Live keys start with es_live_. Full reference at https://emailsherlock.com/api/docs
|
|
6
|
+
*
|
|
7
|
+
* The version of the OpenAPI document: 1.0.0
|
|
8
|
+
*
|
|
9
|
+
*
|
|
10
|
+
* NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
|
|
11
|
+
* https://openapi-generator.tech
|
|
12
|
+
* Do not edit the class manually.
|
|
13
|
+
*/
|
|
14
|
+
import * as runtime from '../runtime.js';
|
|
15
|
+
/**
|
|
16
|
+
*
|
|
17
|
+
*/
|
|
18
|
+
export class GuardApi extends runtime.BaseAPI {
|
|
19
|
+
/**
|
|
20
|
+
* Creates request options for recordGuardEvents without sending the request
|
|
21
|
+
*/
|
|
22
|
+
async recordGuardEventsRequestOpts(requestParameters) {
|
|
23
|
+
if (requestParameters['guardEventsRequest'] == null) {
|
|
24
|
+
throw new runtime.RequiredError('guardEventsRequest', 'Required parameter "guardEventsRequest" was null or undefined when calling recordGuardEvents().');
|
|
25
|
+
}
|
|
26
|
+
const queryParameters = {};
|
|
27
|
+
const headerParameters = {};
|
|
28
|
+
headerParameters['Content-Type'] = 'application/json';
|
|
29
|
+
if (this.configuration && this.configuration.apiKey) {
|
|
30
|
+
headerParameters["X-API-Key"] = await this.configuration.apiKey("X-API-Key"); // ApiKeyAuth authentication
|
|
31
|
+
}
|
|
32
|
+
let urlPath = `/v1/guard/events`;
|
|
33
|
+
return {
|
|
34
|
+
path: urlPath,
|
|
35
|
+
method: 'POST',
|
|
36
|
+
headers: headerParameters,
|
|
37
|
+
query: queryParameters,
|
|
38
|
+
body: requestParameters['guardEventsRequest'],
|
|
39
|
+
};
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Record a batch of Email-Guard decision events (free).
|
|
43
|
+
*/
|
|
44
|
+
async recordGuardEventsRaw(requestParameters, initOverrides) {
|
|
45
|
+
const requestOptions = await this.recordGuardEventsRequestOpts(requestParameters);
|
|
46
|
+
const response = await this.request(requestOptions, initOverrides);
|
|
47
|
+
return new runtime.VoidApiResponse(response);
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* Record a batch of Email-Guard decision events (free).
|
|
51
|
+
*/
|
|
52
|
+
async recordGuardEvents(requestParameters, initOverrides) {
|
|
53
|
+
await this.recordGuardEventsRaw(requestParameters, initOverrides);
|
|
54
|
+
}
|
|
55
|
+
}
|