Access the 'Gmail' 'RESTful' API

An interface to the 'Gmail' 'RESTful' API. Allows access to your 'Gmail' messages, threads, drafts and labels.

Build Status Coverage Status

Exposing the Gmail API from R.


  • retrieve data from your email
    • drafts: my_drafts = drafts()
    • history: my_history = history(start_num)
    • labels: my_labels = labels()
    • messages: my_messages = messages("search query")
    • threads: my_threads = 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: trash_message(message_id)
    • threads: trash_thread(thread_id)
  • take things out of the gmail trash
    • messages: untrash_message(message_id)
    • threads: untrash_thread(thread_id)
  • delete directly without using the trash
    • messages: delete_message(message_id)
    • threads: delete_thread(thread_id)


By default gmailr will use a global project. However if you are going to be doing a heavy user and will do a lot of queries please setup your own project with the steps below.

  • Register a new project at

  • Navigate to APIs

    • Switch the Gmail API status to On, and other API status to Off
  • Navigate to APIs & auth->Consent screen

    • Name your application
    • Select an email address for the application
    • Other fields can be left blank
  • Navigate to APIs & auth->Credentials

    • Create a new client ID
      • Application Type: Installed Application
      • Installed Application Type: Other
    • Download the Client ID JSON - can be renamed!
  • Use the downloaded JSON file as input to gmail_auth()


Future Work

  • More unit tests and better coverage
  • More (complicated) examples
  • Email statistics
  • Programmatic emailing
  • Returning data frames in addition to native Gmail API objects which are usually a nested list.
  • Support all the formats of users.messages:get



gmailr 0.7.1

  • Bundle a application token and secret in gmailr so the average user won't need to create an application.
  • Great number of bug fixes
  • Reworking the print functions to provide more useful and easy to read output

gmailr 0.5.0

Major Changes

  • Added ability to create and send drafts and messages. (#5, #6)
  • Added a number of tests for mime message creation derived from the Email::Stuffer perl module.

Minor Fixes

  • Namespace was not properly updated (#2)
  • added extraction functions for gmail_messages (#3)

gmailr 0.0.1

  • Initial release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.0.0 by Jim Hester, a year ago

Report a bug at

Browse source code at

Authors: Jim Hester

Documentation:   PDF Manual  

Task views: Web Technologies and Services

MIT + file LICENSE license

Imports base64enc, crayon, gargle, httr, jsonlite, lifecycle, magrittr, mime, rematch2

Suggests covr, knitr, methods, sodium, rmarkdown, testthat, xml2

Suggested by devtools, lgr.

See at CRAN