library(gmailr)

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 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
    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 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().