sending_using_smtp.Rmd

---
title: "Sending Email Using SMTP"
output: rmarkdown::html_vignette
resource_files:
  - images
vignette: >
  %\VignetteIndexEntry{sending_using_smtp}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

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](https://support.google.com/accounts/answer/185833?hl=en).

_**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:

1. Storing credentials in the system's key-value store
2. 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"`.

```{r creds_key_1, eval=FALSE}
# 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.

```{r creds_key_2, eval=FALSE}
# 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.

```{r creds_file_1, eval=FALSE}
# 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`.

```{r creds_file_2, eval=FALSE}
# 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.

```{r prepare_test_message, eval=FALSE}
# Create the test message, this returns
# an `email_message` object
test_message <- prepare_test_message()

# Preview the message in the Viewer
test_message
```

<img src="images/prepare_test_message.png" width=100%>

<p align="center">The test message</p>
<br />

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.

```{r smtp_send_creds_manual, eval=FALSE}
# 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"
    )
  )
```

```{r smtp_send_creds_key, eval=FALSE}
# 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")
  )
```

```{r smtp_send_creds_file, eval=FALSE}
# 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](https://github.com/rstudio/blastula/issues).