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:
client, which is morally equivalent to the
previous app, i.e. this is essentially a name change.key, secret, appname, and app arguments are deprecated.path argument, either explicitly::
gm_auth_configure(path = "path/to/my-oauth-client.json")
gm_auth_configure()
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).