Sending e-mail

E-mail functionality uses the Apache Commons Email library under the hood. You can use the play.libs.Mail utility class to send e-mail very easily.

A simple e-mail:

SimpleEmail email = new SimpleEmail();

An HTML e-mail:

HtmlEmail email = new HtmlEmail();
email.setFrom(", "Nicolas");
email.setSubject("Test email with inline image");
// embed the image and get the content id
URL url = new URL("");
String cid = email.embed(url, "Zenexity logo");
// set the html message
email.setHtmlMsg("<html>Zenexity logo - <img src=\"cid:"+cid+"\"></html>");
// set the alternative message
email.setTextMsg("Your email client does not support HTML, too bad :(");

For more information see the Commons Email documentation.

Mail and MVC integration

You can also send complex, dynamic e-mail using the standard templates mechanism and syntax.

First, define a Mailer notifier in your application. Your mailer notifier must subclass play.mvc.Mailer and be part of the notifiers package.

Each public static method will be an e-mail sender, in a similar manner as actions for an MVC controller. For example:

package notifiers;
import play.*;
import play.mvc.*;
import java.util.*;
public class Mails extends Mailer {
   public static void welcome(User user) {
      setSubject("Welcome %s",;
      setFrom("Me <>");
      EmailAttachment attachment = new EmailAttachment();
      attachment.setDescription("A pdf document");
   public static void lostPassword(User user) {
      String newpassword = user.password;
      setFrom("Robot <>");
      setSubject("Your password has been reset");
      send(user, newpassword);

text/html e-mail

The send method call will render the app/views/Mails/welcome.html template as the e-mail message body.

<html><body><p>Welcome <b>${}</b>, </p>

The template for the lostPassword method could look like this:


<img src=""/>
    Hello ${}, Your new password is <b>${newpassword}</b>.

text/plain e-mail

If no HTML template is defined, then a text/plain e-mail is sent using the text template.

The send method call will render the app/views/Mails/welcome.txt template as the e-mail message body.

Welcome ${},

The template for the lostPassword method could look like this:


Hello ${},
Your new password is ${newpassword}.

text/html e-mail with text/plain alternative

If an HTML template is defined and a text template exists, then the text template will be used as an alternative message. In our previous example, if both app/views/Mails/lostPassword.html and app/views/Mails/lostPassword.txt are defined, then the e-mail will be sent in text/html as defined in lostPassword.html with an alternative part as defined in lostPassword.txt. So you can send nice HMTL e-mail to your friends and still please those geeky friends that still use mutt ;)

Links to your application in e-mail

Your can include links to your application in e-mails like this:


If you send mails from Jobs you have to configure application.baseUrl in application.conf.
application.baseUrl must be a valid external baseurl to your application.

If the website where to send you an e-mail from inside a Job, its configuration
would look like this:


SMTP configuration

E-mail functionality is configured in your application’s conf/application.conf file. First of all, you need to define the SMTP server to use:

If your SMTP server requires authentication, use the following properties:


Channel & ports

There are two ways to send the e-mail over an encrypted channel. If your server supports the starttls command (see: RFC 2487), you can use a clear connection on port 25 that will switch to SSL/TLS. You can do so by adding this configuration option:

Your server may also provide a SMTP-over-SSL (SMTPS) connector, that is an SSL socket listening on port 465. In that case, you tell Play to use this setup using the configuration option:

More about configuration

Under the hood, Play uses JavaMail to perform the actual SMTP transactions. If you need to see what’s going on, try:


When using SSL connections with JavaMail, the default SSL behavior is to drop the connection if the remote server certificate is not signed by a root certificate. This is the case in particular when using a self-signed certificate. Play’s default behavior is to skip that check. You can control this using the following property:


If you need to connect to servers using non-standard ports, the following property will override the defaults:


Using Gmail

To use Gmail’s servers, use this configuration:

Continuing the discussion

Now we shall move on to Testing the application.