@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 pretty for human-readable 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.

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)