GreenMail

GreenMail is an open source, intuitive and easy-to-use test suite of email servers for testing purposes.

Typical use cases include mail integration testing or a lightweight sand boxed mail server for development.

Supports SMTP, POP3 and IMAP including SSL
Prevents accidental email leaking to real mail servers
Provides different deployment models, such as WAR module or JBoss GreenMail Service
Easily embeddable in JUnit tests for integration testing
Lightweight with few dependencies

GreenMail is the fist and only library that offers a test framework for both receiving and retrieving emails from Java.

Scenarios

GreenMail is useful in the following scenarios:

Test Your Sending Code

System testing an application. GreenMail responds like a regular SMTP server but does not deliver any email, which enables it to be used in real life applications and real test cases. Messages can easily be extracted, verified and modified. Support for SMTPS (SSL) is enabled.
GreenMail is an excellent choice for unit testing code that needs to send email with a succinct, efficient (non-polling) way to wait for messages to arrive, retrieve, verify, and modify messages.
Note that retrieval of emails can be made with a simple java method or through a provided POP3, IMAP retriever helper class. Alternatively you can use a local client like Thunderbird.
The example below is using the GreenMail JUnit rule. See examples for hints on how to use GreenMail without the rule.


@Rule
public final GreenMailRule greenMail = new GreenMailRule(ServerSetupTest.SMTP);

@Test
public void testSend() throws MessagingException {
    GreenMailUtil.sendTextEmailTest("to@localhost.com", "from@localhost.com",
        "some subject", "some body"); // --- Place your sending code here instead
    assertEquals("some body", GreenMailUtil.getBody(greenMail.getReceivedMessages()[0]));
}

Test Your Retrieving Code

Again GreenMail can be used for system or unit testing an application needing to use POP3 or IMAP by responding like a standard compliant POP3 or IMAP server. Support for POP3S and IMAPS (SSL) is also enabled.
Messages can be placed directly in users mailboxes or by using SMTP.
GreenMail ships with helper classes for sending and retrieving. See the javadocs for the Retriever.java class


@Rule
public final GreenMailRule greenMail = new GreenMailRule(ServerSetupTest.SMTP_IMAP);

@Test
public void testReceive() throws MessagingException {
    GreenMailUser user = greenMail.setUser("to@localhost.com", "login-id", "password");
    user.deliver(createMimeMessage()); // You can either create a more complex message...
    GreenMailUtil.sendTextEmailTest("to@localhost.com", "from@localhost.com",
        "subject", "body"); // ...or use the default messages

    assertEquals(2, greenMail.getReceivedMessages().length); // // --- Place your POP3 or IMAP retrieve code here
}

Sending and Retrieving

GreenMail can easily be configured to use all or a combination of ports, protocols, and bind addresses. For example it's possible to run GreenMail on SMTP, POP3, POP3S and IMAPS ports as easily as only SMTP. Many systems might already be running these servers or don't allow non root users to open the default ports which is why GreenMail ships with a special configuration for testing.

Mocking a mail server for your development environment

GreenMail provides a JBoss GreenMail service for mocking a mail server for development. It safes you the overhead of either installing a full productive server (like Apache James).

Check out the possible deployments as webapp or JBoss Service.

Implementation

The implementation is in 100% Java with only a few library dependencies:

javamail.jar - JavaMail API
activation.jar - Java Activation Framework, required by JavaMail (provided by JDK since 1.6+)
slf4j-api.jar - required for logging via Simple Logging Facade for Java
junit.jar - required for easy test setup using Rules
commons-lang3.jar - for handling String escaping

Source Code

You find the source on GitHub including build instructions. GreenMail is open source released under The Apache 2.0 License.

GreenMail's protocol source code is based on a cocktail of Foedus and James.

Links

The following lists provide helpful links related to GreenMail and email integration testing.

Projects extending/wrapping GreenMail:

Grails Plugin for GreenMail including REST-like GreenMail control interface and UI
Play Plugin for GreenMail including REST-like control interface and UI
JCA Adapter for GreenMail
Deprecated SourceForge GreenMail project location before migration to GitHub in 2014

Articles&Blogs:

Projects using GreenMail include:

Alfresco
Mule ESB
... and many more. Tell us about your project :-)

Related projects to JavaMail and testing/development:

Dumbster, a fake SMTP server
Wiser alias Subethasmtp, another test SMTP server
Apache James, a full blown enterprise mail server
DevNullSmtp
Mock-javamail
JavaMail Mock2

