Edit

Introduction

mailo is a library that allows you to:

  • Store your email templates where you like.
  • Send your email with the ESP you like.
  • Compose your template using HTML partials (convenient for footers and headers).
    • Allowed chars in the names of the partials are given by the following regex a-zA-Z0-9_.-
  • Conveniently collect errors.

Getting started

First, you need to obtain a instance of Mailo, here's an example:

import akka.actor.ActorSystem

import mailo.Mailo
import mailo.data.S3MailData
import mailo.http.MailgunClient

import scala.concurrent.ExecutionContext.Implicits.global


implicit val system = ActorSystem()
// system: ActorSystem = akka://default

val s3 = new S3MailData()
// s3: S3MailData = mailo.data.S3MailData@732da637
val mailgun = new MailgunClient()
// mailgun: MailgunClient = mailo.http.MailgunClient@122395c5

val mailer = Mailo(s3, mailgun)
// mailer: Mailo with com.typesafe.scalalogging.LazyLogging = mailo.AtMostOnceMailo@47660e00

Then you can send an email like so:

import mailo.Mail

mailer.send(
  Mail(
    to = "recipient@mail.com",
    from = "Mailo sender@mail.com",
    templateName = "mail.html",
    subject = "Test mail",
    params = Map("hi" -> "Hello this is your first email! :D"),
    tags = List("test")
  )
)

Templates

Use double curly breakets for parameters {{parameter}}, remember to include parameters in params argument.

Use double square breakets for partials [[partial.html]]. Mailo looks for partials in partials folder.

Complete example:

[[header.html]] Hello {{personFirstName}} {{personLastName}} [[footer.html]]

How to send attachments

Mailo provide a case class Attachment that is used to send attachments in emails. Attachment case class is defined as:

import akka.http.scaladsl.model.ContentType

case class Attachment(
  name: String,
  `type`: ContentType,
  content: String
)

An attachment can be created as follows:

import akka.http.scaladsl.model.MediaTypes._
import akka.http.scaladsl.model.HttpCharsets._
import mailo.Attachment

val attachment = Attachment(name = "test.txt", content="test", `type`=`text/plain` withCharset `UTF-8`)
// attachment: Attachment = Attachment(
//   name = "test.txt",
//   type = WithCharset(
//     mediaType = text/plain,
//     charset = HttpCharset(value = "UTF-8")
//   ),
//   content = "test",
//   transferEncoding = None
// )

And sent as:

import mailo.Mail

mailer.send(
  Mail(
    to = "recipient@mail.com",
    from = "Mailo sender@mail.com",
    cc = Some("ccrecipient@mail.com"),
    bcc = Some("bccrecipient@mail.com"),
    subject = "Test mail",
    templateName = "mail.html",
    params = Map("ciao" -> "CIAOOOONE"),
    attachments = List(attachment),
    tags = List("test")
  )
)

Content-Transfer-Encoding

You can specify add a Content-Transfer-Encoding header in the attachments as follows.

val attachment = Attachment(
  name = "test.pdf",
  content="<<base64pdf>>",
  `type`=`application/pdf`,
  transferEncoding = Some("base64")
)
// attachment: Attachment = Attachment(
//   name = "test.pdf",
//   type = Binary(mediaType = application/pdf),
//   content = "<<base64pdf>>",
//   transferEncoding = Some(value = "base64")
// )

Templates caching

Since version 0.1.5 templates are cached. You can set caching TTL (time to live) in the application.conf as mailo.cachingTTLSeconds: 30.

Installation →