Sending Email Using SMTP • blastula

After we create the an email_message object with compose_email(), we can choose to send it through an SMTP server using blastula’s smtp_send() function. There is some system setup required before sending a blastula email message via SMTP. The main considerations are:

modifying an account-level setting on Gmail (if using that for sending email)
optionally storing SMTP server and auth settings on disk

We’ll go through each of these setup steps before getting into several sending examples with smtp_send().

Requirement for Using Gmail

To use blastula with Gmail you will need to have an app password created for your Gmail account. An app password is a password generated by Google for the purpose of verifying an external app rather than using your standard password. Emails sent with only your standard password pair will be rejected by Google for security purposes. Note that to create an app password you will also need two factor authentication enabled for your account. To create an app password, follow the steps on the Google Account Help page Sign in with App Passwords.

Note: Previous versions of this document provided directions for using the Less Secure Apps setting in Gmail to allow sending blastula emails from Gmail accounts. The Less Secure Apps setting has a sunset date of May 30, 2022 and the previous method will no longer work after that date. Any existing R code using blastula will need to be updated to use this new app password method.

Storing Credentials and SMTP Configuration Data for Later Use

While we can provide SMTP login and configuration information directly whenever we send email, it can be convenient to store this data for easy retrieval. It should be noted that the manually specifying credentials is more secure since no sensitive information is ever stored on disk (and password entry is obscured). Should you want to store credentials on-disk, however, there are two methods available for this:

Storing credentials in the system’s key-value store
Storing credentials in a file

The first method is more secure since access to the system-wide key-value store requires authentication. The second is less secure since it is the user’s responsibility to manage the resulting human-readable JSON file. We’ll provide examples on how to use the both options effectively.

We can store email credentials in the system key-value store with the create_smtp_creds_key() function. Here is an example showing how to create an entry with an id of "gmail_creds".

# Store SMTP credentials using the
# system's secure key-value store;
# provide the `id` of "gmail"
create_smtp_creds_key(
  id = "gmail",
  user = "user_name@gmail.com",
  host = "smtp.gmail.com",
  port = 465,
  use_ssl = TRUE
)

When executing this function, there will always be a prompt for the password (i.e., there is no password argument in this function).

We can also use preset SMTP settings. For example, if we would like to send email through Gmail, we can supply provider = gmail to not have to worry about the SMTP server details.

# Store SMTP credentials in the
# system's key-value store with
# `provider = "gmail"`
create_smtp_creds_key(
  id = "gmail",
  user = "user_name@gmail.com",
  provider = "gmail"
)

The credentials data can be later retrieved during email sending with the creds_key() credentials helper. Should you need to know which keys are set in the key-value store, we can use the view_credential_keys() function (which shows all keys by id, key_name, and username).

We can store email credentials in a file using the create_smtp_creds_file() function. Here is an example showing how to create a credentials file with the name "gmail_creds" in the working directory.

# Store SMTP credentials as a file
# with the filename "gmail_creds"
create_smtp_creds_file(
  file = "gmail_creds",
  user = "user_name@gmail.com",
  host = "smtp.gmail.com",
  port = 465,
  use_ssl = TRUE
)

We can also use preset SMTP settings as with the create_smtp_creds_key() function. To send email through Gmail we can supply provider = gmail to avoid supplying host, port, and use_ssl.

# Create a credentials file for sending
# email through Gmail
create_smtp_creds_file(
  file = "gmail_creds",
  user = "user_name@gmail.com",
  provider = "gmail"
)

The credentials data from this file can later retrieved during email sending with the creds_file() credentials helper.

Sending Email

Let’s create a simple test message with the prepare_test_message() function.

# Create the test message, this returns
# an `email_message` object
test_message <- prepare_test_message()

# Preview the message in the Viewer
test_message

The test message

Now that this test message is available, we can experiment with the sending of it to a personal email account. Here are three examples, each use a different method for supplying SMTP credentials.

# Sending email to a personal account
# through manual specification of SMTP
# credentials
test_message %>%
  smtp_send(
    from = "personal@email.net",
    to = "personal@email.net",
    subject = "Testing the `smtp_send()` function",
    credentials = creds(
      user = "user_name@gmail.com",
      provider = "gmail"
    )
  )

# Sending email to a personal account
# using the credentials key
test_message %>%
  smtp_send(
    from = "personal@email.net",
    to = "personal@email.net",
    subject = "Testing the `smtp_send()` function",
    credentials = creds_key(id = "gmail")
  )

# Sending email to a personal account
# using the on-disk credentials file
test_message %>%
  smtp_send(
    from = "personal@email.net",
    to = "personal@email.net",
    subject = "Testing the `smtp_send()` function",
    credentials = creds_file(file = "gmail_creds")
  )

If the SMTP credentials are correctly set, we will get the following message in the console:

The email message was sent successfully.

Concluding

This covers the basics on how to get up and running on sending emails through blastula’s SMTP functionality. If you encounter a bug (or just have a question or feature request) please file an issue.