Travis-CI Build Status codecov.io

Sometimes we need to send out email messages based on the results of automated analysis processes. The blastula package makes it easy to send out HTML emails from R that are a little bit easier on the eyes. In doing so we can take advantage of both Markdown and R code when composing our email text.

Installation Requirements

The CRAN version of blastula requires that the rJava and mailR package are installed. A system requirement for rJava is that the Java JRE is installed on the system.

The development version of blastula (installed via devtools::install_github("rich-iannone/blastula")) doesn’t require rJava or mailR to be installed. Instead, there is a requirement for openssl.

On OS X, it is recommended that homebrew be used to install openssl:

brew install openssl

On RHEL, Fedora, or CentOS, openssl-devel is necessary:

sudo yum install openssl-devel

With Ubuntu or Debian, we need libssl-dev:

sudo apt-get install -y libssl-dev

Sending an email message

Here’s an example that shows a basic workflow for composing the message, previewing the content, creating optional on-disk credentials for email, and sending out the message.

These four functions can help us do just that:

Some helper functions allow for easy insertion of HTML fragments into the message body. These are:

When you compose an email, you can put character objects from the global workspace into the message content. Here, I’ll create a nicely formatted date/time string (current_date_time) with the package’s add_readable_time() function, and, assign a link to an web image to an object (img_link).

library(magrittr)

# Get a nicely formatted date/time string
current_date_time <- add_readable_time()

# Assign a very long image URL to `img_link`
img_link <-
  "https://marketplace.canva.com/MAA_AbacFmo/2/0/thumbnail_large/canva-basic-good-vibes-email-header-MAA_AbacFmo.jpg"

Now, we can use the compose_email() to compose the email! There are two main arguments here, body and footer. You can supply markdown text to each of these. So things like ##, links, tables, and all other valid markdown conventions should render to valid HTML.

Furthermore, string interpolation is possible and it works by enclosing valid R code inside of curly braces ({...}). Below the image URL (as part of the ![...](...) markdown link contruction) is referenced to the img_link object from the global workspace. Note also that {current_date_time} references a character object that took quite a few piped statements of R to generate. The end result is the date/time string being nicely inserted in the footer of the email without complicating the compose_email() function call itself with lots of R statements.

We can also supply variables in the compose_email() function directly. For example, the {sender} part references an object not in the global workspace but rather it refers the named argument sender = "Mike" in the function call. (The order of searching is from within the function first, then the search moves to variables in the global environment.)

library(blastula)

email_object <-
  compose_email(
    body = "
  ## Hiya! This is an email message. Exciting Right?
  Enjoy it. And this here image:

  ![The alt text]({img_link} \"The title\")
      
  **Yeah!** I seriously hope that you enjoy this \\
  message and the good vibes it will bring to you \\
  and yours.
  
  Peace out,

  {sender}",
    footer = 
  "Brought to you by Smile AG on {current_date_time}",
    sender = "Mike")

Some more notes on style are useful here. The \\ is a helpful line continuation marker. It’ll help you break long lines up when composing but won’t introduce line breaks or new paragraphs. I recommend formatting like above with few indents so as not to induce the quote-type formatting. Any literal quotation marks should be escaped using a single \. Blank lines separating blocks of text result in new paragraphs. And, again, any valid R code can be enclosed inside {...} (e.g., {Sys.Date()}).

After creating the email message, you’ll most certainly want to look at it to ensure that the formatting is what you want it to be. This is done with the preview_email() function. It’s easy to use!

library(blastula)

# Preview the email
preview_email(email = email_object)

…and this is what I saw: