@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()):

| Field | Type | Default | Description | |---|---|---|---| | email | string | — | SMTP sender email address | | password | string | — | SMTP sender password or app password | | host | string | — | SMTP host (e.g., 'smtp.gmail.com') | | port | number | 587 | SMTP port |

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

| Field | Type | Default | Description | |---|---|---|---| | email | string | — | IMAP email address | | password | string | — | IMAP password or app password | | host | string | 'imap.gmail.com' | IMAP host | | port | number | 993 | IMAP port |

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

| Option | Type | Default | Description | |---|---|---|---| | filters | EmailFilter[] | — | Required. Array of filters (AND logic) | | folder | string | 'INBOX' | IMAP folder to search. Accepts a literal path or a specialUse role (e.g. '\\Sent', '\\Trash') | | waitTimeout | number | 30000 | Max milliseconds to poll before throwing an error | | pollInterval | number | 3000 | Milliseconds to wait between IMAP fetch attempts | | expectedCount | number | 1 | Number of matching emails required before returning | | downloadDir | string | os.tmpdir() | Directory to save downloaded .html copies | | maxFetchLimit | number | 50 | Max emails to fetch per polling cycle (memory protection) |

Available Filters (EmailFilterType)

| Type | Value Type | Description | |---|---|---| | SUBJECT | string | Exact or partial match of the email subject | | FROM | string | Sender email address | | TO | string | Recipient email address | | CONTENT | string | Matches anywhere in the HTML body or plain text fallback | | SINCE | Date | Only fetch emails received after this timestamp |

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]' }],
});

// Nuke the entire inbox (Use with caution!)
await client.clean();

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.

| Role | Description | |---|---| | \All | All Mail | | \Trash | Trash / Deleted Items | | \Sent | Sent Mail | | \Drafts | Drafts | | \Junk | Spam | | \Flagged | Starred / Flagged | | \Inbox | Inbox |

// 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:

| Property | Type | Description | |---|---|---| | subject | string | Email subject line | | from | string | Sender address | | to | string | Recipient address | | date | Date | Date the email was sent | | html | string | Parsed HTML body (empty string if plain-text only) | | text | string | Parsed plain-text content | | filePath | string | Local path to the downloaded .html copy |

Error Handling

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

| Operation | Missing Credentials | Error Message | |---|---|---| | send() | SMTP | SMTP credentials are required to send emails. Provide { smtp: { email, password, host } } when constructing EmailClient. | | receive() / receiveAll() | IMAP | IMAP credentials are required to receive/manage emails. Provide { imap: { email, password } } when constructing EmailClient. | | clean() / mark() | IMAP | IMAP credentials are required to receive/manage emails. Provide { imap: { email, password } } when constructing EmailClient. |

Contributing

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

License

MIT