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 Quickstart.
- 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
- Call
gm_auth_configure(path = "path/to/downloaded/json")
- Set the
GMAILR_APP
environment variable to the location of the JSON file, it is convienent to do this in your.Renviron
file withusethis::edit_r_environ()
. Then callinggm_auth_configure()
with no arguments.
- Call
- 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 andGo to gmailr
to proceed to do the oauth flow. - If you want to authenticate with fewer scopes than the default use the
scopes
parameter togm_auth()
. You can see a full list of available scopes fromgm_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 application.
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_to("PUT_A_VALID_EMAIL_ADDRESS_THAT_YOU_CAN_CHECK_HERE") %>%
gm_from("PUT_THE_GMAIL_ADDRESS_ASSOCIATED_WITH_YOUR_GOOGLE_ACCOUNT_HERE") %>%
gm_subject("this is just a gmailr test") %>%
gm_text_body("Can you hear me now?")
# Verify it looks correct
gm_create_draft(test_email)
# If all is good with your draft, then you can send it
gm_send_message(test_email)
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
gm_create_draft(test_email)
# If so, send it
gm_send_message(test_email)
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
latest_thread$messages
# Retrieve parts of a specific message with the accessors
my_msg <- latest_thread$messages[[1]]
gm_to(my_msg)
gm_from(my_msg)
gm_date(my_msg)
gm_subject(my_msg)
gm_body(my_msg)
# If a message has attachments, download them all locally with `gm_save_attachments()`.
gm_save_attachments(my_msg)