Thanks

Special thanks to all contributors for feedback and patches!

Many thanks to and JetBrains for supporting this project with free OSS licenses!

The source code of the examples can be found in the test package of GreenMail (greenmail-core/src/test/java/com/icegreen/greenmail/examples/).

Using JUnit (Rule based setup)


@Rule
public final GreenMailRule greenMail = new GreenMailRule(ServerSetupTest.ALL);

@Test
public void testSomething() {
    GreenMailUtil.sendTextEmailTest("to@localhost.com", "from@localhost.com", "subject", "body");
    MimeMessage[] emails = greenMail.getReceivedMessages();
    assertEquals(1, emails.length);
    assertEquals("subject", emails[0].getSubject());
    assertEquals("body", GreenMailUtil.getBody(emails[0]));
    // ...
}

Testing your sending code (simple)


GreenMail greenMail = new GreenMail(); //uses test ports by default
greenMail.start();
GreenMailUtil.sendTextEmailTest("to@localhost.com", "from@localhost.com", "some subject",
                                "some body"); // --- Place your sending code here
assertEquals("some body", GreenMailUtil.getBody(greenMail.getReceivedMessages()[0]));
greenMail.stop();

Testing your sending code (advanced)


GreenMail greenMail = new GreenMail(ServerSetupTest.ALL);
greenMail.start();

//Use random content to avoid potential residual lingering problems
final String subject = GreenMailUtil.random();
final String body = GreenMailUtil.random();

sendTestMails(subject, body); // --- Place your sending code here

//wait for max 5s for 1 email to arrive
//waitForIncomingEmail() is useful if you're sending stuff asynchronously in a separate thread
assertTrue(greenMail.waitForIncomingEmail(5000, 2));

//Retrieve using GreenMail API
Message[] messages = greenMail.getReceivedMessages();
assertEquals(2, messages.length);

// Simple message
assertEquals(subject, messages[0].getSubject());
assertEquals(body, GreenMailUtil.getBody(messages[0]).trim());

//if you send content as a 2 part multipart...
assertTrue(messages[1].getContent() instanceof MimeMultipart);
MimeMultipart mp = (MimeMultipart) messages[1].getContent();
assertEquals(2, mp.getCount());
assertEquals("body1", GreenMailUtil.getBody(mp.getBodyPart(0)).trim());
assertEquals("body2", GreenMailUtil.getBody(mp.getBodyPart(1)).trim());

greenMail.stop();

Testing your retrieving code


//Start all email servers using non-default ports.
GreenMail greenMail = new GreenMail(ServerSetupTest.ALL);
greenMail.start();

//Use random content to avoid potential residual lingering problems
final String subject = GreenMailUtil.random();
final String body = GreenMailUtil.random();
MimeMessage message = createMimeMessage(subject, body, greenMail); // Construct message
GreenMailUser user = greenMail.setUser("wael@localhost.com", "waelc", "soooosecret");
user.deliver(message);
assertEquals(1, greenMail.getReceivedMessages().length);

// --- Place your retrieve code here
greenMail.stop();

Deploy as a webapp (WAR)

GreenMail Webapp provides a lightweight Java web application wrapping GreenMail mail server.

Like the GreenMail JBoss Service, the usage scenario is a development or test environment where a real mail server is too much overhead. The webapp is application server neutral - you should be able to use it on any JEE application server running und Java 5.

With the GreenMail mail service each developer has its own local mail server sandbox - so there's no danger for accidentally leaking test mails into the Internet.

Deploy the webapp

Simply deploy the webapp like any other Java web application.

For Tomcat, just drop the webapp into $CATALINA_HOME/webapps directory. Alternatively, you can create a $CATALINA_HOME/webapps/greenmail, unpack the WAR here and configure the GreenMail service.

Configure the webapp

You can configure the active mail services and available users by editing WEB-INF/web.xml in the WAR file and modifying the context params. A ServletContextListener starts and stops the GreenMail service when deploying/undeploying.

Context Parameters
Name	Description
greenmail.defaultHostname	The mail server default hostname (defaults to localhost).
greenmail.portOffset	Offset added to the standard mail ports. Default is 10000 (so an activated SMTP service would start up on port 10025).
greenmail.<PROTOCOL>	Starts a server for this mail protocol (using defaultHostname, port offset and default port). Available protocol names include smtp smtps (SMTP via SSL) pop3 pop3s (POP3 via SSL) imap imaps (IMAP via SSL)
greenmail.<PROTOCOL>.host	Optionally overwrites the default host name (localhost).
greenmail.<PROTOCOL>.port	Optionally overwrites the default port and port offset for the given protocol.
greenmail.users	A whitespace/newline/comma separated list of mail users in the form of USER:PWD@DOMAIN.

