@logickernel/mailotron

A TypeScript library for email automation in tests. Generates unique plus-addressed inboxes and waits for emails to arrive via IMAP.

It relies on Gmail's plus-addressing: a Gmail mailbox like [email protected] also receives mail at you+<tag>@gmail.com. Gmail requires the tag to be numeric, so Mailotron generates unique numeric suffixes to give each test its own dedicated inbox.

Installation

npm install @logickernel/mailotron

Quick start

import { getInbox, waitForEmail } from '@logickernel/mailotron';

// 1. Generate a unique inbox alias
const address = getInbox();
// → '[email protected]'

// 2. Trigger something that sends an email to address …

// 3. Wait for it to arrive
try {
  const email = await waitForEmail(address, 'Welcome', { timeout: 30 });
  console.log(email.subject); // 'Welcome to Acme'
  console.log(email.text);    // plain-text body
} catch (err) {
  // Thrown when no matching email arrives within the timeout
  throw new Error(`Email not received: ${(err as Error).message}`);
}

Configuration

Copy .env.template to .env and fill in your credentials:

cp .env.template .env

Required

| Variable | Description | |---|---| | MAILOTRON_EMAIL_ADDRESS | Base Gmail address used by getInbox() | | MAILOTRON_IMAP_PASSWORD | IMAP app password |

Optional

The defaults below work out of the box with Gmail and Google Workspace. Only change these if you know what you are doing.

| Variable | Default | Description | |---|---|---| | MAILOTRON_IMAP_USER | MAILOTRON_EMAIL_ADDRESS | IMAP login username | | MAILOTRON_IMAP_HOST | imap.gmail.com | IMAP server hostname | | MAILOTRON_IMAP_PORT | 993 | IMAP server port | | MAILOTRON_IMAP_SECURE | true | Set to false to disable TLS | | MAILOTRON_SMTP_HOST | smtp.gmail.com | SMTP host (integration tests) | | MAILOTRON_SMTP_PORT | 587 | SMTP port (integration tests) | | MAILOTRON_SMTP_PASSWORD | MAILOTRON_IMAP_PASSWORD | SMTP password (integration tests) | | LOGGER_CONSOLE_FORMAT | — | Set to plain for unformatted logs |

Gmail App Password

Gmail requires an App Password rather than your account password:

1. Enable 2-Step Verification on your Google account.
2. Go to Security → App passwords and generate a password for "Mail".
3. Use that 16-character password (no spaces) as MAILOTRON_IMAP_PASSWORD.

API

getInbox(): string

Returns a unique plus-addressed inbox alias derived from MAILOTRON_EMAIL_ADDRESS, e.g. [email protected].

Throws if MAILOTRON_EMAIL_ADDRESS is not set or is not a valid email address.

waitForEmail(emailAddress, pattern, options?): Promise<Email>

Polls IMAP until an email addressed to emailAddress whose subject, text, or HTML matches pattern arrives, then resolves with a structured Email object.

| Parameter | Type | Default | Description | |---|---|---|---| | emailAddress | string | — | Recipient address to match (plus-tag or base) | | pattern | string \| RegExp | — | Tested against subject, text body, and HTML | | options.timeout | number | 10 | Seconds before rejecting with a Timeout error | | options.since | Date \| number | 10 min ago | Only consider emails received after this point |

interface Email {
  subject: string;
  text: string;
  html: string;
  messageId: string;
  from: string;
  to: string[];
  cc: string[];
  bcc: string[];
  replyTo: string;
  /** ISO 8601 string, or null if the message had no Date header */
  date: string | null;
  priority: string;
  attachments: EmailAttachment[];
}

interface EmailAttachment {
  filename: string;
  contentType: string;
  size: number;
}

Rejects with Error('Timeout: …') if no matching email arrives within the timeout.

disconnect()

Closes the shared IMAP connection and clears internal state. Call this in test teardown (afterAll) or let it happen automatically on process exit.

import { disconnect } from "@logickernel/mailotron"

afterAll(() => {
  disconnect()
})

available

Boolean indicating whether mailotron credentials are configured (MAILOTRON_EMAIL_ADDRESS is set). Use this to skip email-dependent tests:

import { available } from "@logickernel/mailotron"

test.skip(!available, "mailotron not configured")

Development

npm run build          # compile TypeScript → dist/
npm run typecheck      # type-check without emitting
npm test               # unit tests (Jest + ts-jest, no network required)
npm run test:integration  # end-to-end test (requires .env with SMTP + IMAP credentials)