Repository files navigation

Exposing theGmail API fromR.

Install the released version of gmailr from CRAN:

install.packages("gmailr")

Or install the development version from GitHub with:

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

library(gmailr)

In order to use gmailr, youmust provide your own OAuth client. Thisis documented in the articleSet up an OAuthclient. Thearticle goes deeply into how to create an OAuth client and also how toconfigure it for gmailr’s use. If you already have an OAuth client orknow how to create one, the help topics for?gm_auth_configure and?gm_default_oauth_client are more concise resources for just theclient configuration piece.

Configuring an OAuth client is step 1 of 2 for getting ready to usegmailr. Step 2 is to complete the so-called “OAuth dance”, which istriggered automatically upon first need. You are taken to a web browser,where you must select or login as the Google user you want to use(authenticate yourself) and give your OAuth client permission to doGmail stuff on your behalf (authorize). The OAuth dance does not(necessarily) need to be repeated in subsequent sessions. See?gm_authif these defaults aren’t appropriate for your use case and you’d like totake more control.

You can callgm_profile() to confirm that you are using the intendedGoogle identity.

Create a new email withgm_mime() and build it up from parts, usinghelper functions likegm_to() andgm_subject().

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?")

When developing the message, you might want to usegm_create_draft(),if you’d like to view a draft and verify that it’s formatted as youexpect. Then you can send the draft withgm_send_draft() or send theoriginal MIME message withgm_send_message().

# Verify it looks correct, i.e. look at your Gmail drafts in the browserd<- gm_create_draft(test_email)# If all is good with your draft, then you can send the existing draftgm_send_draft(d)#> Draft Id: 19a4c8f2ecd3e439#> NULL# or the existing MIME messagegm_send_message(test_email)#> Id: 19a4c8f30fae009f

You can retrieve all email threads withgm_threads() or retrieve aspecific thread withgm_thread(). You can then isolate a specificmessage and access its parts.

# view recent threadsmy_threads<- gm_threads(num_results=10)# retrieve the latest thread by retrieving the first IDlatest_thread<- gm_thread(gm_id(my_threads)[[1]])# messages in the thread will now be in a list# retrieve parts of a specific message with the accessorsmy_msg<-latest_thread$messages[[1]]gm_date(my_msg)#> [1] "Mon, 3 Nov 2025 20:50:43 -0500"gm_subject(my_msg)#> [1] "this is just a gmailr test"gm_body(my_msg)#> [[1]]#> [1] "Can you hear me now?\r\n"

More details are available in theGetstarted article and ingmailr’sother articles.

Privacy policy