- Name: XCMailr
- Version: 3.0.1
- Release: June 2023
- License: Apache V2.0
- License URI: http://www.apache.org/licenses/LICENSE-2.0.txt
- Tags: AntiSpam, Testutility
- Contributors:
- Patrick Thum, Xceptance Software Technologies GmbH
- Patrick Hähnlein, Xceptance Software Technologies GmbH
XCMailr has been built to aid testing. Testing needs email addresses to create accounts, test formats of emails addresses, and last but not least load testing needs a ton of that. A special challenge for load testing is, that the mails should be deliverable, so that the sending system is not overwhelmed by returns.
Commercial or free system do not want to see 20k fake accounts that receive about 1,500 emails per day each. Your sender will be blocked quickly. Additionally you often cannot disable email delivery because the system under test does either not have that option or it is out of reach.
XCMailr lets you quickly and easily setup email accounts for testing purposes. Simply create temporary email addresses and have all incoming email forwarded to your actual account. When its configurable lifetime expires, the address gets deactivated and all incoming mail will be silently dropped. XCMailr doesn't store any email content and and won't notify the sender if the address is no longer valid.
So you host XCMailr yourself, you control security, you control availability, you control the domains, you control everything. Hence XCMailr is perfect for real-life testing of sensitive systems as well, because no third party will see your test emails and draw conclusion from it.
- Java 11 runtime (OpenJDK compatible)
- Apache Maven 3.0.0+ for building the sources
- Memcached, optional since V1.1.3 but recommended for production
- Copy the application configuration template
conf/application.conf.template
toconf/application.conf
and open it in your editor. - It is strongly recommended to create a new application secret. This secret ensures that the session-cookie of a user has not been modified.
- You should especially customize the following settings:
- application.secret uncomment and set this line, its used to verify session-cookies
- mbox.dlist the list of available domains
- mbox.host the main-application-host
- mail.smtp.* the "outbound" SMTP-Server (the server to which the application will forward any "valid" messages)
- memcached.* the MemCached-Server (host and port)
- ebean.* the Ebean-Configuration
- Logging can be configured by editing conf/logback.xml. See https://logback.qos.ch/manual/ for documentation.
- To configure HTTP and HTTPS, you can set the following properties to desired values as described on https://www.ninjaframework.org/documentation/configuration_and_modes.html
- ninja.ssl.port the HTTPS port (set to
-1
to disable HTTPS listener) - ninja.port the HTTP port (set to
-1
to disable clear-text HTTP listener) - ninja.ssl.keystore.uri the URI to the keystore to use
- ninja.ssl.keystore.password the password of the keystore
- ninja.ssl.truststore.uri the URI to the truststore to use
- ninja.ssl.truststore.password the password of the truststore
- ninja.ssl.port the HTTPS port (set to
First of all, you should create your own application configuration file by simply making a copy of the existing template application.conf.template
located in the conf
folder.
The copy should be named application.conf
and reside in the conf
folder as well.
Now, open and edit it in your favorite editor (see Configuration). Make sure to save it using UTF-8 encoding.
Finally, run the script bin/run.sh
(or bin\run.cmd
respectively). If configured correctly, you should see something like the following in your console
Ninja application running at
=> http://localhost:8080
If you set a value for ninja.context
, the server will use that value as context path for your application. That means when you specify the value "xcmailr" for ninja.context
and "http://localhost:8080" as application.url
, then your application can be locally reached at "http://localhost:8080/xcmailr". In case you want to run the application behind a reverse proxy, have a look at the section below.
IMPORTANT Make sure to use different values for all of the following settings, otherwise you might purge your production DB by accident:
- ebean.datasource.databaseUrl
- %test.ebean.datasource.databaseUrl
- %dev.ebean.datasource.databaseUrl
- If you want to build the project from the sources, you have two options to run the webapp.
- First option (after you've changed something and want to check your changes), the development-mode:
- cd into the 'xcmailr-webapp' folder
- if you build the app the very first time, execute
mvn clean compile process-classes
to clean up the target folder (if existent) and compile the app - execute
mvn ninja:run
to run the app in development-mode inside an embedded Jetty listing on localhost:8080 for HTTP and localhost:8443 for HTTPS - NOTE (especially for contributors): You probably want to change the configuration-file in dev-mode. Thereby, you should either set a gitignore (or svn:ignore) to prevent that your personal data (e.g. the mailservice-login) will be committed to the repository or you can place another application.conf at /home/yourUsername/conf/ . The ninja-framework uses Apache Commons Configuration to read the file. It will search for the configuration-file at first in this folder. In both cases you have to take care that the .conf-files at ./xcmailr-webapp/src/main/resources/conf and ./xcmailr-webapp/conf are up-to-date and contain all necessary keys.
- Second option (to create the distribution archive):
- cd into the 'xcmailr-webapp' folder
- execute
mvn clean package
to compile the app, run tests and create the distribution archive - extract the distribution archive located in the 'target' directory anywhere you like and proceed as described in section "Run the Application"
- You may want to use an (Apache2) reverse-proxy in front of the application. With the
ninja.context
setting in the application.conf, you can specify a context path for your application. Thereby, you can use the same path on which the app will be available through the proxy. - For instance, if it will be available externally at "http://reverse.proxy/path/to/app", then you can set the context-path to "path/to/app" and it will run locally at "http://localhost:port/path/to/app".
- The advantage is that you don't have to use the mod_proxy_html-module to rewrite every link and file path on all HTML pages.
- After setting up the Apache2 with all necessary Proxy-Modules (especially you have to enable proxy and proxy_http), you'll have to create a VirtualHost-Configuration for your site. Here's a small example for that:
<VirtualHost *:80>
ProxyRequests off
ProxyPass /xcmailr/ http://localhost:8080/xcmailr/
ProxyPassReverse /xcmailr/ http://localhost:8080/xcmailr/
<Proxy http://localhost:8080*>
Order deny,allow
allow from all
</Proxy>
Redirect /xcmailr /xcmailr/
</VirtualHost>
- We set the context path to "xcmailr" and our app then runs locally on "http://localhost:8080/xcmailr", externally it can be reached with this configuration at http://mydomain/xcmailr.
XCMailr supports API token to access some XCMailr functionality without using e-mail and password to authenticate. An API token can be generated in the edit profile menu. token
You can create a new token or revoke an earlier generated token.
An http based API was added to XCMailr containing the following functionality.
Create a new temporary email address that will be associated with you already registered account. That temporary email address has a limited life span which can be defined with parameter validTime. The parameter is a natural number indicating how many minutes that temporary email will be active. The upper limit for the maximum allowed time span can be configured in application.conf (application.temporarymail.maximumvalidtime, default value is 30).
The parameter mailAddress is the full address that is desired to claim. E.g. foo@bar.com provided that you configured XCMailr to serve email for bar.com The parameter token is the token that can be created in the edit profile menu.
http://xcmailrhost/create/temporaryMail/{token}/{mailAddress}/{validTime}
e.g. http://xcmailrhost/create/temporaryMail/MyAccessToken/foo@bar.com/5 Uses the token (here "MyAccessToken" for) to claim address foo@bar.com. The mail address can receive emails for 5 minutes before the address expires. An expired address can be reactivated by using the same call given that your account is associated with the desired address. In case another account claimed that address before a http error is thrown.
In case of any error during temporary mail creation an http error is thrown, no further advice is given.
XCMailr behavior has changed recently. Emails sent to an active mail address will now be saved for a limited time (10 minutes, this can't be changed at the moment). The received emails can be accessed through the web interface. See "My Emails" once you are logged in.
There is also an API functionality which allows to also filter received emails for a given mail address. In order to do so one can use the following URL and the following parameter. mailAddress is the full address that is claimed by the used account. The parameter token can be generated in the edit profile dialog http://xcmailrhost/mailbox/{mailAddress}/{token}
URL parameter
-
from: a regular expression to find in the address the mail was sent from
-
subject: a regular expression to find in the emails subject
-
textContent: a regular expression to find in the emails text content
-
htmlContent: a regular expression to find in the emails html content
-
plainMail: a regular expression to find in the plain mailsmailHeader: a regular expression to find in the mail's header text
-
lastMatch: a parameter without value that limits the result set to one entry. This is the last filter that will be applied to result set.
-
format: a string indicating the desired response format. If not defined then the result will be displayed as html. Valid values are "json" and "plain". With format json the results will be returned as json formatted string. The format plain is used to retrieve the mail in the format the mail server received it. This contains also all email header and encoding fields. Also the plain format will automatically limit the results to one entry since multiple results could hardly distinguished in the response.format: a string indicating the desired response format. If not defined then the result will be displayed as html. Valid values are "html", "json" and "header". With format json the results will be returned as json formatted string. The format header is used to retrieve the mail's header as XCMailr received it. This format will automatically limit the results to one entry since multiple results could hardly distinguished in the response.
Example: http://xcmailrhost/mailbox/foo@bar.com/MyAccessToken?subject=
- https://github.com/angular-ui/bootstrap
- MIT-License: https://github.com/angular-ui/bootstrap/blob/master/LICENSE
- https://github.com/Eonasdan/bootstrap-datetimepicker
- MIT-License: https://github.com/Eonasdan/bootstrap-datetimepicker/blob/master/LICENSE
- http://www.h2database.com/
- Dual licensed
- H2 License, V1.0: http://www.h2database.com/html/license.html#h2_license
- EPL: http://www.h2database.com/html/license.html#eclipse_license
- Copyright Jan Kovařík
- http://glyphicons.com/
- Apache V2.0 License: https://github.com/twitter/bootstrap/wiki/License
- Copyright (c) 2006 Damien Miller
- http://www.mindrot.org/projects/jBCrypt/
- ISC/BSD License: http://www.mindrot.org/files/jBCrypt/LICENSE
- http://www.eclipse.org/jetty/
- Apache V2.0 License: http://www.apache.org/licenses/LICENSE-2.0
- http://joda-time.sourceforge.net
- Apache V2.0 License: http://joda-time.sourceforge.net/license.html
- http://tablesorter.com
- Dual licensed
- MIT-License: http://www.opensource.org/licenses/mit-license.php
- GPL: http://www.opensource.org/licenses/gpl-license.php
- https://github.com/moment/moment/
- MIT-License: https://github.com/moment/moment/blob/develop/LICENSE
- http://www.ninjaframework.org/
- Apache V2.0 License: https://github.com/reyez/ninja/blob/develop/license.txt
- http://code.google.com/p/spymemcached/
- MIT-License: http://www.opensource.org/licenses/mit-license.php
- https://github.com/twbs/bootstrap
- MIT-License: https://github.com/twbs/bootstrap/blob/master/LICENSE
- https://github.com/twitter/typeahead.js
- MIT-License: https://github.com/twitter/typeahead.js/blob/master/LICENSE
XCMailr is licensed under the Apache Version 2.0 license. See LICENSE file for full license text.