Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jennybc/send-email-with-r

How to send a bunch of email from R
https://github.com/jennybc/send-email-with-r

Last synced: 13 days ago
JSON representation

How to send a bunch of email from R

Awesome Lists containing this project

README 

        
---

output:

  github_document:

    toc: true

    toc_depth: 2

---

How to send a bunch of emails from R

=================



```{r, echo = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "README-"

)

```



We send a fair amount of email in [STAT 545](http://stat545.com). For example, it's how we inform students of their marks on weekly homework and peer review. We use R for essentially all aspects of the course and this is no exception.



In this repo I describe our workflow, with Lord of the Rings characters playing the role of our students.



Must haves:



  * A Google account with an associated Gmail email address.

  * The [`gmailr` R package](http://cran.r-project.org/web/packages/gmailr/index.html) by Jim Hester, which wraps the Gmail API (development on [GitHub](https://github.com/jimhester/gmailr)).



Nice to haves:



  * A project in Google Developers Console to manage your use of the Gmail API. Optional but recommended once your use `gmailr` is more than casual, as mine is.

  * The [`readr`](http://cran.r-project.org/web/packages/readr/index.html), [`dplyr`](http://cran.r-project.org/web/packages/dplyr/index.html) and [`purrr`](https://cran.r-project.org/web/packages/purrr/) packages for data wrangling and iteration. "Past me" used `plyr` instead of `purrr` and you could certainly do all of this with base R if you prefer.

  * [`addresses.csv`](addresses.csv) a file containing email addresses, identified by a __key__. In our case, student names.

  * [`marks.csv`](marks.csv) a file containing the variable bits of the email you plan to send, including the same identifying __key__ as above.  In our case, the homework marks.

  * The script [`send-email-with-r.R`](send-email-with-r.R) that

    - joins email addresses to marks

    - creates valid email objects from your stuff

    - provides your Gmail credentials

    - sends email

    

### FAQ: Can't I "just" do this with sendmail?



YES, be my guest! If you can get that working quickly, I salute you -- you clearly don't need this tutorial. For everyone else, I have found this Gmail + `gmailr` approach less exasperating.



## Prep work related to Gmail and the `gmailr` package



Verify that your Google account is mail-capable by visiting  while logged in. If it's not, you might as well stop reading now. Or accept the offer at that link to enable Gmail or create a new mail-capable account.



Install the `gmailr` package from CRAN or the development version from GitHub (pick ONE):



```{r eval = FALSE}

install.packages("gmailr")

## OR ...

devtools::install_github("jimhester/gmailr")

```



### Create a project in Google Developers Console



If your use of `gmailr` is more than casual, you should get your own client id. Don't worry if you don't know what that means. Just do it.



I have found this works better -- or only works at all -- if I use Google Chrome versus, say, Safari. YMMV.



  * Pick a name for your project. I chose "gmailr-tutorial" for this write-up. Let's call this `PROJ-NAME` from now on.

  * Create a new project at .

  * Overview screen > Google Apps APIs > Gmail API.

    - Enable!

  * Click "Go to Credentials" or navigate directly to Credentials.

  * You want a "client ID".

  * Yes, you will have to "Configure consent screen".

    - The email should be pre-filled, since presumably you are signed in with the correct Google account. Enter `PROJ-NAME` as the Product name and leave everything else blank. Click Save.

  * Back to ... Create client ID. Select application type "Other". Enter `PROJ-NAME` again here for the name. Click "Create".

  * OAuth client pop up will show you your client ID and secret. You don't need to copy them -- there are better ways to get this info. Dismiss with "OK". 

  * Click on the download icon at the far right of your project's OAuth 2.0 client ID listing to get a JSON file with your ID and secret. You'll get a file named something like this:

    

            client_secret_.apps.googleusercontent.com.json

        

      I rename this after the project, e.g., `PROJ-NAME.json` and move into the directory where the bulk emailing project lives.

        

  * *Optional* if you are using Git, add a line like this to your `.gitignore` file 

    

            PROJ-NAME.json

  

  * You can add members to specific projects from Google Developers Console, allowing them to also download JSON credentials for the same project. I do that for my TAs, for example.



## Dry run



See [`dryrun.R`](dryrun.R) for clean code.



Load `gmailr`. *PSA: it masks several functions from `base` and `utils`, including `message()`.*



```{r}

suppressPackageStartupMessages(library(gmailr))

```



**If you chose to get your own client id**, tell `gmailr` about that JSON file now. Otherwise, skip this and `gmailr` will use its own built-in client id.



```{r}

use_secret_file("gmailr-tutorial.json")

```



You can force the auth process explicitly via `gmail_auth()` or simply go about your business and it will happen when needed. Let's send a test email.



```{r eval = FALSE}

test_email <- mime(

	To = "PUT_A_VALID_EMAIL_ADDRESS_THAT_YOU_CAN_CHECK_HERE",

	From = "PUT_THE_GMAIL_ADDRESS_ASSOCIATED_WITH_YOUR_GOOGLE_ACCOUNT_HERE",

	Subject = "this is just a gmailr test",

	body = "Can you hear me now?")

send_message(test_email)

```



```{r echo = FALSE}

test_email <- mime(

	To = "[email protected]",

	From = "[email protected]",

	Subject = "this is just a gmailr test",

	body = "Can you hear me now?")

send_message(test_email)

```



You may be presented with this question



```

Use a local file to cache OAuth access credentials between R sessions?

1: Yes

2: No



Selection: 

```



No matter what, the first time, you should get kicked into a browser to authenticate yourself and authorize the application. If you say "No", this will happen every time and is appropriate for interactive execution of your bulk emailing R code. If you say "Yes", your credentials will be cached in a file named `.httr-oauth` so the browser dance won't happen in the future. Choose this if you plan to execute your bulk emailing code non-interactively.



*Optional* if you opt for OAuth credential caching and you're using Git, add this to your `.gitignore` file. *Note: it appears that `gmailr` does this for you, but make sure it happens!*:

  

    .httr-oauth



Did your email get through? **Do not proceed until the answer is YES**.



If this doesn't work, running it inside a loop with typo-ridden email addresses is unlikely work any better.



## Compose and send your emails



The hard parts are over! See [`send-email-with-r.R`](send-email-with-r.R) for clean code to compose and send email. Here's the guided tour.



The file [`addresses.csv`](addresses.csv) holds names and email addresses. The file [`marks.csv`](marks.csv) holds names and homework marks. In this case, the LoTR characters receive marks based on the number of words they spoke in the Fellowship of the Ring. Read those in and join.



```{r}

suppressPackageStartupMessages(library(gmailr))

suppressPackageStartupMessages(library(dplyr))

suppressPackageStartupMessages(library(purrr))

library(readr)



addresses <- read_csv("addresses.csv")

marks <- read_csv("marks.csv")

(my_dat <- left_join(marks, addresses))

```



Next we create a data frame where each variable is a key piece of the email, e.g. the "To" field or the body.



```{r}

this_hw <- "The Fellowship Of The Ring"

email_sender <- 'Peter Jackson ' # your Gmail address

optional_bcc <- 'Anonymous '     # for me, TA address

body <- "Hi, %s.



Your mark for %s is %s.



Thanks for participating in this film!

"

edat <- my_dat %>%

	mutate(

		To = sprintf('%s <%s>', name, email),

		Bcc = optional_bcc,

		From = email_sender,

		Subject = sprintf('Mark for %s', this_hw),

		body = sprintf(body, name, this_hw, mark)) %>%

	select(To, Bcc, From, Subject, body)

write_csv(edat, "composed-emails.csv")

```



We write this data frame to `.csv` for an easy-to-read record of the composed emails. You will never regret saving such small, easy-to-read things.



We use the `gmailr::mime()` function to convert each row of this data frame into a MIME-formatted message object. We use `purrr::pmap()` to generate the list of mime objects, one per row of the input data frame. I present commented-out `plyr` code, for historical interest. If you want base R, you're on your own.



```{r}

emails <- edat %>%

  pmap(mime)

str(emails, max.level = 2, list.len = 2)



## plyr code to do similar: Option A

# emails <- plyr::dlply(edat, ~ To, function(x) mime(

#   To = x$To,

#   Bcc = x$Bcc,

#   From = x$From,

#   Subject = x$Subject,

#   body = x$body))



## plyr code to do similar: Option B

# emails <- plyr::alply(edat, 1, function(x) mime(

#   To = x$To,

#   Bcc = x$Bcc,

#   From = x$From,

#   Subject = x$Subject,

#   body = x$body))

```



**If you chose to get your own client id**, tell `gmailr` about that JSON file now. Otherwise, skip this and `gmailr` will use its own built-in client id.



```{r}

use_secret_file("gmailr-tutorial.json")

```



If you've cached your OAuth credentials, sending mail should "just work", though you might see something about refreshing your token. Otherwise, you can expect to do the OAuth browser dance when executing the next chunk.



Send your emails!



  * I choose to create a "safe" version of `send_message()` with `purrr::safely()`, so no single failure can derail my bulk emailing effort in the middle.

  * `purrr::map()` iterates over all the MIME objects stored in `emails.`

  * Always retain the return value, for inspection and writing to file.



```{r eval = FALSE}

safe_send_message <- safely(send_message)

sent_mail <- emails %>% 

  map(safe_send_message)



saveRDS(sent_mail,

        paste(gsub("\\s+", "_", this_hw), "sent-emails.rds", sep = "_"))

```



```{r include = FALSE}

fake_emails <- data_frame(

  To = c("[email protected]", "invalid", "[email protected]"),

  From = "[email protected]",

  Bcc = "[email protected]",

  Subject = c("success subject 1", "fail subject", "success 2 subject"),

  body = c("success body 1", "fail body", "success 2 body")

) %>% 

  pmap(mime)



safe_send_message <- safely(send_message)



sent_mail <- fake_emails %>% 

  map(safe_send_message)



saveRDS(sent_mail,

        paste(gsub("\\s+", "_", this_hw), "sent-emails.rds", sep = "_"))



# sent_mail <- fake_emails %>%

#  map(send_message)

# I verified that email 1 goes out, email 2 makes things halt

# and sent_mail does not get created

# so YEAH safely is a good idea here

```



How does this `safely()` thing work? In a hidden chunk, I've used code like the above to attempt to send 3 emails. The one in the middle intentionally has a nonsensical "To" field and fails. Here's how I inspect the result and access the error.



```{r}

errors <- sent_mail %>% 

  transpose() %>% 

  .$error %>% 

  map_lgl(Negate(is.null))

sent_mail[errors]

```



The end.



### session info



```{r}

devtools::session_info()

```