Documentation

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

Sending emails with play

You can use the play.libs.Mail utility to send emails very easily:

Mail.send("[email protected]","[email protected]","Subject","Message");

Mail and MVC integration

You can also send complex, dynamic emails 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 email sender, in a similar manner as actions for a 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", user.name);
      addRecipient(user.email);
      addFrom("Me <[email protected]>");
      addAttachment(Play.getFile("rules.pdf"));
      send(user);
   }
 
   public static void lostPassword(User user) {
      String newpassword = user.password;
      addFrom("Robot <[email protected]>");
      setSubject("Your password has been reset");
      addRecipient(user.email);
      send(user, newpassword);
   }
 
}

text/html email

The send call will render the app/views/Mails/welcome.html template as the body of the email message.

<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},<br/>
Your new password is <b>${newpassword}</b>.
</p>
</body>
</html>

text/plain email

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

The send call will render the app/views/Mails/welcome.txt template as the body of the email message.

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 email 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 email 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 emails to your friends and still please those geeky friends that still use mutt ;)

SMTP configuration

First of all, you need to define the smtp server to use:

mail.smtp.host=smtp.taldius.net

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

mail.smtp.user=jfp
mail.smtp.pass=topsecret

Channel & ports

There are two ways to send the email 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:

mail.smtp.channel=starttls

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

mail.smtp.channel=ssl

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:

mail.debug=true

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:

mail.smtp.socketFactory.class

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

mail.smtp.port=2500

Using Gmail

To use gmail’s servers, use this configuration:

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