blastula

Overview

The blastula package makes it easy to produce and send HTML email from R. The message can have three content areas (the body, the header, and the footer) and we can insert Markdown text, R expressions, block-based components, and even some raw HTML. The underlying HTML/CSS is meant to display properly across a wide range of email clients and webmail services. The resulting email message is responsive so it’ll look great on computers and mobile devices.

An Example

Composing an Email Message

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

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

# Assign an URL with an image to `img_link`
img_link <- "https://i.imgur.com/p1KvgYj.png"

Now we use the compose_email() function to compose the email. There are three main arguments here: body, header, and footer. You can supply Markdown text to any of these content areas to get rendered HTML.

The insertion of text can be performed by enclosing valid R code inside of curly braces ({...}). In the example code 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. 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.)

# Generate the body text for the email message
email_text <- 
"
Hello,

This is a great photo of Lake Tahoe. I took \\
it using my new camera.

![]({img_link})
      
You *should go* if you get the chance.
"

email_object <-
  compose_email(
    body = email_text,
    footer = 
      "Email sent on {current_date_time}."
  )

After creating the email message, we can look at it to ensure that the formatting is as expected. Simply call the object itself and it will be displayed in the Viewer.

# Preview the email
email_object

Sending an Email Message via SMTP

We can store SMTP email credentials in a file using the create_email_creds_file() function. This will create a hidden credentials file in the working directory. Having generated the credentials file, we can use the smtp_send() function to send the email.

# Sending email by SMTP using a credentials file
smtp_send(
  email = email_object,
  from = "personal@email.net",
  to = "another_user@web.net",
  subject = "Testing the `smtp_send()` function",
  creds_file = ".email_creds"
)

Installation

The blastula package is moving toward using a new binary for smtp mailing, provided by the mailsend-go project. This binary is cross-platform and works on Windows, macOS (via Homebrew), and Linux (Debian and RPM packages). Information on installation and other important considerations for SMTP sending can be found in this article.

You can install the in-development version of blastula from GitHub using the remotes package.

install.packages("devtools")
remotes::install_github("rich-iannone/blastula")

If you encounter a bug, have usage questions, or want to share ideas to make this package better, feel free to file an issue.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

kuzmenkov111 / blastula