@mails-expert/sdk

Official Node.js and TypeScript SDK for the mails.expert API.

mails.expert helps you verify email addresses before you send campaigns, onboard users, clean old databases, or sync contacts from external tools. It is useful when you need to reduce bounces, protect sender reputation, remove invalid or risky addresses, and automate email quality checks directly from your backend or scripts.

This SDK is designed to make the API easy to use from Node.js and TypeScript projects. Instead of manually building HTTP requests, headers, and polling logic, you get a typed client for single-email verification, bulk jobs, exports, account operations, API tokens, and Mailchimp integration.

Site: https://mails.expert/

Why use this SDK

• Typed responses for the main mails.expert API endpoints
• Simple client setup with API token or JWT
• Built-in helpers for bulk verification polling
• Easy export of results as csv, txt, or xlsx
• Support for account workflows such as API tokens and Mailchimp import
• Clean integration path for Node.js automation, CRON jobs, internal tools, and SaaS backends

Requirements

• Node.js 18+
• A mails.expert account
• A valid mails.expert API token or JWT

You can create and manage tokens in your mails.expert dashboard.

Installation

npm install @mails-expert/sdk

Quick start

import { MailsExpertClient } from "@mails-expert/sdk";

const client = new MailsExpertClient({
  apiKey: process.env.MAILS_EXPERT_API_KEY!,
  baseUrl: "https://api.mails.expert"
});

Authentication

The SDK uses Bearer authentication under the hood.

You can pass:

• a mails.expert API token such as mv_xxxxxxxxxx
• or a JWT issued by the platform

Example:

const client = new MailsExpertClient({
  apiKey: "mv_xxxxxxxxxxxxxxxxxxxxxxxxx"
});

Basic usage

Verify a single email

Use this when you need to check one address during signup, import validation, or internal workflows.

const result = await client.verifyEmail("[email protected]");

console.log(result.email);
console.log(result.result);
console.log(result.deliverability_score);
console.log(result.checks.smtpStatus);

Typical things you may inspect:

• result.result
• result.deliverability_score
• result.bounce_risk
• result.domain_health
• result.checks.isDisposable
• result.checks.isRole
• result.checks.isBlacklisted
• result.smtp_message

Start a bulk verification job

Use bulk verification when you already have a list of emails and want the API to process them asynchronously.

const bulk = await client.startBulkVerification([
  "[email protected]",
  "[email protected]",
  "[email protected]"
]);

console.log(bulk.jobId);
console.log(bulk.queued);
console.log(bulk.skipped);

Check bulk progress

const progress = await client.getBulkProgress(bulk.jobId);

console.log(progress.status);
console.log(progress.processed, progress.total);
console.log(progress.progress_percent);

Get bulk results

const results = await client.getBulkResults(bulk.jobId, {
  page: 1,
  limit: 100
});

console.log(results.results);

Wait until a bulk job is complete

If you do not want to implement your own polling logic, use waitForBulkCompletion.

const completed = await client.waitForBulkCompletion(bulk.jobId, {
  pollIntervalMs: 3000,
  timeoutMs: 5 * 60_000,
  page: 1,
  limit: 100
});

console.log(completed.status);
console.log(completed.results);

Export verification results

You can export account results as csv, txt, or xlsx.

The SDK returns a Uint8Array, which you can save directly to disk in Node.js.

import { writeFile } from "node:fs/promises";

const file = await client.exportResults("csv", {
  result: ["valid", "risky"]
});

await writeFile("results.csv", file);

Common workflows

1. Verify emails before sending

const emails = [
  "[email protected]",
  "[email protected]",
  "[email protected]"
];

const job = await client.startBulkVerification(emails);
const finalResults = await client.waitForBulkCompletion(job.jobId);

const safeToSend = finalResults.results.filter(
  (item) => item.result === "valid" || item.result === "risky"
);

console.log(safeToSend.length);

2. Check account balance before starting a job

const balance = await client.getBalance();

