Sending e-mails with {blastula}

We send out mails from within R using the {blastula} package.

E-mails are a surprisingly effective tool to

• send out recurring reports/stats,
• alert people that a long-running job finished,
• or simply contact customers or other departments with user-specific information.

So in today’s video, I’m going to show you how the {blastula} package makes all of that possible for you. Let’s dive in.

Creating an email

The first thing you need to do is to compose an email. {blastula} gives you the compose_email() function for that. And for you convenience you can use Markdown notation using the md() function.

library(blastula)
compose_email(
  body = md(
  "Hi there 👋,
  
  This is an email to let you now that - **hooooray** 🥳 - your long running job **finished**.

  Best,<br>
  Albert"
  )
)

If you run this, you’ll see that the HTML email message is displayed in RStudio’s viewer window.

Filling the email with data

Now as I said, e-mails could also contain some key data for stakeholders or customers. So, let’s create a fake dataset to simulate that:

dat_running <- tibble::tibble(
  job_name = 'My cool job',
  job_started = lubridate::now() - lubridate::minutes(57),
  job_ended = lubridate::now(),
  job_time = lubridate::interval(job_started, job_ended) /
    lubridate::minutes(1)
)
dat_running
## # A tibble: 1 × 4
##   job_name    job_started         job_ended           job_time
##   <chr>       <dttm>              <dttm>                 <dbl>
## 1 My cool job 2025-01-18 19:53:19 2025-01-18 20:50:19     57.0

Then, we can assemble an HTML table, e.g. with {gt}.

library(gt)
## 
## Attaching package: 'gt'
## The following object is masked from 'package:blastula':
## 
##     md
tbl <- gt(dat_running) |> 
  fmt_datetime(columns = 2:3) |> 
  fmt_duration(
    columns = job_time, 
    input_units = 'minutes'
  )
tbl

job_name	job_started	job_ended	job_time
My cool job	2025-01-18 19:53:19	2025-01-18 20:50:19	57m

And then we can stick everything together with glue(). Just make sure to convert your {gt} table to raw html.

msg <- compose_email(
  body = md(
    glue::glue(
       "Hi there 👋,
  
      This is an email to let you now that - **hooooray** 🥳 - your long running job **finished**. 
      Here is some data on your long running job:
      
      {tbl |> gt::as_raw_html()}
    
      Best,<br>
      Albert"
    )
  )
)
msg

Get email credentials

Nice. We have a semi-good-lookin’ email. Let’s send that to someone. For that, we have to create “smtp credentials” first.

There are multiple ways to do that. You can

• create a credentials file with create_smtp_creds_file(),
• store credentials in your computer’s key-value vault with create_smtp_creds_key(), or
• retrieve your passwort using environment variables with creds_envvar().

They all work pretty much the same but here we will go for the one that uses environment variables. This one is the easiest to implement.

If you’re using gmail, outlook or office365 as your email provider, then it’s particularly simple. You’ll just have to provide creds_envvar() with

• your user name (typically e-mail),
• the name of the env-variable that stores your password, and
• your provider.

In this case, I’m using gmail as a provider and I store my password in a variable called SMTP_PASSWORD.

my_email_creds <- creds_envvar(
  user = Sys.getenv('MY_GMAIL_ACCOUNT'),
  pass_envvar = 'SMTP_PASSWORD', 
  provider = 'gmail'
)

Here, I’m also using an env-variable for my e-mail but that’s purely optional. Also, it is worth noting that for gmails you cannot use your regular password. You will have to create a designated app password.

Sending out the email

Finally, sending out the email is pretty straightforward. Just take your output of compose_email() and pass it to smtp_send(). But don’t forget to include the credentials we’ve just created.

msg |> 
  smtp_send(
    from = Sys.getenv('MY_GMAIL_ACCOUNT'),
    to = "info@albert-rapp.de",
    subject = "Testing the `smtp_send()` function",
    credentials = my_email_creds
  )
## The email message was sent successfully.