How to send emails with graphics from R

How do you share your R analyses with others? R Markdown is one good way, because it’s easy to mix text narrative, calculation results, and graphics. But how do you share your R Markdown documents with colleagues?

You might post them somewhere, email them as attachments, or use RStudio Connect (a commercial product) to share them. Or, you can turn an R Markdown document into an email message, and send it in the body of your email, right from R – ggplot graphs included. That’s thanks to the blastula package from RStudio.

Here’s how it works.

First, not surprisingly, install and load the package with install.packages("blastula") or remotes::install_github("rstudio/blastula").

Create an email message with blastula

There are two ways to create an email with blastula. My favorite is to start with an R Markdown document. Use blastula::blastula_email as the output format, make sure to include a title, and you’re ready to go. The other way is to use blastula’s compose_email() function, which requires more manual coding for more than a simple text email. For this demo, I’ll use R Markdown.

I suggest creating an empty document in RStudio by going to File > New File > R Markdown and clicking on the Create Empty Document button.

For the YAML at the top, a document title and email output format is required, like this:

---
title: My Email Title
output: blastula::blastula_email
---

Then create an R Markdown document as usual. Note that HTML widgets won’t work — the emails won’t run JavaScript. However, ggplot works fine, as in this sample document:

---
title: Useful graph!
output: blastula::blastula_email
---
Greetings all! I wanted to show you this graph.
If I had more to say, I could use formatting like _italics_ and **bold**. HTML css works, too, such as <span style='color:red;'>changing font color</span>.
```{r echo = FALSE}
library(ggplot2)
ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point() + 
  ggtitle("MPG by Weight")
```

You can preview what it looks like the usual way, by clicking the knit button in RStudio.

Next, save your .Rmd document to a blastula email object with blastula’s render_email() function, such as

library(blastula)
my_email_object <- render_email('blastula_test.Rmd')

You can preview the email object with print(my_email_object). If you check the object’s class with class(my_email_object), you should see

"blastula_message" "email_message" 

Send your email message from R

Now it’s time to send the email.

To do this, you need access to an SMTP server. Outlook, Gmail, and many other email services use SMTP. But to use blastula, you need access to send mail programmatically through that server. Depending on security settings, you may not have that access — especially at work.

If you want to use a personal Gmail account, you have to set your account to allow what Google considers “less secure” apps to access it. I don’t recommend doing this for a primary Google account that has sensitive information.

For a secondary or otherwise unimportant account, go to Manage your Google Account > Security and scroll down to where it says “Less secure app access.” You’ll be warned not to do this. (And with good reason. I turned this setting back off after writing this article.)

You can save your Gmail user name and server settings with blastula’s create_smtp_creds_key() function. This saves your user name and provider server settings, and you’ll be asked to enter your password.

Here’s the format for the smtp_send() function incuding those saved credentials:

  smtp_send(my_email_object,
    from = "username@gmail.com",
    to = "username@domain.com",
    subject = "Your email subject",
    credentials = creds_key("gmail")
  )

And there you have it — an easy way to share your R analysis with others. You can see it all in action in the video embedded at the top of this page.

For more R tips and tutorials, head to my Do More With R page.