Exposing the Gmail API from R.


Get the released version from CRAN:

Or the development version from github with:

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



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.

Using gmailr in deployed applications

If you are using gmailr in a deployed application you will need to copy two pieces to your deployed location.

  1. The application JSON file, that you setup in the local setup.
  2. The oauth token cache, by default this is ~/.R/gargle/gargle-oauth

The easiest thing to do to ensure you are copying only the gmailr oauth token is to set this explicitly locally, e.g. do the following.

Run locally

Then copy credentials.json and the .secret directory to your remote location.


Privacy policy

Community Examples