gmailr: Access the 'Gmail' 'RESTful' API

Description

An interface to the 'Gmail' 'RESTful' API. Allows access to your 'Gmail' messages, threads, drafts and labels.

Author(s)

Maintainer: Jennifer Bryan jenny@posit.co

Authors:

• Jim Hester

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://gmailr.r-lib.org

• https://github.com/r-lib/gmailr

• Report bugs at https://github.com/r-lib/gmailr/issues

Convert a mime object to character representation

Description

This function converts a mime object into a character vector

Usage

## S3 method for class 'mime'
as.character(x, newline = "\r\n", ...)

Arguments

Retrieve an attachment to a message

Description

This is a low level function to retrieve an attachment to a message by id of the attachment and message. Most users are better off using gm_save_attachments() to automatically save all the attachments in a given message.

Usage

gm_attachment(id, message_id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages.attachments/get

See Also

Other message: gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
my_attachment <- gm_attachment("a32e324b", "12345")
# save attachment to a file
gm_save_attachment(my_attachment, "photo.jpg")

## End(Not run)

Retrieve information about attachments

Description

Retrieve information about attachments

Usage

gm_attachments(x, ...)

Arguments

Value

A data.frame with the filename, type, size and id of each attachment in the message.

Authorize gmailr

Description

Authorize gmailr to view and manage your Gmail projects. This function is a wrapper around gargle::token_fetch().

By default, you are directed to a web browser, asked to sign in to your Google account, and to grant gmailr permission to operate on your behalf with Google Gmail. By default, with your permission, these user credentials are cached in a folder below your home directory, from where they can be automatically refreshed, as necessary. Storage at the user level means the same token can be used across multiple projects and tokens are less likely to be synced to the cloud by accident.

Usage

gm_auth(
  email = gm_default_email(),
  path = NULL,
  subject = NULL,
  scopes = "full",
  cache = gargle::gargle_oauth_cache(),
  use_oob = gargle::gargle_oob_default(),
  token = NULL
)

Arguments

Details

Most users, most of the time, do not need to call gm_auth() explicitly – it is triggered by the first action that requires authorization. Even when called, the default arguments often suffice.

However, when necessary, gm_auth() allows the user to explicitly:

• Declare which Google identity to use, via an email specification.

• Use a service account token or workload identity federation via path.

• Bring your own token.

• Customize scopes.

• Use a non-default cache folder or turn caching off.

• Explicitly request out-of-bound (OOB) auth via use_oob.

If you are interacting with R within a browser (applies to RStudio Server, Posit Workbench, Posit Cloud, and Google Colaboratory), you need OOB auth or the pseudo-OOB variant. If this does not happen automatically, you can request it explicitly with use_oob = TRUE or, more persistently, by setting an option via options(gargle_oob_default = TRUE).

The choice between conventional OOB or pseudo-OOB auth is determined by the type of OAuth client. If the client is of the "installed" type, use_oob = TRUE results in conventional OOB auth. If the client is of the "web" type, use_oob = TRUE results in pseudo-OOB auth. Packages that provide a built-in OAuth client can usually detect which type of client to use. But if you need to set this explicitly, use the "gargle_oauth_client_type" option:

options(gargle_oauth_client_type = "web")       # pseudo-OOB
# or, alternatively
options(gargle_oauth_client_type = "installed") # conventional OOB

For details on the many ways to find a token, see gargle::token_fetch(). For deeper control over auth, use gm_auth_configure() to bring your own OAuth client or API key. To learn more about gargle options, see gargle::gargle_options.

See Also

Other auth functions: gm_auth_configure(), gm_deauth(), gm_scopes(), gmailr-configuration

Examples

# load/refresh existing credentials, if available
# otherwise, go to browser for authentication and authorization
gm_auth()

# indicate the specific identity you want to auth as
gm_auth(email = "jenny@example.com")

# force a new browser dance, i.e. don't even try to use existing user
# credentials
gm_auth(email = NA)

# specify the identity, use a 'read only' scope, so it's impossible to
# send or delete email, and specify a cache folder
gm_auth(
  "target.user@example.com",
  scopes = "gmail.readonly",
  cache = "some/nice/directory/"
)

Edit auth configuration

Description

See the article Set up an OAuth client for instructions on how to get an OAuth client. Then you can use gm_auth_configure() to register your client for use with gmailr. gm_oauth_client() retrieves the currently configured OAuth client.

Usage

gm_auth_configure(
  client = NULL,
  path = gm_default_oauth_client(),
  key = deprecated(),
  secret = deprecated(),
  appname = deprecated(),
  app = deprecated()
)

gm_oauth_client()

Arguments

Value

• gm_auth_configure(): An object of R6 class gargle::AuthState, invisibly.

• gm_oauth_client(): the current user-configured OAuth client.

See Also

gm_default_oauth_client() to learn how you can make your OAuth client easy for gmailr to discover.

Other auth functions: gm_auth(), gm_deauth(), gm_scopes(), gmailr-configuration

Examples

# if your OAuth client can be auto-discovered (see ?gm_default_oauth_client),
# you don't need to provide anything!
gm_auth_configure()

# see and store the current user-configured OAuth client
(original_client <- gm_oauth_client())

# the preferred way to configure your own client is via a JSON file
# downloaded from Google Developers Console
# this example JSON is indicative, but fake
path_to_json <- system.file(
  "extdata", "client_secret_installed.googleusercontent.com.json",
  package = "gargle"
)
gm_auth_configure(path = path_to_json)

# confirm that a (fake) OAuth client is now configured
gm_oauth_client()

# restore original auth config
gm_auth_configure(client = original_client)

Get the body text of a message or draft

Description

Get the body text of a message or draft

Usage

gm_body(x, ...)

Arguments

Examples

## Not run: 
gm_body(my_message)
gm_body(my_draft)

## End(Not run)

Create a draft from a mime message

Description

Create a draft from a mime message

Usage

gm_create_draft(mail, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.drafts/create

Examples

## Not run: 
gm_create_draft(gm_mime(
  From = "you@me.com", To = "any@one.com",
  Subject = "hello", "how are you doing?"
))

## End(Not run)

Create a new label

Description

Function to create a label.

Usage

gm_create_label(
  name,
  label_list_visibility = c("show", "hide", "show_unread"),
  message_list_visibility = c("show", "hide"),
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.labels/create

See Also

Other label: gm_delete_label(), gm_labels(), gm_label(), gm_update_label()

Clear current token

Description

Clears any currently stored token. The next time gmailr needs a token, the token acquisition process starts over, with a fresh call to gm_auth() and, therefore, internally, a call to gargle::token_fetch(). Unlike some other packages that use gargle, gmailr is not usable in a de-authorized state. Therefore, calling gm_deauth() only clears the token, i.e. it does NOT imply that subsequent requests are made with an API key in lieu of a token.

Usage

gm_deauth()

See Also

Other auth functions: gm_auth_configure(), gm_auth(), gm_scopes(), gmailr-configuration

Examples

gm_deauth()

Permanently delete a single draft

Description

Function to delete a given draft by id. This cannot be undone!

Usage

gm_delete_draft(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.drafts/delete

See Also

Other draft: gm_drafts(), gm_draft(), gm_send_draft()

Examples

## Not run: 
delete_draft("12345")

## End(Not run)

Permanently delete a label

Description

Function to delete a label by id. This cannot be undone!

Usage

gm_delete_label(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.labels/delete

See Also

Other label: gm_create_label(), gm_labels(), gm_label(), gm_update_label()

Permanently delete a single message

Description

Function to delete a given message by id. This cannot be undone!

Usage

gm_delete_message(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/delete

See Also

Other message: gm_attachment(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
gm_delete_message("12345")

## End(Not run)

Permanently delete a single thread.

Description

Function to delete a given thread by id. This cannot be undone!

Usage

gm_delete_thread(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.threads/delete

See Also

Other thread: gm_modify_thread(), gm_threads(), gm_thread(), gm_trash_thread(), gm_untrash_thread()

Examples

## Not run: 
gm_delete_thread(12345)

## End(Not run)

Get a single draft

Description

Function to retrieve a given draft by <-

Usage

gm_draft(id, user_id = "me", format = c("full", "minimal", "raw"))

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.drafts/get

See Also

Other draft: gm_delete_draft(), gm_drafts(), gm_send_draft()

Examples

## Not run: 
my_draft <- gm_draft("12345")

## End(Not run)

Get a list of drafts

Description

Get a list of drafts possibly matching a given query string.

Usage

gm_drafts(num_results = NULL, page_token = NULL, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.drafts/list

See Also

Other draft: gm_delete_draft(), gm_draft(), gm_send_draft()

Examples

## Not run: 
my_drafts <- gm_drafts()

first_10_drafts <- gm_drafts(10)

## End(Not run)

Is there a token on hand?

Description

Reports whether gmailr has stored a token, ready for use in downstream requests.

Usage

gm_has_token()

Value

Logical.

See Also

Other low-level API functions: gm_token()

Examples

gm_has_token()

Retrieve change history for the inbox

Description

Retrieves the history results in chronological order

Usage

gm_history(
  start_history_id = NULL,
  num_results = NULL,
  label_id = NULL,
  page_token = NULL,
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.history/list

Examples

## Not run: 
my_history <- gm_history("10")

## End(Not run)

Get the id of a gmailr object

Description

Get the id of a gmailr object

Usage

gm_id(x, ...)

## S3 method for class 'gmail_messages'
gm_id(x, what = c("message_id", "thread_id"), ...)

Arguments

Examples

## Not run: 
gm_id(my_message)
gm_id(my_draft)

## End(Not run)

Import a message into the gmail mailbox from a mime message

Description

Import a message into the gmail mailbox from a mime message

Usage

gm_import_message(
  mail,
  label_ids,
  type = c("multipart", "media", "resumable"),
  internal_date_source = c("dateHeader", "recievedTime"),
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/import

See Also

Other message: gm_attachment(), gm_delete_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
gm_import_message(gm_mime(
  From = "you@me.com", To = "any@one.com",
  Subject = "hello", "how are you doing?"
))

## End(Not run)

Insert a message into the gmail mailbox from a mime message

Description

Insert a message into the gmail mailbox from a mime message

Usage

gm_insert_message(
  mail,
  label_ids,
  type = c("multipart", "media", "resumable"),
  internal_date_source = c("dateHeader", "recievedTime"),
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/insert

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
gm_insert_message(gm_mime(
  From = "you@me.com", To = "any@one.com",
  Subject = "hello", "how are you doing?"
))

## End(Not run)

Get a specific label

Description

Get a specific label by id and user_id.

Usage

gm_label(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.labels/get

See Also

Other label: gm_create_label(), gm_delete_label(), gm_labels(), gm_update_label()

Get a list of all labels

Description

Get a list of all labels for a user.

Usage

gm_labels(user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.labels/list

See Also

Other label: gm_create_label(), gm_delete_label(), gm_label(), gm_update_label()

Examples

## Not run: 
my_labels <- gm_labels()

## End(Not run)

Response from the last query

Description

Response from the last query

Usage

gm_last_response()

Get a single message

Description

Function to retrieve a given message by id

Usage

gm_message(
  id,
  user_id = "me",
  format = c("full", "metadata", "minimal", "raw")
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
my_message <- gm_message(12345)

## End(Not run)

Get a list of messages

Description

Get a list of messages possibly matching a given query string.

Usage

gm_messages(
  search = NULL,
  num_results = NULL,
  label_ids = NULL,
  include_spam_trash = NULL,
  page_token = NULL,
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/list

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
# Search for R, return 10 results using label 1 including spam and trash folders
my_messages <- gm_messages("R", 10, "label_1", TRUE)

## End(Not run)

Create a mime formatted message object

Description

These functions create a MIME message. They can be created atomically using gm_mime() or iteratively using the various accessors.

Usage

gm_mime(..., attr = NULL, body = NULL, parts = list())

## S3 method for class 'mime'
gm_to(x, val, ...)

## S3 method for class 'mime'
gm_from(x, val, ...)

## S3 method for class 'mime'
gm_cc(x, val, ...)

## S3 method for class 'mime'
gm_bcc(x, val, ...)

## S3 method for class 'mime'
gm_subject(x, val, ...)

gm_text_body(
  mime,
  body,
  content_type = "text/plain",
  charset = "utf-8",
  encoding = "quoted-printable",
  format = "flowed",
  ...
)

gm_html_body(
  mime,
  body,
  content_type = "text/html",
  charset = "utf-8",
  encoding = "base64",
  ...
)

gm_attach_part(mime, part, id = NULL, ...)

gm_attach_file(mime, filename, type = NULL, id = NULL, ...)

Arguments

Examples

# using the field functions
msg <- gm_mime() |>
  gm_from("james.f.hester@gmail.com") |>
  gm_to("asdf@asdf.com") |>
  gm_text_body("Test Message")

# alternatively you can set the fields using gm_mime(), however you have
#  to use properly formatted MIME names
msg <- gm_mime(
  From = "james.f.hester@gmail.com",
  To = "asdf@asdf.com"
) |>
  gm_html_body("<b>Test<\b> Message")

Modify the labels on a message

Description

Function to modify the labels on a given message by id. Note you need to use the label ID as arguments to this function, not the label name.

Usage

gm_modify_message(id, add_labels = NULL, remove_labels = NULL, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/modify

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
gm_modify_message(12345, add_labels = "label_1")
gm_modify_message(12345, remove_labels = "label_1")
# add and remove at the same time
gm_modify_message(12345, add_labels = "label_2", remove_labels = "label_1")

## End(Not run)

Modify the labels on a thread

Description

Function to modify the labels on a given thread by id.

Usage

gm_modify_thread(
  id,
  add_labels = character(0),
  remove_labels = character(0),
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.threads/modify

See Also

Other thread: gm_delete_thread(), gm_threads(), gm_thread(), gm_trash_thread(), gm_untrash_thread()

Examples

## Not run: 
gm_modify_thread(12345, add_labels = "label_1")
gm_modify_thread(12345, remove_labels = "label_1")
# add and remove at the same time
gm_modify_thread(12345, add_labels = "label_2", remove_labels = "label_1")

## End(Not run)

Get currently configured OAuth app (deprecated)

Description

In light of the new gargle::gargle_oauth_client() constructor and class of the same name, gm_oauth_app() is being replaced by gm_oauth_client().

Usage

gm_oauth_app()

Get info on current gmail profile

Description

Reveals information about the profile associated with the current token.

Usage

gm_profile(user_id = "me", verbose = TRUE)

Arguments

Value

A list of class gmail_profile.

See Also

Wraps the getProfile endpoint:

• https://developers.google.com/gmail/api/reference/rest/v1/users/getProfile

Examples

## Not run: 
gm_profile()

## more info is returned than is printed
prof <- gm_profile()
prof[["historyId"]]

## End(Not run)

Save the attachment to a file

Description

This is a low level function that only works on attachments retrieved with gm_attachment(). To save an attachment directly from a message see gm_save_attachments(), which is a higher level interface more suitable for most uses.

Usage

gm_save_attachment(x, filename)

Arguments

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
my_attachment <- gm_attachment("a32e324b", "12345")
# save attachment to a file
gm_save_attachment(my_attachment, "photo.jpg")

## End(Not run)

Save attachments to a message

Description

Function to retrieve and save all of the attachments to a message by id of the message.

Usage

gm_save_attachments(x, attachment_id = NULL, path = ".", user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages.attachments/get

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachment(), gm_send_message(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
# save all attachments
gm_save_attachments(my_message)
# save a specific attachment
gm_save_attachments(my_message, "a32e324b")

## End(Not run)

Produce scopes specific to the Gmail API

Description

When called with no arguments, gm_scopes() returns a named character vector of scopes associated with the Gmail API. If gm_scopes(scopes =) is given, an abbreviated entry such as "gmail.readonly" is expanded to a full scope ("https://www.googleapis.com/auth/gmail.readonly" in this case). Unrecognized scopes are passed through unchanged.

Usage

gm_scopes(scopes = NULL)

Arguments

Value

A character vector of scopes.

See Also

https://developers.google.com/gmail/api/auth/scopes for details on the permissions for each scope.

Other auth functions: gm_auth_configure(), gm_auth(), gm_deauth(), gmailr-configuration

Examples

gm_scopes("full")
gm_scopes("gmail.readonly")
gm_scopes()

Send a draft

Description

Send a draft to the recipients in the To, CC, and Bcc headers.

Usage

gm_send_draft(draft, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.drafts/send

See Also

Other draft: gm_delete_draft(), gm_drafts(), gm_draft()

Examples

## Not run: 
draft <- gm_create_draft(gm_mime(
  From = "you@me.com", To = "any@one.com",
  Subject = "hello", "how are you doing?"
))
gm_send_draft(draft)

## End(Not run)

Send a message from a mime message

Description

Send a message from a mime message

Usage

gm_send_message(
  mail,
  type = c("multipart", "media", "resumable"),
  thread_id = NULL,
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/send

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_trash_message(), gm_untrash_message()

Examples

## Not run: 
gm_send_message(gm_mime(
  from = "you@me.com", to = "any@one.com",
  subject = "hello", "how are you doing?"
))

## End(Not run)

Get a single thread

Description

Function to retrieve a given thread by id

Usage

gm_thread(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.threads

See Also

Other thread: gm_delete_thread(), gm_modify_thread(), gm_threads(), gm_trash_thread(), gm_untrash_thread()

Examples

## Not run: 
my_thread <- gm_thread(12345)

## End(Not run)

Get a list of threads

Description

Get a list of threads possibly matching a given query string.

Usage

gm_threads(
  search = NULL,
  num_results = NULL,
  page_token = NULL,
  label_ids = NULL,
  include_spam_trash = NULL,
  user_id = "me"
)

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.threads/list

See Also

Other thread: gm_delete_thread(), gm_modify_thread(), gm_thread(), gm_trash_thread(), gm_untrash_thread()

Examples

## Not run: 
my_threads <- gm_threads()

first_10_threads <- gm_threads(10)

## End(Not run)

Methods to get values from message or drafts

Description

Methods to get values from message or drafts

Usage

gm_to(x, ...)

gm_from(x, ...)

gm_cc(x, ...)

gm_bcc(x, ...)

gm_date(x, ...)

gm_subject(x, ...)

Arguments

Produce configured token

Description

For internal use or for those programming around the Gmail API. Returns a token pre-processed with httr::config(). Most users do not need to handle tokens "by hand" or, even if they need some control, gm_auth() is what they need. If there is no current token, gm_auth() is called to either load from cache or initiate OAuth2.0 flow. If auth has been deactivated via gm_deauth(), gm_token() returns NULL.

Usage

gm_token()

Value

A request object (an S3 class provided by httr).

See Also

Other low-level API functions: gm_has_token()

Examples

gm_token()

Write/read a gmailr user token

Description

This pair of functions writes an OAuth2 user token to file and reads it back in. This is rarely necessary when working in your primary, interactive computing environment. In that setting, it is recommended to lean into the automatic token caching built-in to gmailr / gargle. However, when preparing a user token for use elsewhere, such as in CI or in a deployed data product, it can be useful to take the full control granted by gm_token_write() and gm_token_read().

Below is an outline of the intended workflow, but you will need to fill in particulars, such as filepaths and environment variables:

• Do auth in your primary, interactive environment as the target user, with the desired OAuth client and scopes.

  gm_auth_configure()
  gm_auth("jane@example.com", cache = FALSE)
  

• Confirm you are logged in as the intended user:

  gm_profile()
  

• Write the current token to file:

  gm_token_write(
    path = "path/to/gmailr-token.rds",
    key = "GMAILR_KEY"
  )
  

• In the deployed, non-interactive setting, read the token from file and tell gmailr to use it:

  gm_auth(token = gm_token_read(
    path = "path/to/gmailr-token.rds",
    key = "GMAILR_KEY"
  )
  

Usage

gm_token_write(token = gm_token(), path = "gmailr-token.rds", key = NULL)

gm_token_read(path = "gmailr-token.rds", key = NULL)

Arguments

Security

gm_token_write() and gm_token_read() have a more security-oriented implementation than the default token caching strategy. OAuth2 user tokens are somewhat opaque by definition, because they aren't written to file in a particularly transparent format. However, gm_token_write() always applies some additional obfuscation to make such credentials even more resilient against scraping by an automated tool. However, a knowledgeable R programmer could decode the credential with some effort. The default behaviour of gm_token_write() (called without key) is suitable for tokens stored in a relatively secure place, such as on Posit Connect within your organization.

To prepare a stored credential for exposure in a more public setting, such as on GitHub or CRAN, you must actually encrypt it, using a key known only to you. You must make the encryption key available via a secure environment variable in any setting where you wish to decrypt and use the token, such as on GitHub Actions.

Send a single message to the trash

Description

Function to trash a given message by id. This can be undone by gm_untrash_message().

Usage

gm_trash_message(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/trash

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_untrash_message()

Examples

## Not run: 
gm_trash_message("12345")

## End(Not run)

Send a single thread to the trash

Description

Function to trash a given thread by id. This can be undone by gm_untrash_thread().

Usage

gm_trash_thread(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.threads/trash

See Also

Other thread: gm_delete_thread(), gm_modify_thread(), gm_threads(), gm_thread(), gm_untrash_thread()

Examples

## Not run: 
gm_trash_thread(12345)

## End(Not run)

Remove a single message from the trash

Description

Function to trash a given message by id. This can be undone by gm_untrash_message().

Usage

gm_untrash_message(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.messages/trash

See Also

Other message: gm_attachment(), gm_delete_message(), gm_import_message(), gm_insert_message(), gm_messages(), gm_message(), gm_modify_message(), gm_save_attachments(), gm_save_attachment(), gm_send_message(), gm_trash_message()

Examples

## Not run: 
gm_untrash_message("12345")

## End(Not run)

Remove a single thread from the trash.

Description

Function to untrash a given thread by id. This can reverse the results of a previous gm_trash_thread().

Usage

gm_untrash_thread(id, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.threads/untrash

See Also

Other thread: gm_delete_thread(), gm_modify_thread(), gm_threads(), gm_thread(), gm_trash_thread()

Examples

## Not run: 
gm_untrash_thread(12345)

## End(Not run)

Update a existing label.

Description

Get a specific label by id and user_id. gm_update_label_patch() is identical to gm_update_label() but the latter uses HTTP PATCH to allow partial update.

Usage

gm_update_label(id, label, user_id = "me")

gm_update_label_patch(id, label, user_id = "me")

Arguments

References

https://developers.google.com/gmail/api/reference/rest/v1/users.labels/update

https://developers.google.com/gmail/api/reference/rest/v1/users.labels/patch

See Also

Other label: gm_create_label(), gm_delete_label(), gm_labels(), gm_label()

Other label: gm_create_label(), gm_delete_label(), gm_labels(), gm_label()

Configuring gmailr

Description

gmailr can be configured with various environment variables, which are accessed through wrapper functions that provide some additional smarts.

Usage

gm_default_email()

gm_default_oauth_client()

gm_default_email()

gm_default_email() returns the environment variable GMAILR_EMAIL, if it exists, and gargle::gargle_oauth_email(), otherwise.

gm_default_oauth_client()

gm_default_oauth_client() consults a specific set of locations, looking for the filepath for the JSON file that represents an OAuth client. This file can be downloaded from the APIs & Services section of the Google Cloud console https://console.cloud.google.com). The search unfolds like so:

• GMAILR_OAUTH_CLIENT environment variable: If defined, it is assumed to be the path to the target JSON file.

• A .json file found in the directory returned by rappdirs::user_data_dir("gmailr"), whose filename uniquely matches the regular expression "client_secret.+[.]json$".

• GMAILR_APP environment variable: This is supported for backwards compatibility, but it is preferable to store the JSON below rappdirs::user_data_dir("gmailr") or to store the path in the GMAILR_OAUTH_CLIENT environment variable.

Here's an inspirational snippet to move the JSON file you downloaded into the right place for auto-discovery by gm_auth_configure():

path_old <- "~/Downloads/client_secret_123-abc.apps.googleusercontent.com.json"
d <- fs::dir_create(rappdirs::user_data_dir("gmailr"), recurse = TRUE)
fs::file_move(path_old, d)

See Also

Since gmailr uses the gargle package to handle auth, gargle's configuration is also relevant, which is mostly accomplished through options and associated accessor functions.

Other auth functions: gm_auth_configure(), gm_auth(), gm_deauth(), gm_scopes()

Examples

gm_default_email()

withr::with_envvar(
  c(GMAILR_EMAIL = "jenny@example.com"),
  gm_default_email()
)

gm_default_oauth_client()

withr::with_envvar(
  c(GMAILR_OAUTH_CLIENT = "path/to/my-client.json"),
  gm_default_oauth_client()
)

Deprecated functions

Description

All of these functions have been renamed, by adding a gm_ prefix. This is to eliminate name conflicts with other packages (including the base package). Starting with gmailr 1.0.0 (released 2019-08-23), the deprecated functions generated a warning. As of gmailr 2.0.0, they generate an error and they will be completely removed in a future release.

Usage

id(x, ...)

to(x, ...)

from(x, ...)

cc(x, ...)

bcc(x, ...)

date(x, ...)

subject(x, ...)

body(x, ...)

message(...)

messages(...)

trash_message(...)

untrash_message(...)

delete_message(...)

modify_message(...)

attachment(...)

save_attachment(...)

save_attachments(...)

insert_message(...)

import_message(...)

send_message(...)

threads(...)

thread(...)

trash_thread(...)

untrash_thread(...)

delete_thread(...)

modify_thread(...)

draft(...)

drafts(...)

create_draft(...)

send_draft(...)

labels(...)

label(...)

update_label(...)

update_label_patch(...)

delete_label(...)

create_label(...)

history(...)

mime(...)

text_body(...)

html_body(...)

attach_part(...)

attach_file(...)

Deprecated auth

Description

These functions are deprecated and no longer work.

Usage

clear_token()

gmail_auth(
  scope = c("read_only", "modify", "compose", "full"),
  id = the$id,
  secret = the$secret,
  secret_file = NULL
)

use_secret_file(filename)

Encode text using quoted printable

Description

Does no do any line wrapping of the output to 76 characters Implementation derived from the perl MIME::QuotedPrint

Usage

quoted_printable_encode(data)

Arguments

References

http://search.cpan.org/~gaas/MIME-Base64-3.14/QuotedPrint.pm