Installation

ImapKit needs Node.js 20 or newer. It also runs on the latest Bun and Deno releases, and its own test suite runs on both in CI.

As a dev dependency

Most projects use ImapKit from their test suite:

npm install --save-dev imapkit

The package ships ES modules and CommonJS, each with type declarations:

import imapkit from 'imapkit';
// or with CommonJS: const imapkit = require('imapkit');

const server = imapkit({ plugins: ['IDLE'] });
const port = await server.start();

Next to the imapkit(options) factory, the package exports ImapKitError (the error the control API throws), quirks (the quirk presets as data), validateStorage() and storageSchema (the check and JSON Schema of the storage option), the IMAPServer and IMAPConnection classes, and TypeScript types:

import imapkit, { ImapKitError, type IMAPServerOptions, type Plugin } from 'imapkit';

With Bun, bun add -d imapkit. With Deno, import npm:imapkit.

As a standalone server

Install the command globally, or run it from the project with npx imapkit:

npm install -g imapkit
imapkit -p 1143

Point any IMAP client to localhost:1143 and log in with user name testuser and password testpass. Without -p the server listens on port 143 (993 with --secure), which usually needs root privileges.

The command takes plugins, a storage file, script rules, quirk presets and a REST API port. See Command line for every option, or run:

imapkit --help

Optional: the SMTP listener

ImapKit can also accept mail over SMTP and append every message it receives to INBOX (--smtpPort for the command, the smtp option in code). The listener needs the smtp-server package, an optional peer dependency that is not installed with ImapKit:

npm install --save-dev smtp-server
# or, next to a global install
npm install -g smtp-server

Without it, server.start() rejects with an error that tells you to install it, and the IMAP server works as usual when SMTP is not enabled.

Default account

Every server has one account until you configure others:

User name	Password	Access token (XOAUTH2, OAUTHBEARER)
testuser	testpass	testtoken

The users option replaces this list, and the control API adds users at runtime. All users share the same mailbox tree; see Authentication.

Next steps

• Write your first test in the Quick Start.
• Run the server from the shell with the command line options.