Official Node.js / TypeScript client library for the EvilMail disposable email API

Installation • Quick Start • API Reference • Error Handling • Documentation

The EvilMail Node.js SDK provides a modern, fully-typed TypeScript interface for integrating temporary email, disposable email addresses, email verification code extraction, inbox management, and custom domain email services into your Node.js applications. Zero runtime dependencies — built entirely on node:https and the Node.js standard library.

• Zero Dependencies — No runtime dependencies, built on node:https only
• Full TypeScript — Strict mode, complete type definitions, source maps, declaration maps
• ESM + CommonJS — Dual-package output with proper exports map for both module systems
• Temporary Email — Create anonymous disposable email addresses with configurable TTL
• Email Verification Codes — Auto-extract OTP codes from Google, Facebook, Instagram, TikTok, Discord, Twitter, LinkedIn, iCloud
• Account Management — Full CRUD for persistent email accounts on custom domains
• Inbox Access — Read emails, list messages, fetch full HTML & plain text content
• Random Email Generator — Batch create random email accounts with auto-generated passwords
• Domain Management — List free, premium, and custom email domains
• Shortlink Creation — Generate short URLs for temporary email sessions
• AbortSignal Support — Cancel any in-flight request using native AbortController
• Typed Errors — Granular error classes with instanceof checks and predicate helpers
• Keep-Alive — Efficient HTTP connection reuse via Node.js agent

• Node.js 18 or later
• An EvilMail API key — Get yours free

npm install evilmail

yarn add evilmail

pnpm add evilmail

import { EvilMail } from 'evilmail';

const client = new EvilMail('your-api-key');

// Create a temporary disposable email address
const temp = await client.tempEmail.create({ domain: 'evilmail.pro', ttlMinutes: 60 });
console.log(`Email: ${temp.email}`);
console.log(`Token: ${temp.sessionToken}`);

// Check session status
const session = await client.tempEmail.getSession(temp.sessionToken);
console.log(`Expires: ${session.expiresAt}`);

// Read a specific message from temp inbox
const message = await client.tempEmail.getMessage(temp.sessionToken, 1);
console.log(`Subject: ${message.subject}`);

// Extract a Google verification code
const code = await client.verification.getCode('google', '[email protected]');
console.log(`OTP Code: ${code.code}`);

// List all email accounts
const accounts = await client.accounts.list();
for (const acct of accounts) {
  console.log(`${acct.email} (${acct.domain})`);
}

// Batch create random email accounts
const batch = await client.randomEmail.createBatch({
  domain: 'yourdomain.com',
  count: 5,
  passwordLength: 20,
});
for (const entry of batch.emails) {
  console.log(`${entry.email}: ${entry.password}`);
}

// Clean up
await client.tempEmail.delete(temp.sessionToken);

const { EvilMail } = require('evilmail');

const client = new EvilMail('your-api-key');

async function main() {
  const temp = await client.tempEmail.create({ ttlMinutes: 30 });
  console.log(temp.email);
}

main();

import { EvilMail } from 'evilmail';

// Basic
const client = new EvilMail('your-api-key');

// Custom settings
const client = new EvilMail('your-api-key', {
  baseUrl: 'https://evilmail.pro',  // default
  timeout: 60_000,                   // milliseconds, default 30_000
});

// With AbortController for cancellation
const controller = new AbortController();
const client = new EvilMail('your-api-key', {
  signal: controller.signal,
});

// Cancel all in-flight requests
controller.abort();

Create anonymous, disposable email addresses with automatic expiration. Perfect for sign-up verification, automated testing, and privacy protection.

Create a new temporary email address.

Returns: Promise<TempEmailSession> — email, domain, sessionToken, ttlMinutes, expiresAt

Check if a temporary email session is still active and retrieve session details.

Read a specific message from a temporary email inbox.

Permanently delete a temporary email session and all associated messages.

Manage persistent email accounts on your custom domains. Requires API key.

Returns: Promise<Account[]> — email, domain, createdAt

Returns: Promise<CreatedAccount> — email

Returns: Promise<DeleteResult> — deletedCount

Read emails from persistent account inboxes. Requires API key.

Returns: Promise<InboxMessage[]> — uid, from, subject, date, text, html

Returns: Promise<Message> — uid, from, to, subject, date, text, html, headers

Automatically extract OTP verification codes from emails sent by popular services. Requires API key.

