blastula: An R repository from ccg

Sometimes we need to send out email messages based on the results of automated analytical processes. The blastula package makes it easy to send out HTML emails from R that are 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 blastula package requires the availability of 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:

compose_email(): generates the email message content inside the email_message-class object
preview_email(): makes the email message created by compose_email() viewable in the RStudio Viewer
send_email_out(): sends the HTML-based email to one or more recipients
create_email_creds_file(): generates an optional on-disk file with email credentials

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

add_image(): with a local image file, insert it into message (it resizes the image to fit the content area)
add_readable_time(): adds the current time as a nicely readable string.
add_cta_button(): add a call-to-action (CTA) button with button text and a link
add_ggplot(): add a ggplot plot object as an inline image

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 a 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. All other valid markdown conventions should render to valid HTML.

The insertion of HTML fragments or text can be performed by enclosing valid R code inside of curly braces ({...}). Below the image URL (as part of the ![...](...) markdown link construction) is referenced to the img_link object from the global workspace. Note also that {current_date_time} references the current_date_time character object generated earlier via the add_readable_time() function. The end result is the insertion of the date/time string into the footer of the email. (Alternatively, add_readable_time() could have been called directly.)

We can also supply variables in the compose_email() function directly. For example, the {sender} part references an object not in the global workspace. 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.

library(blastula)

# Preview the email
preview_email(email = email_object)

…and this is what I saw:

I’d previously set up my email credentials in a file using the create_email_creds_file() function. Here’s an example of how one might create a creds file as a hidden file in the home directory (~).

# Create a credentials file to facilitate
# the sending of email messages
create_email_creds_file(
  user = "have_a@blastula.org",
  password = "<user_password>",
  host = "smtp.blastula.org",
  port = 465,
  sender = "correspondences@blastula.org",
  creds_file_name = "~/.e_creds")

You can also use preset SMTP settings. For example, if you’d like to send email through Gmail, we can supply provider = gmail to not have to worry about SMTP settings:

# Create a credentials file for sending
# email through Gmail
create_email_creds_file(
  user = "user_name@gmail.com",
  password = "<user_password>",
  provider = "gmail",
  sender = "Sender Name")

This will create a hidden credentials file in the working directory, the name of which is based on the provider (you can optionally specify the name with the creds_file_name argument, as in the first example).

One additional note about using Gmail to send out email: you must first change account settings to let less secure apps use your account. Details on how to make this account-level change can be found in this support document.

Having generated that file, you can use the send_email_out() function to send the email. I sent the email just to myself but do note that the to argument can accept a vector of email addresses for mass mailings. Alternatively, one can set a number of environment variables and use Sys.getenv() calls for email credentials arguments in the send_email_out() statement.

library(blastula)

# Sending email using a credentials file
send_email_out(
  message = email_object,
  from = "mike@smile.de",
  to = "riannone@me.com",
  subject = "This is NOT junk mail.",
  creds_file = "~/.e_creds")
  
# Sending email using environment variables
send_email_out(
  message = email_object,
  from = "mike@smile.de",
  to = "riannone@me.com",
  subject = "This is NOT junk mail.",
  sender = Sys.getenv("BLS_SENDER"),
  host = Sys.getenv("BLS_HOST"),
  port = Sys.getenv("BLS_PORT"),
  user = Sys.getenv("BLS_USER_NAME"),
  password = Sys.getenv("BLS_PASSWORD"))

This is how the message appeared when received in the email client:

The underlying HTML/CSS is meant to display properly across a wide range of email clients and webmail services.

Adding a table to an email message

You can add HTML tables to the message. Here’s an example using a formattable table generated via its format_table() function.

library(blastula)
library(formattable)

# Create a data frame
df <- data.frame(
  id = 1:10,
  name = c("Bob", "Ashley", "James", "David", "Jenny", 
           "Hans", "Leo", "John", "Emily", "Lee"), 
  age = c(28, 27, 30, 28, 29, 29, 27, 27, 31, 30),
  grade = c("C", "A", "A", "C", "B", "B", "B", "A", "C", "C"),
  test1_score = c(8.9, 9.5, 9.6, 8.9, 9.1, 9.3, 9.3, 9.9, 8.5, 8.6),
  test2_score = c(9.1, 9.1, 9.2, 9.1, 8.9, 8.5, 9.2, 9.3, 9.1, 8.8),
  final_score = c(9, 9.3, 9.4, 9, 9, 8.9, 9.25, 9.6, 8.8, 8.7),
  registered = c(TRUE, FALSE, TRUE, FALSE, TRUE, TRUE, TRUE, FALSE, FALSE, FALSE),
  stringsAsFactors = FALSE)

# Create an HTML table with `format_table()`
formatted_table <-
  format_table(
    x = df,
    list(
      age = color_tile("white", "orange"),
      grade = 
        formatter(
          "span",
          style = x ~ ifelse(
            x == "A", 
            style(color = "green", font.weight = "bold"), NA)), 
      area(col = c(test1_score, test2_score)) ~ normalize_bar("pink", 0.2),
      final_score = 
        formatter(
          "span",
          style = x ~ style(color = ifelse(rank(-x) <= 3, "green", "gray")),
          x ~ sprintf("%.2f (rank: %02d)", x, rank(-x))),
      registered = 
        formatter(
          "span",
          style = x ~ style(color = ifelse(x, "green", "red")),
          x ~ icontext(ifelse(x, "ok", "remove"), ifelse(x, "Yes", "No")))
    ))
    
# Create and preview the email message
compose_email(
  body = "
  Hello,

  Here are the grades you've been hounding me \\
  for all this past week. Overall, everyone did \\
  quite well. I'm impressed.

  {formatted_table}
  <br />
  Cheers,<br />The grader") %>%
  preview_email()