gmailr v1.0.0

Introduction

gmailr v1.0.0 (https://gmailr.r-lib.org) is now on CRAN!

gmailr wraps the Gmail REST API v3. It provides a variety of funcitons to query your mailbox and create and send new email messages. You can retrieve, create and send emails and drafts, manage email labels, trash and untrash emails, and delete messages, drafts and threads.

The tidyverse team uses gmailr most often to send emails to the maintainers of packages which depend on our packages, to inform them when a new package release is imminent or if any of our changes require action on their part.

Install gmailr with:

install.packages("gmailr")

The release of version 1.0.0 marks three events:

There are changes in the auth interface that are not backwards compatible.
The built-in application has been removed.
The functions have all been prefixed with gm_(), to avoid name conflicts with functions in other packages (including the base package).

There is also new functionality that make writing emails with non-ASCII characters more robust, and improved documentation. See the changelog for the full details on this release.

Auth from gargle

gmailr’s auth functionality now comes from the gargle package, which provides R infrastructure to work with Google APIs, in general. We’ve just blogged about gargle’s initial release, so check out that post for more details.

We’re adopting gargle for auth in several other packages, such as bigrquery (>= v1.2.0), googledrive (>= v1.0.0), and googlesheets4 (currently GitHub-only, successor of googlesheets). This makes new token flows available in these packages, such as Application Default Credentials, and makes auth less idiosyncratic.

Auth changes the typical user will notice

The functions used for authentication have changed. Use gm_auth_configure() to configure your application and then gm_auth() to actually authenticate your user with the application.

OAuth2 tokens are now cached at the user level, by default, instead of in .httr-oauth in the current project. We will ask if it’s OK to create a new folder to hold your OAuth tokens. We recommend that you delete any vestigial .httr-oauth files lying around your gmailr projects and re-authorize gmailr, i.e. get a new token, stored in the new way.

The new strategy makes it harder to accidentally push your tokens to the cloud, easier to use multiple Google identities, and easier to share tokens across projects and packages.

Overall, gmailr has gotten more careful about getting your permission to use a cached token. See the gargle vignette Non-interactive auth to learn how to prevent attempts to interact with you, especially the section “Arrange for an oauth token to be re-discovered”.

gmailr also removes the built-in OAuth “app”. This was nessesary to comply with stricter rules and enforcement by google for Gmail API applications. It was not possible to comply with these rules and continue to have a default application embedded in gmailr. See the setup section of the readme for how to create a new project and authenticate it with only a few steps. gmailr operates under the same Privacy Policy as other tidyverse API packages, the most relevant bit for users is ‘The packages only communicate with Google APIs. No user data is shared with the owners of the Tidyverse API Packages, RStudio, or any other servers.’

Preventing name conflicts

Historically functions in gmailr did not attempt to avoid conflicts, including common functions in the base package like body() and message(). It was assumed users would use namespaced calls, e.g. gmailr::body() if there were issues. However this inadvertantly causes confusing errors for users. All of the functions are now prefixed with gm_() to solve this conflict. This also increases function discoverability via auto-complete.

The un-exported function gmailr:::gm_convert_file() converts existing scripts to use the new functions. Use gmailr:::gm_convert_file(list.files(pattern = "[.]R$", recursive = TRUE)) to convert all of your R scripts in the current directory and below. (Be sure to inspect the changes manually!)

Shared workflows

The shared use of gargle allows us to create centralized articles for several workflows that can be tricky for users:

Thanks!

Thanks to the 58 people who contributed issues, code, and comments to this release!

@abhishek1608, @alansz, @alkashef, @ascheinwald, @batpigandme, @Btibert3, @choisy, @coatless, @csalgads, @ctbrown, @eluerken, @EricGoldsmith, @fiol92, @grepinsight, @hadley, @Hellengeremias, @hopeful-coder, @howard-gu, @jamespmcguire, @jennybc, @jim0wheel, @jimhester, @jlegewie, @jnolis, @josibake, @kazuya030, @kevin-dyrland, @krlmlr, @lawremi, @lmmx, @lwasser, @maaraaj, @marco-vene, @martijnvv, @matt-negrin, @mattbaggott, @msgoussi, @msrodrigues, @MST2803, @nicocriscuolo, @obarisk, @paddytobias, @prithajnath, @RockScience, @RozennGZ, @rpietro, @scottgrimes, @SimonCoulombe, @slomanl1, @songyurita, @sumxf, @TheKashe, @tingmar, @tmamiya, @Vestaxis, @vikram-rawat, @williamgunn, and @xhudik