Returns: Promise<VerificationCode> — code, service, email, from, subject, date

Static method returning all supported service names.

Static type guard for validating service names.

Generate random email accounts with secure auto-generated credentials. Requires API key.

Returns: Promise<RandomEmailPreview> — username, email, password, domain

Returns: Promise<RandomEmailBatch> — count, emails, note?

List available email domains by tier.

Returns: Promise<CustomerDomains> — free, premium, customer, packageType, authenticated

Returns: Promise<PublicDomains> — free, premium, ttlOptions

Generate short URLs for temporary email sessions and messages.

Returns: Promise<Shortlink> — code, url

The SDK provides a structured error hierarchy with typed exception classes:

import {
  EvilMail,
  EvilMailError,       // Base class for all SDK errors
  ApiError,            // Non-2xx HTTP response
  AuthenticationError, // 401 / 403 — invalid API key
  NotFoundError,       // 404 — resource not found
  RateLimitError,      // 429 — too many requests
  ValidationError,     // 400 / 422 — invalid parameters
  TimeoutError,        // Request timeout exceeded
  ConfigError,         // Client misconfiguration (e.g. missing API key)
} from 'evilmail';

const client = new EvilMail('your-api-key');

try {
  const code = await client.verification.getCode('google', '[email protected]');
  console.log(`Code: ${code.code}`);
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('No verification email found yet');
  } else if (err instanceof RateLimitError) {
    console.log('Too many requests — slow down');
  } else if (err instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (err instanceof ApiError) {
    console.log(`API error ${err.statusCode}: ${err.message}`);
    console.log('Is server error:', err.isServerError);
  } else if (err instanceof TimeoutError) {
    console.log('Request timed out');
  }
}

For functional error checking without instanceof:

import { isNotFoundError, isRateLimitError, isApiError } from 'evilmail';

try {
  await client.inbox.getMessage(999, '[email protected]');
} catch (err) {
  if (isNotFoundError(err)) console.log('Not found');
  if (isRateLimitError(err)) console.log('Rate limited');
  if (isApiError(err)) console.log(`Status: ${err.statusCode}`);
}

Cancel any in-flight request using the native AbortController:

const controller = new AbortController();

// Global abort signal — cancels all requests
const client = new EvilMail('your-api-key', {
  signal: controller.signal,
});

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const temp = await client.tempEmail.create({ ttlMinutes: 60 });
} catch (err) {
  if (err instanceof ApiError && err.message === 'Request aborted') {
    console.log('Request was cancelled');
  }
}

The SDK ships with complete TypeScript declarations for both ESM and CommonJS. All types are exported from the main entry point:

import type {
  TempEmailSession,
  TempEmailInfo,
  Message,
  InboxMessage,
  Account,
  CreatedAccount,
  DeleteResult,
  VerificationCode,
  VerificationService,
  RandomEmailPreview,
  RandomEmailBatch,
  PublicDomains,
  CustomerDomains,
  Shortlink,
  ClientOptions,
} from 'evilmail';

• Automated Testing & QA — Generate disposable email addresses for Playwright, Puppeteer, Cypress, and Selenium test suites
• Web Scraping & Automation — Create temp emails for sign-up verification in automation pipelines
• Email Verification Bots — Automatically extract OTP codes from Google, Facebook, Instagram, and more
• Account Provisioning — Bulk create and manage email accounts for SaaS platforms
• Privacy & Anonymity — Use anonymous disposable email addresses to protect user identity
• CI/CD Pipelines — Integrate email testing into GitHub Actions, GitLab CI, or Jenkins workflows
• Serverless Functions — Lightweight zero-dependency client for AWS Lambda, Vercel, Cloudflare Workers
• CLI Tools — Build email automation scripts and command-line utilities with Node.js
• Backend Services — Native TypeScript support for Express, Fastify, NestJS, and Koa backends
• Real-time Applications — AbortController support for WebSocket-driven or event-based architectures

• EvilMail Website — Temporary & custom domain email platform
• API Documentation — Full REST API reference
• Chrome Extension — Disposable temp email in your browser
• Firefox Add-on — Temp email for Firefox
• Mobile App — Privacy-first email on Android

MIT

• Issues: github.com/Evil-Mail/evilmail-node/issues
• Email: [email protected]
• Website: evilmail.pro