@civitas-cerebrum/email-client

A highly robust, zero-dependency SMTP/IMAP email client built specifically for E2E test automation. Send, receive, search, manage, and clean emails using composable, deterministic filters.

Why this client?

• Zero Playwright runtime dependency — Works seamlessly with Playwright, Cypress, Vitest, Jest, or any Node.js test runner.
• Smart Polling Engine — Built-in retry logic prevents flaky tests caused by slow email delivery.
• Memory Protected — Automatically caps raw MIME fetches to prevent Node.js memory crashes when hitting large, unmanaged test inboxes.
• Two-Phase Matching — Evaluates exact IMAP criteria first, then falls back to a smart, case-insensitive client-side match to catch poorly formatted automated emails.
• Full Mailbox Management — Send, receive, flag, archive, and aggressively clean your test environment.

Installation

npm install @civitas-cerebrum/email-client

Quick Start

Send-Only (SMTP)

import { EmailClient } from '@civitas-cerebrum/email-client';

const client = new EmailClient({
    smtp: {
        email: '[email protected]',
        password: 'app-password',
        host: 'smtp.example.com',
    },
});

await client.send({
    to: '[email protected]',
    subject: 'Your OTP Code',
    text: 'Your code is 123456',
});

Receive-Only (IMAP)

import { EmailClient, EmailFilterType } from '@civitas-cerebrum/email-client';

const client = new EmailClient({
    imap: {
        email: '[email protected]',
        password: 'app-password',
    },
});

const email = await client.receive({
    filters: [{ type: EmailFilterType.SUBJECT, value: 'Your OTP Code' }],
});
console.log(email.text);

Full Client (Send + Receive)

SMTP and IMAP credentials are independent — they can point to different providers or accounts. For example, send via a transactional relay and receive from Gmail:

import { EmailClient, EmailFilterType, EmailMarkAction } from '@civitas-cerebrum/email-client';

const client = new EmailClient({
    smtp: {
        email: '[email protected]',
        password: 'app-password',
        host: 'smtp.example.com',
    },
    imap: {
        email: '[email protected]',
        password: 'app-password',
    },
});

await client.send({ to: '[email protected]', subject: 'OTP', text: '123456' });

const email = await client.receive({
    filters: [{ type: EmailFilterType.SUBJECT, value: 'OTP' }],
});

await client.mark({
    action: EmailMarkAction.READ,
    filters: [{ type: EmailFilterType.SUBJECT, value: 'OTP' }],
});

await client.clean({
    filters: [{ type: EmailFilterType.SUBJECT, value: 'OTP' }],
});

API Reference

Initialization

Constructor: new EmailClient({ smtp?, imap? }) or new EmailClient(legacyCredentials)

SmtpCredentials (required for send()):

ImapCredentials (required for receive(), receiveAll(), clean(), mark()):

Legacy Format

The old flat EmailCredentials interface is still supported for backward compatibility. Migration to the new split format is encouraged.

// Legacy format (still supported)
const client = new EmailClient({
    senderEmail: '[email protected]',
    senderPassword: 'app-password',
    senderSmtpHost: 'smtp.example.com',
    receiverEmail: '[email protected]',
    receiverPassword: 'app-password',
});

Sending Emails (send)

Supports plain text, inline HTML, and loading HTML files directly from disk.

// Plain text
await client.send({ to: '[email protected]', subject: 'Test', text: 'Hello' });

// Inline HTML
await client.send({ to: '[email protected]', subject: 'Report', html: '<h1>Results</h1>' });

// HTML template from disk
await client.send({ to: '[email protected]', subject: 'Report', htmlFile: 'emails/template.html' });

Receiving Emails (receive / receiveAll)

The client uses a robust polling mechanism. It will continuously query the IMAP server until the waitTimeout is reached or the filters are satisfied. Combine multiple filters to create strict AND logic constraints. When multiple emails match, receive() returns the most recent one by date.

// Get the single most recent matching email
const email = await client.receive({
    filters: [{ type: EmailFilterType.SUBJECT, value: 'Your OTP' }],
    waitTimeout: 15000 // Optional: fail if not found in 15s
});