Have a look at the default web.xml.

Deploy as a JBoss Service (SAR)

GreenMail provides a JBoss Service for easy JBoss integration. The usage scenario is a development or test environment where a real mail server is too much overhead. With the GreenMail mail service each developer has its own local mail server sandbox - so there's no danger for accidentally leaking test mails into the Internet.

GreenMail SAR works only up to JBoss AS 6!

JBoss introduced a not backward compatible change to the SAR MBean deployment in JBoss AS 7+. As alternative, try out the GreenMail WAR deployment.

Deploy the service

Download the current service which we distribute as a JBoss SAR (Service Archive).

Unjar the service to your server deploy directory.

This example uses the default server, where the service is deployed in exploded mode for follow up configuration.


cd ${JBOSS_HOME}/server/default/deploy
mkdir greenmail-jboss-service.sar
cd greenmail-jboss-service.sar
jar xvf /path/to/greenmail-jboss-service-XXX.jar

Starting JBoss will now automatically also start the GreenMail JBoss Service. You can see a startup message on the console output, including basic configuration data like active protocols and their ports:

JBoss console output when deploying GreenMail SAR

Opening the JBoss Console, you can see the GreenMail Service JMX Bean:

You find two entries, of which the second one holds our interest:

loader=greenmail-jboss-service : A loader for isolated class loading inside the JBoss service (as to prevent the greenmail JavaMail to conflict with the application server version).
name=GreenMail,type=service,version=... : The GreenMail service bean for managing GreenMail

Configurable user accounts

The GreenMail service is configured by the file META-INF/jboss-service.xml in the exploded service directory.

Send a mail message via JMX

Open the JBoss JMX Console in your browser (see the deployment picture).
Select the JMX bean of name GreenMail and type service
Invoke the sendMail operation:

The mail should now be visible by listing the user mails, if there is no automatic polling of the mail box.

Send a mail message using your mail client

You can use your favorite mail client if you configure it for GreenMail by setting the outgoing mail to the GreenMail SMTP port. By default this is localhost:3025. Of course you can also read created mail by configuring your mail client to use GreenMail POP3 (localhost:3110) or IMAP (localhost:3143). You will probably have to adjust these settings for your specific configuration.

List mails for a user via JMX

Instead of using your favourite mail client, you can use the JMX GreenMail service for listing all current mails in of a user in the GreenMail server sandbox.

Open your browser with the JMX Console and choose the GreenMail service (see sending mail paragraph)
Enter the user email for the listMailsForUserHTML operation:
Click the invoke button. The browser now shows all emails for the specified user:

Note that displaying mails does not modify the user mail box.

How come I don't have to create any accounts to send/retrieve?

By default GreenMail accepts all incoming emails. If there is no corresponding existing email account, one is automatically created with login and password being the same as the to-address.

What other library dependencies are there?

Check out the Maven POM. Dependencies include

javamail.jar and activation.jar
slf4j-api.jar (for logging)
commons-lang3.jar (for handling encodings)
junit.jar (for test rules)

How come I don't need to install any SSL/TLS related certificates?

GreenMail is designed to be used out of the box with no need to generate, sign or install any certificates into your keystore. GreenMail ships with a builtin keystore with a self signed RSA key. Refer to the source code of DummySSLServerSocketFactory for details.

How can I use IMAP quotas?

GreenMail supports IMAP quota. Quota capbility can be toggled on and off. For details see ImapServerTest.java quota test

Maven Central contains all GreenMail artifacts.

1.4.1 - April 27th, 2015

This version requires JDK 1.6+ and JavaMail 1.5+ .

Name	GAV
GreenMail Core	com.icegreen:greenmail:1.4.1
GreenMail Webapp	com.icegreen:greenmail-webapp:1.4.1:war
GreenMail JBoss Service	com.icegreen:greenmail-jboss-service:1.4.1:jboss-sar
GreenMail Spring	com.icegreen:greenmail-spring:1.4.1

Latest and recommended version is available via Maven repository or as a ZIP from GitHub.

1.4.0 - October 29th, 2014