Need help with gmailr?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

r-lib
212 Stars 58 Forks Other 315 Commits 30 Opened issues

Description

Access the Gmail RESTful API from R.

Services available

!
?

Need anything else?

Contributors list

gmailr

R build status Codecov test coverage <!-- badges: end -->

Exposing the Gmail API from R.

Installation

Get the released version from CRAN:

install.packages("gmailr")

Or the development version from github with:

# install.packages("devtools")
devtools::install_github("r-lib/gmailr")

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_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,"mtcars.csv")
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 

Features

  • retrieve data from your email
    • drafts:
      my_drafts = gm_drafts()
    • history:
      my_history = history(start_num)
    • labels:
      my_labels = gm_labels()
    • messages:
      my_messages = gm_messages("search query")
    • threads:
      my_threads = gm_threads("search query")
  • Create and send emails and drafts: see sending_messages vignette
  • manage email labels programmatically:
    modify_thread(thread_id, add_labels=c("label_1"), remove_labels=c("label_2"))
  • put things in the gmail trash
    • messages:
      gm_trash_message(message_id)
    • threads:
      trash_thread(thread_id)
  • take things out of the gmail trash
    • messages:
      gm_untrash_message(message_id)
    • threads:
      untrash_thread(thread_id)
  • delete directly without using the trash
    • messages:
      gm_delete_message(message_id)
    • threads:
      delete_thread(thread_id)

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.

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

# Configure your app
gm_auth_configure(path = "credentials.json")

Authenticate with the new cache, store tokens in .secret

gm_auth(cache = ".secret")

Go through the oauth flow

Then copy

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

Run remotely

# Configure your app
gm_auth_configure(path = "credentials.json")

Authenticate with the tokens in the copied cache

gm_auth(email = TRUE, cache = ".secret")

There are additional details on dealing with non-interactive auth in the gargle documentation.

Policies

Privacy policy

Community Examples

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.