// Get ALL matching emails in the inbox (useful for batch processing)
const allEmails = await client.receiveAll({
    filters: [
        { type: EmailFilterType.FROM, value: '[email protected]' },
        { type: EmailFilterType.SINCE, value: new Date('2025-01-01') },
    ],
});

Receive Options

Searching multiple folders

A message does not always arrive where you expect it. Mail from a new or low-reputation sending domain is routinely filed as spam by the receiving server, and a spam-filed message is never found by an inbox-only search — no matter how long you wait for it.

Pass folders to search several mailboxes in one call. Every folder is searched on every polling cycle and the matches are pooled, so the wait ends as soon as the message shows up anywhere in the set:

const email = await client.receive({
    filters: [{ type: EmailFilterType.SUBJECT, value: 'Your verification code' }],
    folders: ['INBOX', '[Gmail]/Spam'],   // or ['INBOX', '\\Junk'] to stay portable
    waitTimeout: 60000,
});

folders is accepted by receive, receiveAll, clean and mark, and takes precedence over folder when both are given. For clean and mark the action is applied in each folder in turn and the returned count is the total.

Missing folders. A single folder is strict — naming one that does not exist throws, listing the folders the server does have. A folder list is tolerant: an absent folder is skipped so a portable set works against servers that lack one of them. If none of the listed folders can be opened, the call still throws.

Do not reach for \All as a shortcut. All Mail also contains sent, archived and recently-deleted copies, so a search across it will keep finding a message you have already moved or deleted. Name the folders you actually mean.

Available Filters (EmailFilterType)

Managing the Inbox (mark / clean)

Keep your automated test inboxes clean and organized to prevent IMAP throttling and memory issues.

Mark (Flagging and Moving)

Modify the state of emails matching specific criteria. Returns the number of emails affected.

// Apply standard flags
await client.mark({
    action: EmailMarkAction.READ, // READ, UNREAD, FLAGGED, UNFLAGGED
    filters: [{ type: EmailFilterType.SUBJECT, value: 'Welcome' }]
});

// Move emails to an archive folder (using specialUse role — works across all locales)
await client.mark({
    action: EmailMarkAction.ARCHIVED,
    filters: [{ type: EmailFilterType.FROM, value: '[email protected]' }],
    archiveFolder: '\\Trash' // Resolves to the server's actual Trash path at runtime
});

// Apply custom IMAP flags
await client.mark({
    action: ['\\Draft', '\\Answered'],
    filters: [{ type: EmailFilterType.SUBJECT, value: 'Custom State' }]
});

Clean (Deleting)

Permanently delete emails from the server.

// Delete specific emails
await client.clean({
    filters: [{ type: EmailFilterType.FROM, value: '[email protected]' }],
});

// Delete across several folders in one call
await client.clean({
    filters: [{ type: EmailFilterType.SUBJECT, value: 'my-test-run-42' }],
    folders: ['INBOX', '[Gmail]/Spam'],
});

// Nuke an entire folder (Use with caution!)
await client.clean();                       // every message in INBOX
await client.clean({ folder: 'scratch' });  // every message in "scratch"

Sharing a mailbox? clean() with no filters deletes everything in the target folder, including messages another process put there. If more than one test run can touch the same mailbox, stamp a unique per-run token into every subject you send and always pass a filter selecting it — then a cleanup can only ever remove its own mail. Reserve the unfiltered form for a folder your run created and owns.

Folder Resolution

Any folder or archiveFolder option accepts either a literal path (e.g. '[Gmail]/Trash') or a specialUse role prefixed with \. The client resolves roles to the correct server path at runtime using IMAP LIST metadata, so your code works regardless of the mail server's language or naming conventions.

// These are equivalent on a Turkish Gmail account:
await client.clean({ folder: '[Gmail]/Çöp kutusu' }); // literal path
await client.clean({ folder: '\\Trash' });             // specialUse role (locale-independent)

The ReceivedEmail Object

When you receive an email, the client parses the raw MIME source and returns a clean, strongly-typed object:

Error Handling

The client provides clear error messages when credentials are missing for a specific operation:

Contributing

git clone https://github.com/Umutayb/email-client.git
cd email-client
npm install
npm run test

License

MIT