Set up an OAuth client is a new non-vignette article with detailed instructions for creating and configuring an OAuth client.
gm_default_oauth_client() is a new helper that
searches for the JSON file representing an OAuth client in a sequence of
locations. The (file)path of least resistance is to place this file in
the directory returned by
rappdirs::user_data_dir("gmailr"). Another alternative is
to record its filepath in the GMAILR_OAUTH_CLIENT
environment variable. For backwards compatibility, the
GMAILR_APP environment variable is still consulted, but
generates a warning (#166).
gm_auth() no longer checks for an OAuth client
before calling gargle::token_fetch(). This allows other
auth methods to work, which by and large don’t need an OAuth client,
such as gargle::credentials_byo_oauth2() (#160,
#186).
If gm_auth() fails to get a token and no OAuth
client has been configured, it silently calls
gm_auth_configure() to make one attempt at automatic client
discovery. If an OAuth client is indeed discovered,
gm_auth() tries one more time to get a token.
Since the lack of an OAuth client undoubtedly remains the most common
reason for gm_auth() to fail, its error message includes
some specific content if no OAuth client has been configured.
gm_token_write() + gm_token_read() is a
new matched pair of functions that make it much easier to explicitly
store a token obtained in an interactive session then reuse that token
elsewhere, such in CI or in a deployed product (#190).
The directory
system.file("deployed-token-demo", package = "gmailr")
contains a working demo of how to use gm_token_write() +
gm_token_read() in a deployed Shiny app.
vignette("deploy-a-token") is a new vignette
describing how to capture a token interactively, for later use in a
non-interactive setting.
Versions 1.3.0, 1.4.0, and 1.5.1 of gargle introduced some changes around OAuth and gmailr is syncing up that:
gm_oauth_client() is a new function to replace the
now-deprecated gm_oauth_app(). This is somewhat about a
vocabulary change (“client” instead of “app”), but it’s really connected
to a more meaningful shift in gargle, which has a new appreciation for
different OAuth client types (e.g., “installed” vs. “web”).gm_oauth_client() (and the function it’s replacing,
gm_oauth_app()) no longer error if there is no configured
OAuth client.gm_auth_configure() has an updated signature:
The first argument is now named client, which is
morally equivalent to the previous app, i.e. this is
essentially a name change.
The key, secret, appname,
and app arguments are deprecated.
Our strong recommendation is to use the path
argument, either explicitly::
gm_auth_configure(path = "path/to/my-oauth-client.json")or implicitly:
gm_auth_configure()which works because of the new default:
gm_auth_configure(path = gm_default_oauth_client()).
gm_auth(subject =) is a new argument that can be
used with gm_auth(path =), i.e. when using a service
account. The path and subject arguments are
ultimately processed by
gargle::credentials_service_account() and support the use
of a service account to impersonate a regular user.
gm_scopes() can now take a character vector of
scopes, each of which can be an actual scope or a short alias, e.g.,
"gmail.readonly", which identifies a scope associated with
the Gmail API. When called without arguments, gm_scopes()
still returns a named vector of Gmail API-specific scopes, where the
names are the associated short aliases.
The deprecation process for legacy functions that lack the
gm_ prefix has been advanced. The functions are still
present, but throw an error directing the user to switch to the prefixed
version.
The unexported helper
gmailr:::gm_convert_file(list.files(pattern = "[.]R$", recursive = TRUE))
can be used to convert all R files in the current directory to the new
names (#95).
Legacy auth functions clear_token(),
gmail_auth(), and use_secret_file() now throw
an error.
gmailr no longer Imports magrittr and no longer
re-exports the magrittr pipe (%>%). gmailr is a very
pipe-friendly package, so this was originally done for user convenience
(#42).
Since most users (those using R >= 4.1) now have access to the
base pipe (|>), that is now what is shown in gmailr’s
documentation. Those using R < 4.1 can still use gmailr with
magrittr::%>%, but they will need to do
library(magrittr) for themselves.
Any gmailr examples that use the base pipe will no longer work on R < 4.1. On affected R versions, the examples are automatically converted to a regular section with a note that they might not work.
All functions are now prefixed with gm_*() to avoid
name conflicts with other packages (including the base package), the
previous names have been deprecated and will be removed in future
releases. Use
gmailr:::gm_convert_file(list.files(pattern = "[.]R$", recursive = TRUE))
to convert all R files in the current directory to the new names.
(#95)
New gm_auth_configure() and gm_auth()
functions added conforming to the conventions in the gargle package.
gmail_auth(), clear_token() and
use_secret_token() are now deprecated and will be removed
in a future release.
The google application bundled in previous gmailr releases has been removed, users will now need to create their own applications in order to use gmailr. See the Setup section in the readme for details. This was necessary to comply with stricter enforcement of the API terms of service.
New gm_attachements() returns a data.frame of
attachment information from a message or draft (#10, #24).
New gm_delete_draft() added to delete a draft email
without sending it to the trash.
New gm_profile() function to return the gmail
profile of the currently logged in user (#114)
New gm_scopes() function to list the available
scopes, and gmailr now requests only the full scope by default
(#90)
More detailed examples added to the README and the vignette, including adding and referencing attachments in HTML email.
gm_body(), gm_to(),
gm_from(), gm_cc(), gm_bcc() and
gm_subject() now automatically mark their output as UTF-8
(#47, #86)
Quoted-printable now works with smart quotes (#77)
Unicode text can now be used in email headers, including the Subject and address fields, like To and Cc (#76, #78)
print.gmail_message() now only prints the parts of
the message that are defined (#88) and now prints out the filenames of
attachments (if any).