Documentation

You are viewing the documentation for Play 1. The documentation for Play 2 is here.

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();
email.setFrom("[email protected]");
email.addTo("[email protected]");
email.setSubject("subject");
email.setMsg("Message");
Mail.send(email);

An HTML e-mail:

HtmlEmail email = new HtmlEmail();
email.addTo("[email protected]");
email.setFrom("[email protected]", "Nicolas");
email.setSubject("Test email with inline image");
// embed the image and get the content id
URL url = new URL("http://www.zenexity.fr/wp-content/themes/images/logo.png");
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 org.apache.commons.mail.*; 
import play.*;
import play.mvc.*;
import java.util.*;
 
public class Mails extends Mailer {
 
   public static void welcome(User user) {
      setSubject("Welcome %s", user.name);
      addRecipient(user.email);
      setFrom("Me <[email protected]>");
      EmailAttachment attachment = new EmailAttachment();
      attachment.setDescription("A pdf document");
      attachment.setPath(Play.getFile("rules.pdf").getPath());
      addAttachment(attachment);
      send(user);
   }
 
   public static void lostPassword(User user) {
      String newpassword = user.password;
      setFrom("Robot <[email protected]>");
      setSubject("Your password has been reset");
      addRecipient(user.email);
      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>${user.name}</b>, </p>
...
</html>

The template for the lostPassword method could look like this:

app/views/Mails/lostPassword.html

<html>
<body><head>...</head><body>
<img src="mycompany.com/images"/>
<p>
    Hello ${user.name}, Your new password is <b>${newpassword}</b>.
</p>
</body>
</html>

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 ${user.name},
...

The template for the lostPassword method could look like this:

app/views/Mails/lostPassword.txt

Hello ${user.name},
 
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:

@@{application.index}

If you send mails from Jobs you have to set application.baseUrl to a valid external base URL for your application.

For example, to send an e-mail from a Job running on the playframework.com web site, the configuration would look like this:

application.baseUrl=https://www.playframework.com/

Links to embedded images

The tag use the following parameters:

You can add links to embedded images by using the embeddedImage tag like this:

Distant image:

#{embeddedImage src:'https://www.playframework.com/assets/images/logo.png', name:'distantImage' /}

Locale image:

#{embeddedImage src:'file:///public/images/favicon.png', name:'LocaleImage', alt:'LocaleImage' /}

or:

#{embeddedImage src:'public/images/favicon.png', name:'LocaleImage', alt:'LocaleImage' /}

This will attach the image to the email and create an internal reference inside the the html/text content.

SMTP configuration

E-mail functionality is configured by several mail configuration properties:

Two additional configuration properties let you override default behaviour:

By default, in DEV mode, the e-mail will be printed to the console, while in PROD mode it will be sent to the actual SMTP server. You can change the default behaviour in DEV mode by commenting the following line:

# Default is to use a mock Mailer
mail.smtp=mock

Using Gmail

To use Gmail’s servers, for example when you deploy with playapps, use this configuration: 

mail.smtp.host=smtp.gmail.com
mail.smtp.user=yourGmailLogin
mail.smtp.pass=yourGmailPassword
mail.smtp.channel=ssl

Continuing the discussion

Now we shall move on to Testing the application.