Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time
title: "gmailr"
output: rmarkdown::html_vignette
vignette: >
```{r, include = FALSE}
collapse = TRUE,
comment = "#>"
```{r setup, message = FALSE}
## Quickstart ##
This is a short document on getting up to speed with gmailr quickly.
## External Setup ##
In order to use gmailr you will need to create a google project for it. The
easiest way to do this is via the [Python
* Click the `Enable the Gmail API` button.
* In the resulting dialog click the `DOWNLOAD CLIENT CONFIGURATION` on your computer.
* Tell gmailr where the JSON lives, by doing one of the two things
1. Call `gm_auth_configure(path = "path/to/downloaded/json")`
2. Set the `GMAILR_APP` environment variable to the location of the JSON
file, it is convienent to do this in your `.Renviron` file with
`usethis::edit_r_environ()`. Then calling `gm_auth_configure()` with no arguments.
* Call `gm_auth()` to start the OAuth flow to verify to google that you would
like your gmailr project to have access to your email. You will get a scary
warning about an untrusted application, this is because the application is
the one you just created, click advanced and `Go to gmailr` to proceed to do
the oauth flow.
* If you want to authenticate with fewer scopes than the default use the
`scopes` parameter to `gm_auth()`. You can see a full list of available
scopes from `gm_scopes()`.
Only very heavy usage of the Gmail API requires payment, so use of the API for most
people should be free.
If you use `usethis::edit_r_environ()` to set both `GMAILR_EMAIL` and
`GMAILR_APP`, then once you have an oauth token you can simply run
`gm_auth_configure()` with no arguments at the top of the script to setup your
## Writing new emails ##
Create a new email with `gm_mime()` and the helper functions. When testing it
is recommended to use `gm_create_draft()` to verify your email is formatted as you
expect before automating it (if desired) with `gm_send_message()`.
test_email <-
gm_mime() %>%
gm_subject("this is just a gmailr test") %>%
gm_text_body("Can you hear me now?")
# Verify it looks correct
# If all is good with your draft, then you can send it
You can add a file attachment to your message with `gm_attach_file()`.
write.csv("mtcars.csv", mtcars)
test_email <- gm_attach_file("mtcars.csv")
# Verify it looks correct
# If so, send it
## Reading emails ##
gmail shows you threads of messages in the web UI, you can retrieve all threads
with `gm_threads()`, and retrieve a specific thread with `gm_thread()`
# view the latest thread
my_threads <- gm_threads(num_results = 10)
# retrieve the latest thread by retrieving the first ID
latest_thread <- gm_thread(gm_id(my_threads)[[1]])
# The messages in the thread will now be in a list
# Retrieve parts of a specific message with the accessors
my_msg <- latest_thread$messages[[1]]
# If a message has attachments, download them all locally with `gm_save_attachments()`.