console.log(balance.token_balance);
console.log(balance.token_price_usd);

3. List historical results from your account

const history = await client.listResults({
  page: 1,
  limit: 20,
  result: ["valid", "risky"],
  sort: "checked_at",
  order: "desc"
});

console.log(history.total);
console.log(history.data);

4. Import contacts from Mailchimp and verify them

await client.connectMailchimp(process.env.MAILCHIMP_API_KEY!);

const audiences = await client.listMailchimpAudiences();
const firstAudience = audiences.audiences[0];

const imported = await client.importMailchimpAudience({
  audienceId: firstAudience.id,
  status: "subscribed",
  limit: 1000
});

console.log(imported.jobId);
console.log(imported.audience_name);
console.log(imported.imported_count);

API overview

Verification

• verifyEmail(email)
• startBulkVerification(emails)
• getBulkProgress(jobId)
• getBulkResults(jobId, { page, limit })
• waitForBulkCompletion(jobId, { pollIntervalMs, timeoutMs, page, limit })

Profile and account

• getProfile()
• changePassword(currentPassword, newPassword)
• deleteAccount(password)

Balance and transactions

• getBalance()
• getTransactions({ page, limit })

Results

• listResults(filters)
• getResultStats(filters)
• getResultFilterOptions()
• exportResults(format, filters)
• deleteResults(ids)
• deleteAllResults(filters)

Bulk jobs

• listJobs({ activeOnly })
• deleteJob(jobId)

API tokens

• listApiTokens()
• createApiToken(name)
• revealApiToken(tokenId)
• updateApiTokenName(tokenId, name)
• revokeApiToken(tokenId)

Mailchimp integration

• getMailchimpStatus()
• connectMailchimp(apiKey)
• disconnectMailchimp()
• listMailchimpAudiences()
• importMailchimpAudience({ audienceId, status, limit })

Error handling

The SDK throws MailsExpertApiError for API-level failures.

import { MailsExpertApiError } from "@mails-expert/sdk";

try {
  const result = await client.verifyEmail("[email protected]");
  console.log(result);
} catch (error) {
  if (error instanceof MailsExpertApiError) {
    console.error(error.status);
    console.error(error.message);
    console.error(error.details);
  } else {
    console.error(error);
  }
}

Client options

apiKey

Required. Your mails.expert API token or JWT.

baseUrl

Optional. Defaults to:

"https://api.mails.expert"

Useful if you want to point the SDK to a local, staging, or self-hosted API endpoint.

fetchImpl

Optional. Lets you provide a custom fetch implementation.

Useful for:

• testing
• custom instrumentation
• non-standard runtimes

Example:

const client = new MailsExpertClient({
  apiKey: process.env.MAILS_EXPERT_API_KEY!,
  fetchImpl: fetch
});

Example: full script

import { MailsExpertClient } from "@mails-expert/sdk";

const client = new MailsExpertClient({
  apiKey: process.env.MAILS_EXPERT_API_KEY!,
  baseUrl: "https://api.mails.expert"
});

async function main() {
  const balance = await client.getBalance();
  console.log("Current balance:", balance.token_balance);

  const bulk = await client.startBulkVerification([
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]);

  console.log("Started job:", bulk.jobId);

  const done = await client.waitForBulkCompletion(bulk.jobId, {
    pollIntervalMs: 3000,
    timeoutMs: 120_000
  });

  for (const row of done.results) {
    console.log(row.email, row.result);
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});

About mails.expert

mails.expert is an email verification platform focused on improving deliverability and list quality. It helps teams and products detect invalid, risky, disposable, role-based, blacklisted, and catch-all email addresses before they damage sender reputation or waste acquisition and outreach budgets.

If you need to:

• clean email lists before campaigns
• validate users during signup
• automate verification in internal workflows
• import audiences from external tools such as Mailchimp
• export and analyze verification history

this SDK gives you a direct TypeScript-first way to integrate the platform.