NEWS.md

gmailr (development version)

Syncing up with gargle

Version 1.3.0 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_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).

Other changes

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

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

gmailr 0.7.1

• Bundle a application token and secret in gmailr so the average user won't need to create an application.
• Great number of bug fixes
• Reworking the print functions to provide more useful and easy to read output
• Added check for null response to fix bug with DELETE requests (#79) @josibake

gmailr 0.5.0

Major Changes

• Added ability to create and send drafts and messages. (#5, #6)
• Added a number of tests for mime message creation derived from the Email::Stuffer perl module.

Minor Fixes

• Namespace was not properly updated (#2)
• added extraction functions for gmail_messages (#3)

gmailr 0.0.1

• Initial release