---
title: "Sending Email Using SMTP"
output: rmarkdown::html_vignette
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

Before using **Gmail** to send out email through **blastula**, there is a key **Gmail** account setting that must changed from the default value. We have to allow *Less Secure Apps* to use your the **Gmail** account. Details on how to make this account-level change can be found in [this support document](https://support.google.com/accounts/answer/6010255).

## 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
```

```{r echo = FALSE, out.width = "100%"}
knitr::include_graphics("prepare_test_message.png", dpi = 300)
```

<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. Again, this article applies only to the in-development version of **blastula**, which can be installed using:

```{r install_github, eval=FALSE}
remotes::install_github("rich-iannone/blastula")
```

Because the `smtp_send()` is quite new, there are bound to be some problems with it. If you encounter a bug or just have a question or feature request, please file an [issue](https://github.com/rich-iannone/blastula/issues).
