Skip to content
An ad-hoc disposable temporary mail server. Create and use ad hoc disposable mailboxes for testing or any other purpose.
TypeScript HTML CSS JavaScript API Blueprint Dockerfile
Branch: master
Clone or download

Latest commit

Latest commit 92042b4 May 14, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
client Revert "Adsterra (#17)" Mar 17, 2020
e2e Universal branch, trying to make it work Nov 14, 2017
k8s kubernetes config files added Jan 14, 2020
server/app Adsterra (#17) Mar 17, 2020
.dockeringnore Dockerize build and run. Need to implement mongo integration and volume. Jan 29, 2018
.editorconfig Ver 0.3 - Added project, backend email only for now. Jul 2, 2017
.env.sample blog entry update Jan 15, 2020
.gitignore dockerization updates and fixes Jan 12, 2020
.travis.yml fixed travis file Jan 13, 2020
Dockerfile dockerization updates and fixes Jan 12, 2020
Dockerfile_ssr dockerization updates and fixes Jan 12, 2020
LICENSE.md
README.md Update README.md May 14, 2020
ahem.js email count socket io thing Jan 15, 2020
angular.json Core module contains footer and header Sep 29, 2018
apiary.apib Transferring API Description file from Apiary.io Oct 18, 2018
browserslist Added browserlist Oct 2, 2019
docker-compose-ssr.yml yml Jan 12, 2020
docker-compose.yml docker compose ssr Jan 13, 2020
karma.conf.js Update all components to angular 6 Sep 25, 2018
mailTester.js Added test script to generate emails Oct 6, 2018
openapi.json Changed account to mailbox Oct 16, 2018
package-lock.json Bump acorn from 6.3.0 to 6.4.1 (#18) Apr 12, 2020
package.json email count socket io thing Jan 15, 2020
properties.json updatedndocumentationh Oct 12, 2018
protractor.conf.js Ver 0.3 - Added project, backend email only for now. Jul 2, 2017
proxy.conf.json email count socket io thing Jan 15, 2020
tsconfig.json Updated to angular 8 and fixed security issues Oct 2, 2019
tslint.json Updated to angular 8 and fixed security issues Oct 2, 2019
universalServer.ts back to dynamicatlly read Jan 8, 2019
webpack.backend.config.js Added two items to home screen Oct 25, 2018
webpack.server.config.js Seperate back and frontend Oct 22, 2018

README.md

Ad Hoc Email Server (AHEM)

Build Status

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

  • Note - the public cloud based version of AHEM will be cancelled on June 11, 2020.

Getting Started

AHEM 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 its UI, enter the mailbox name and you'll see the emails contained in the mailbox. That's it. No authentication. No account creation.

Prerequisites

nodejs > v10 
angular cli installed globally (npm install -g @angular/cli)
mongodb

Installation

# clone the repository
git clone https://github.com/o4oren/ahem-server.git
cd ahem-server
npm install
# builds the project.
npm run build:ssr

# there are other, convenience options for build and run in development mode.
# for development:
npm run startDev

# for prod:
# will run the backend which will also serve the front end form the `dist` folder.
node ahem.js

Configuration

AHEM use several environment variables for configuration. These can be set up using a .env file (see dotEnv docuemntation). An example file is located in the root of the project. If a .env file is no found, you can just set these items as env variables. A docker-compose file is also present in the root of the project, showing how these configuration properties can be set in a docker compose set up or passed to a docker image.

These are the available parameters:

Parameter Description
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 The SMTP server's port. Note that by default it is set to 2525 - this is done for testing purposes, as on many systems only a system account can listen on port 25.
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: ["my.domain.com", "my.second-domain.com"].
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.
jwtSecret The JWT secret, if using token authentication.
jwtExpiresIn JWT token TTL in seconds. -1 means token validation is not enforced.
maxAllowedApiCalls If using token validation, this is the amount of API calls a token is allowed to make.

Docker

  • Build docker: docker build -t o4oren/ahem .

  • Build FE only: docker build -t o4oren/ahem-universal . -f Dockerfile_ssr

  • Run docker with external properties: docker run -v /[local.dotEvn.path]/.env:/opt/ahem/.env -it -p 3000:3000 -p 25:25 -d o4oren/ahem

  • Sign into docker: docker exec -it ahem sh

  • start docker stackand swarm: docker swarm init && docker stack deploy -c docker-compose.yml ahemswarmc

  • stop docker stack: docker stack rm getstartedlab

  • In addition, sample kubernetes yaml config files are provided as reference in the k8s folder. These are provided as is.

  • for debugging - run mongo on docker locally: docker run -d -p 27017:27017 -v ~/data:/data/db mongo

Build and run with mongodb

  • docker-compose build
  • docker-compose up

Palette

The AHEM color palette is available here.

API

The full API documentation is available here.

A brief list of RESTful resources:

HTTP Method URI Path Parameters Description
POST /api/mailbox/autocomplete { "prefix":"value" } Returns a partial list of mailboxes.
GET /api/properties Returns global system properties.
POST /api/auth/authenticate { } Returns an access token.
GET /api/mailbox/{mailbox}/email Returns a list of the email objects in the mailbox.
GET /api/mailbox/{mailbox}/email/{emailId} Gets the contents of a specific email.
PATCH /api/mailbox/{acount}/email/{emailId} {"isRead" : true} Updates the emailInfo object (representation of the email meta data in the mailbox). Currently, only the isRead field is supported.
GET /api/mailbox/{mailbox}/email/{emailId}/attachments/{filename} Downloads a specific attachment from an email.
DELETE /api/mailbox/{mailbox}/email/{emailId} Deletes a specific email.
DELETE /api/mailbox/{mailbox} Deletes a whole mailbox.

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.

  <script>
    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
        (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
    })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

    ga('create', 'XX-XXXXXXXXX-X', 'auto');
  </script>

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
  • Sort out logging
  • Separate mailbox view from email view pages
  • Separate server and webapp properties
  • Better home page
  • Add apis to get mailbox references from email, get mailbox and email counts - both general and in mailbox context

Authors

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

License

This project is licensed under the GPLv3 License - see the LICENSE.md file for details

You can’t perform that action at this time.