gmailr 2.0.0

Changes around the OAuth client

• 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.

Storing and deploying a token

• 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.

Syncing up with gargle

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()).

Other changes

• 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.

gmailr 1.0.1

• Jenny Bryan is now the maintainer

gmailr 1.0.0

Breaking changes

• 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 nessesary to comply with stricter enforement
  of the API terms of service.

New features

• 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.

Minor improvements and fixes

• 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).