h1. Sending e-mail

E-mail functionality uses the "Apache Commons Email":http://commons.apache.org/email/userguide.html library under the hood. You can use the @play.libs.Mail@ utility class to send e-mail very easily.

A simple e-mail:

bc. SimpleEmail email = new SimpleEmail();
email.setFrom("sender@zenexity.fr");
email.addTo("recipient@zenexity.fr");
email.setSubject("subject");
email.setMsg("Message");
Mail.send(email); 

An HTML e-mail:

bc. HtmlEmail email = new HtmlEmail();
email.addTo("info@lunatech.com");
email.setFrom("sender@lunatech.com", "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":http://commons.apache.org/email/userguide.html.

h2. <a name="mvc">Mail and MVC integration</a>

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:

bc. 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 <me@me.com>");
      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 <robot@thecompany.com>");
      setSubject("Your password has been reset");
      addRecipient(user.email);
      send(user, newpassword);
   }
 
}

h3. text/html e-mail 

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

bc. <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@

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

h3. 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.

bc. Welcome ${user.name},
...

The template for the lostPassword method could look like this:

@app/views/Mails/lostPassword.txt@

bc. Hello ${user.name},
 
Your new password is ${newpassword}.

h3. 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 ;)

h3. Links to your application in e-mail

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

bc. @@{application.index}

If you send mails from Jobs you have to set "application.baseUrl":configuration#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:

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

h3. Links to embedded images

The tag use the following parameters:

* @src@ url/path to the image
* Optional @name@ name of the attach image file (so must be unique for a given image)
* Optional arguments can be added (alt, class,...)

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

Distant image:

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

Locale image:

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

or:

bc. #{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.

h2. <a name="smtp">SMTP configuration</a>

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

* SMTP server - "mail.smtp.host":configuration#mail.smtp.host
* SMTP server authentication - "mail.smtp.user":configuration#mail.smtp.user and "mail.smtp.pass":configuration#mail.smtp.pass
* encrypted channel - "mail.smtp.channel":configuration#mail.smtp.channel
* JavaMail SMTP transaction logging - "mail.debug":configuration#mail.debug.

Two additional configuration properties let you override default behaviour:

* "mail.smtp.socketFactory.class":configuration#mail.smtp.socketFactory.class
* "mail.smtp.port":configuration#mail.smtp.port


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:

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


h3. <a name="gmail">Using Gmail</a>

To use Gmail’s servers, for example when you deploy with "playapps":https://www.playframework.com/modules/playapps, use this configuration: 

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

p(note). **Continuing the discussion**
 
Now we shall move on to %(next)"Testing the application":test%.
