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:
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-oauthin 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-oauthfiles 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”.
Preventing name conflicts
Historically functions in gmailr did not attempt to avoid conflicts, including common functions in the base package like
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!)
The shared use of gargle allows us to create centralized articles for several workflows that can be tricky for users:
- Non-interactive auth
- Auth when using R in the browser
- Managing tokens securely
- How to get your own API credentials
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