JarCastingplay2-mailgun
Features:
- Requires no extra dependencies (uses Play Framework libraries only)
- Super-easy to wire in (just add two values to
application.conf) - Send plain-text and/or HTML emails with the one Twirl template (not finished yet)
Installation
Add the release repository
Add the following to your build.sbt:
resolvers ++= Seq(
"Millhouse Bintray" at "http://dl.bintray.com/themillhousegroup/maven"
)
Pick the right version for your Play app
There are versions available for Play 2.3 to 2.5.
If you are on Play 2.5, you'll need to use the latest from the 0.3.x family, as shown below:
libraryDependencies ++= Seq(
"com.themillhousegroup" %% "play2-mailgun" % "0.3.284"
)
Development of new features for the Play 2.3/4 has stopped, but the library is still available and works well. Bugfixes (where applicable) from master are backported to the 0.2.x family (i.e. Play 2.4). Just substitute the appropriate version number in the above specifier:
- For Play 2.3 the version you want is
0.1.256 - For Play 2.4 the version you want is
0.2.285
Usage
Once you have play2-mailgun added to your project, you can start using it like this:
Put your Mailgun credentials into application.conf
You need the following two entries:
mailgun.api.key=key-abcdef123456abcdef123456abc12345
mailgun.api.url="https://api.mailgun.net/v3/mg.example.com/messages"
Build an EmailMessage containing your email content
Supply plain text and HTML versions of your message:
import com.themillhousegroup.play2.mailgun.EmailMessage
import play.twirl.api.Html
val plainText = "This is the plain text"
val html = Html("<h5>This is <em>actual</em> <strong>HTML!</strong></h5>")
val m = EmailMessage(
Some("[email protected]"),
"[email protected]",
"This is the subject",
plainText,
html
)
Sender addressing
You might have noticed the first argument to EmailMessage was Some("[email protected]") - if you want emails to come from different senders depending on context, you should pass the sender's email address in like this.
If your requirements are simpler, and you just have a global email address that all emails should "come from" (like a [email protected] or similar) then you can simply set that in your application.conf as follows:
mailgun.default.sender="[email protected]"
And then just pass None as the first argument to EmailMessage() - you can still override it on a case-by-case basis if necessary.
Pass the EmailMessage to MailgunEmailService.send()
It returns a Future[MailgunResponse] (which you can ignore if you don't care):
Play 2.3 static-object style:
import cn.playalot.play2.mailgun.MailgunEmailService
...
MailgunEmailService.send(m).map { mailgunResponse =>
s"id: ${mailgunResponse.id} - message: ${mailgunResponse.message}"
}
Play 2.4+ dependency-injected style:
import play.api.mvc._
import com.google.inject.Inject
import cn.playalot.play2.mailgun.MailgunEmailService
class MyController @Inject() (val emailService:MailgunEmailService) extends Controller {
...
emailService.send(m).map { mailgunResponse =>
s"id: ${mailgunResponse.id} - message: ${mailgunResponse.message}"
}
...
}
You can of course use the MailgunEmailService in static style, but it's more in keeping with the Play 2.4+ philosophy to inject this dependency.
Advanced Usage
Sending to multiple recipients
Use a MulticastEmailMessage instance instead of an EmailMessage - it gives you the opportunity to specify multiple To, CC and BCC recipients
import com.themillhousegroup.play2.mailgun.MulticastEmailMessage
import play.twirl.api.Html
val multiEmail = MulticastEmailMessage(
None,
None,
Seq("[email protected]", "[email protected]"),
Seq("[email protected]", "[email protected]"),
Seq("[email protected]", "[email protected]"),
subject,
plainText,
html
)
You can then pass your MulticastEmailMessage to the MailgunEmailService as before.
Using a custom Reply-To address
Use a MulticastEmailMessage as above, and set the second parameter to a Some. If you don't need multiple recipients, just create a Seq around the single recipient, or use Nil as required:
import com.themillhousegroup.play2.mailgun.MulticastEmailMessage
import play.twirl.api.Html
val replyToEmail = MulticastEmailMessage(
None,
Some("[email protected]"),
Seq("[email protected]"),
Nil, // No CCs
Nil, // No BCCs
subject,
plainText,
html
)
Still To-Do
Use one custom template (with .scala.email extension) to define both plain text and HTML message bodies.
