play-mailer 0 editorconfig travis-ci

Play mailer plugin

2 years after

About

:next-branch-uri: https://github.com/playframework/play-mailer/tree/next :playframework-24x-docs-uri: https://www.playframework.com/documentation/2.4.x :runtime-di-uri: {playframework-24x-docs-uri}/ScalaDependencyInjection#Runtime-Dependency-Injection :compile-time-di-uri: {playframework-24x-docs-uri}/ScalaCompileTimeDependencyInjection#Compile-Time-Dependency-Injection

This plugin provides a simple emailer.

//ifdef::env-github[] image:https://travis-ci.org/playframework/play-mailer.svg?branch=master["Travis build status", link="https://travis-ci.org/playframework/play-mailer"] //endif::env-github[]

Setup

NOTE: For Play 2.3.x please read https://github.com/playframework/play-mailer/blob/2.x/README.md#setup[the README on the 2.x branch].

  1. Add a library dependency on play-mailer: +

    "com.typesafe.play" %% "play-mailer" % "{version}"

    + See below for the version matrix.

  2. Configure the mailer in your conf/application.conf: +

    play.mailer {
    host (mandatory)
    port (defaults to 25)
    ssl (defaults to no)
    tls (defaults to no)
    user (optional)
    password (optional)
    debug (defaults to no, to take effect you also need to set the log level to "DEBUG" for the application logger)
    timeout (defaults to 60s in milliseconds)
    connectiontimeout (defaults to 60s in milliseconds)
    mock (defaults to no, will only log all the email properties instead of sending an email)
    }

You can also configure the mailer programmatically, see https://github.com/playframework/play-mailer/blob/master/user-manual.adoc[user manual].

Usage

Java

import play.libs.mailer.Email;
import play.libs.mailer.MailerClient;
import javax.inject.Inject;
import java.io.File;
import org.apache.commons.mail.EmailAttachment;

public class MyComponent {
  @Inject MailerClient mailerClient;

  public void sendEmail() {
    String cid = "1234";
    Email email = new Email()
      .setSubject("Simple email")
      .setFrom("Mister FROM <[email protected]>")
      .addTo("Miss TO <[email protected]>")
      // adds attachment
      .addAttachment("attachment.pdf", new File("/some/path/attachment.pdf"))
      // adds inline attachment from byte array
      .addAttachment("data.txt", "data".getBytes(), "text/plain", "Simple data", EmailAttachment.INLINE)
      // adds cid attachment
      .addAttachment("image.jpg", new File("/some/path/image.jpg"), cid)
      // sends text, HTML or both...
      .setBodyText("A text message")
      .setBodyHtml("<html><body><p>An <b>html</b> message with cid <img src=\"cid:" + cid + "\"></p></body></html>");
    mailerClient.send(email);
  }
}

Scala

You need a MailerClient instance to send an email :

import play.api.libs.mailer._
import java.io.File
import org.apache.commons.mail.EmailAttachment

def sendEmail {
  val cid = "1234"
  val email = Email(
    "Simple email",
    "Mister FROM <[email protected]>",
    Seq("Miss TO <[email protected]>"),
    // adds attachment
    attachments = Seq(
      AttachmentFile("attachment.pdf", new File("/some/path/attachment.pdf")),
      // adds inline attachment from byte array
      AttachmentData("data.txt", "data".getBytes, "text/plain", Some("Simple data"), Some(EmailAttachment.INLINE)),
      // adds cid attachment
      AttachmentFile("image.jpg", new File("/some/path/image.jpg"), contentId = Some(cid))
    ),
    // sends text, HTML or both...
    bodyText = Some("A text message"),
    bodyHtml = Some(s"""<html><body><p>An <b>html</b> message with cid <img src="cid:$cid"></p></body></html>""")
  )
  mailerClient.send(email)
}

Since Play 2.4, you can use {runtime-di-uri}[runtime dependency injection] or {compile-time-di-uri}[compile time dependency injection]. As a result, the MailerClient instance can be obtained using runtime dependency injection or compile time dependency injection.

With runtime injection

Use the @Inject annotation on the constructor of your component or controller:

import play.api.libs.mailer._
import javax.inject.Inject

class MyComponent @Inject() (mailerClient: MailerClient)

[NOTE]

Configuration will be retrieved each time mailerClient.send(email) is called. This means that mailer client will always be up to date if you have a dynamic configuration.

With compile time injection

Declare the MailerClient without the @Inject annotation:

import play.api.libs.mailer._

class MyComponent(mailerClient: MailerClient)

Then in your router definition, use the trait MailerComponents:

import play.api._
import play.api.ApplicationLoader.Context
import router.Routes
import play.api.libs.mailer._

class MyApplicationLoader extends ApplicationLoader {
  def load(context: Context) = {
    new ApplicationComponents(context).application
  }
}

class ApplicationComponents(context: Context) extends BuiltInComponentsFromContext(context) with MailerComponents {
  lazy val myComponent = new MyComponent(mailerClient)
  // create your controllers here ...
  lazy val router = new Routes(...) // inject your controllers here
}

Finally add this line play.application.loader=MyApplicationLoader in application.conf.

Versioning

The Play Mailer plugin supports several different versions of Play.

|=== | Plugin version | Play version

| 5.x | 2.5.x | 4.x | 2.4.x | 3.x | 2.4.x | 2.x | 2.3.x | {next-branch-uri}[next branch] | latest snapshot |===

Current Versions

For Play 2.3:

"com.typesafe.play" %% "play-mailer" % "2.4.1"

For Play 2.4:

"com.typesafe.play" %% "play-mailer" % "4.0.0"

For Play 2.5:

"com.typesafe.play" %% "play-mailer" % "5.0.0"

Licence

This software is licensed under the Apache 2 license, quoted below.

Copyright 2012 Typesafe (http://www.typesafe.com).

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Related Repositories

ruby-style-guide

ruby-style-guide

A community-driven Ruby coding style guide ...

play-authenticate

play-authenticate

An authentication plugin for Play Framework 2.x (Java) ...

PlayStartApp

PlayStartApp

Starting APP Play Framework 2.x with Signup, Signin, Reset password, Change Emai ...

ruby-style-guide

ruby-style-guide

A community-driven Ruby coding style guide ...

Play-with-deadbolt-securesocial-reactivemongo-mailer

Play-with-deadbolt-securesocial-reactivemongo-mailer

Play 2.2.0 with Securesocial, Deadbolt-2-scala, Play-reactivemongo, Play-salat, ...


Top Contributors

pk11 jroper Mogztter mkurz benmccann freekh gmethvin Ne-Lexa tsuyoshizawa schmitch nraychaudhuri eirslett loicdescotte prettynatty techmag stephenmuss alirussell chafikhnini dylex dspasojevic divarvel ekamaras erwan hermanbanken iain-logan jmparsons joscha twistedpair kevinbosman laszlovandenhoek

Releases

-   5.0.0 zip tar
-   5.0.0-M1 zip tar
-   4.0.0 zip tar
-   4.0.0-M1 zip tar
-   3.0.1 zip tar
-   3.0.0 zip tar
-   3.0.0-RC1 zip tar
-   3.0.0-M1 zip tar
-   2.4.1 zip tar
-   2.4.0 zip tar
-   2.4.0-RC1 zip tar
-   2.3.1 zip tar