Mailfloss Node.js SDK

Official Node.js/TypeScript SDK for the Mailfloss email verification API.

• Zero runtime dependencies (uses global fetch, Node.js >= 18)
• Fully typed request params and responses, hand-derived from the OpenAPI spec
• Automatic retries on 429/5xx (honors Retry-After) and network errors
• Automatic Idempotency-Key on every POST

Installation

npm install @mailfloss/sdk

Authentication

Grab an API key from your Mailfloss dashboard, then either pass it directly:

import { Mailfloss } from "@mailfloss/sdk";

const mailfloss = new Mailfloss({ apiKey: "mf_rk_..." });

or set the MAILFLOSS_API_KEY environment variable and construct with no arguments:

export MAILFLOSS_API_KEY="mf_rk_..."

const mailfloss = new Mailfloss();

The key is sent as Authorization: Bearer <key>. If no key is found, the constructor throws a MailflossConfigError.

Quickstart

Verify a single email (GET /v1/verify)

import { Mailfloss } from "@mailfloss/sdk";

const mailfloss = new Mailfloss();

const result = await mailfloss.verify({ email: "jane@acme.com" });

console.log(result.status);   // "passed" | "undeliverable" | "risky" | "unknown"
console.log(result.passed);   // true when safe to send
console.log(result.reason);   // e.g. "available"
console.log(result.suggestion); // typo fix suggestion, when available

Batch verification (POST /v1/batch-verify)

const { id } = await mailfloss.batchVerify.create({
  emails: ["jane@acme.com", "bob@example.com"],
  webhook_url: "https://example.com/hooks/mailfloss", // optional; omit to poll
});

// Poll for progress...
const { status, progress } = await mailfloss.batchVerify.status(id);

// ...then page through the results.
const page = await mailfloss.batchVerify.results(id, { per_page: 100 });
console.log(page.results);

Client options

const mailfloss = new Mailfloss({
  apiKey: "mf_rk_...",          // default: process.env.MAILFLOSS_API_KEY
  baseUrl: "https://api.mailfloss.com/v1", // default
  maxRetries: 3,                 // retries on 429/5xx/network errors
  timeoutMs: 30_000,             // per-request timeout (no timeout by default)
  fetch: customFetch,            // injectable fetch (for testing/proxies)
});

Resources

Resource	Methods
mailfloss.verify(params)	Real-time single verification
mailfloss.batchVerify	create, status(id), results(id, params?), cancel(id)
mailfloss.jobs	list(params?), get(id)
mailfloss.users	list(params?), get(userId)
mailfloss.reports	usage(params?)
mailfloss.checkKey(params?)	Validate an API key
mailfloss.account	get(), update(params)
mailfloss.organization	get()
mailfloss.integrations	list(params?), get(type)
mailfloss.integrations.connections	create(type, params), get(type, id), update(type, id, params), delete(type, id), sync(type, id), test(type, id)
mailfloss.integrations.keywords	list(type, id, list, params?), add(type, id, list, params), delete(type, id, list, ruleId)
mailfloss.erasures	create(params)

List endpoints return a typed { data, pagination } envelope; pass pagination.next_cursor back as cursor to fetch the next page.

Idempotency

Every POST automatically includes an Idempotency-Key header (UUID v4). To control it yourself, pass it per call:

await mailfloss.batchVerify.create(
  { emails: ["jane@acme.com"] },
  { idempotencyKey: "order-1234-verification" }, // gitleaks:allow — docs example, not a secret
);

Error handling

Non-2xx responses throw a MailflossError:

import { MailflossError } from "@mailfloss/sdk";

try {
  await mailfloss.verify({ email: "jane@acme.com" });
} catch (err) {
  if (err instanceof MailflossError) {
    console.error(err.status);    // e.g. 401
    console.error(err.code);      // stable machine-readable code
    console.error(err.type);      // e.g. "authentication_error"
    console.error(err.message);   // human-readable message
    console.error(err.requestId); // X-Request-Id echo, for support
  }
}

Rate limits (429) and server errors (5xx) are retried automatically with exponential backoff and full jitter, honoring the Retry-After header when present.

License

MIT — see LICENSE.