An ad-hoc mail server. Create and use ad hoc disposable mailboxes for testing or any other purpose.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Ad Hoc Email Server (AHEM)

Ad Hoc Email Server is, well, an ad hoc mail server. AHEM server can be used for testing, were a large (or unknown) number of mailboxes is needed or to provide disposable emails for registering into services that might expose the email for spam; This project will provide both RESTful api and web application for consuming the service. A working example of AHEM is always available - and usable - at

Alt text

Getting Started

Ahem mail server will accept any email sent to it (on the domains specified in the configuration), and create an ad hoc mailbox as needed. Then just browse to it's UI, enter the account name and you'll see the emails the account received. That's it. No authentication. No account creation.


nodejs > v6.11 
angular cli installed globally (npm install -g @angular/cli)


# clone the repository
git clone
cd ahem-server
npm install
# builds the project.
# There are other, convenience options for build and run in development mode.
npm run build:ssr
# prod run - will run the backend which will also serve the front end form the `dist` folder.
npm run serve:ssr


A configuration file names properties.json is located in the root of the project. Edit it to fit your use case. Parameters:

  • serverBaseUri - the base address for your api server
  • mongoConnectUrl - the mongodb connect url in the form of "mongodb://localhost:27017/ahem"
  • appListenPort - the port the node app will bind to.
  • smtpPort - ahem... you know.
  • emailDeleteInterval - The time in seconds between age checks for purging old files.
  • emailDeleteAge - The age in seconds above which emails will be deleted
  • allowedDomains - An array of allowed email domains. These domains will be allowed by the server as RCPT TO: entries. This also makes the server not act as an open relay. Format: ["", ""]
  • customText - html string that will replace the default text in the landing page
  • allowAutocomplete - if set to false, will prevent auto completing users in the ui


  • Build docker: docker build -t o4oren/ahem .
  • Run docker: docker run -it -p 3000:3000 -p 25:25 -d o4oren/ahem
  • Sign into docker: docker exec -it [docker_id] sh
  • start docker stackand swarm: docker swarm init && docker stack deploy -c docker-compose.yml ahemswarmc
  • stop docker stack: docker stack rm getstartedlab

Build and run with mongodb

  • docker-compose build
  • docker-compose up


The full api documentation is available at

A brief list of RESTful resources:

HTTP Method URI Path Parameters Descritpion
POST /account/autocomplete { "prefix":"value" } Returns a partial list of accounts
GET /api/properties returns the properties.json content
GET /api/account/{account} returns a list of the email objects in the account
GET /api/account/{account}/{emailId} Gets the contents of a specific email
PATCH /api/account/{acount}/{emailId} {"isRead" : true} Updates the emailInfo object (representation of the email meta data in the user's account. Currently, only the isRead field is supported.
GET /api/account/{account}/{emailId}/attachments/{filename} Downloads a specific attachment form an email
DELETE /api/account/{account}/{emailId} Deletes a specific email
DELETE /api/account/{account} Deletes a whole account

Google Analytics

AHEM server is ready for google analytics. By default, when you set it up, it will not send information to GA though. If you'd like to enable GA, add the snippet below in your /client/index.html file's head section, and rebuild the project. Replace XX-XXXXXXXXX-X with your GA id.

        (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

    ga('create', 'XX-XXXXXXXXX-X', 'auto');

Todo for 1.0

  • Error page when user/email doesn't exist.
  • Empty mail page
  • Landing page
  • Errors on find user/email in api
  • Error on non existing user / message
  • routing for messages
  • read/unread icons
  • attachments
  • allow delete emails
  • migrate to mongodb
  • [] update missing emails page and loading circles
  • [] Add apis to get account references from email, get account and email counts - both general and in account context


  • Oren Geva

See also the list of contributors who participated in this project.


This project is licensed under the MIT License - see the file for details