# gmailr

Exposing the [Gmail API](https://developers.google.com/gmail/api) from
R.

## Installation

Install the released version of gmailr from CRAN:

``` r
install.packages("gmailr")
```

Or install the development version from GitHub with:

``` r
# install.packages("pak")
pak::pak("r-lib/gmailr")
```

## Attach gmailr

``` r
library(gmailr)
```

## Setup and auth

In order to use gmailr, you **must** provide your own OAuth client. This
is documented in the article [Set up an OAuth
client](https://gmailr.r-lib.org/dev/articles/oauth-client.html). The
article goes deeply into how to create an OAuth client and also how to
configure it for gmailr’s use. If you already have an OAuth client or
know how to create one, the help topics for
[`?gm_auth_configure`](https://gmailr.r-lib.org/reference/gm_auth_configure.md)
and
[`?gm_default_oauth_client`](https://gmailr.r-lib.org/reference/gmailr-configuration.md)
are more concise resources for just the client configuration piece.

Configuring an OAuth client is step 1 of 2 for getting ready to use
gmailr. Step 2 is to complete the so-called “OAuth dance”, which is
triggered automatically upon first need. You are taken to a web browser,
where you must select or login as the Google user you want to use
(authenticate yourself) and give your OAuth client permission to do
Gmail stuff on your behalf (authorize). The OAuth dance does not
(necessarily) need to be repeated in subsequent sessions. See
[`?gm_auth`](https://gmailr.r-lib.org/reference/gm_auth.md) if these
defaults aren’t appropriate for your use case and you’d like to take
more control.

You can call
[`gm_profile()`](https://gmailr.r-lib.org/reference/gm_profile.md) to
confirm that you are using the intended Google identity.

## Compose and send an email

Create a new email with
[`gm_mime()`](https://gmailr.r-lib.org/reference/gm_mime.md) and build
it up from parts, using helper functions like
[`gm_to()`](https://gmailr.r-lib.org/reference/accessors.md) and
[`gm_subject()`](https://gmailr.r-lib.org/reference/accessors.md).

``` r
test_email <-
  gm_mime() |>
  gm_to("PUT_A_VALID_EMAIL_ADDRESS_THAT_YOU_CAN_CHECK_HERE") |>
  gm_from("PUT_THE_GMAIL_ADDRESS_ASSOCIATED_WITH_YOUR_GOOGLE_ACCOUNT_HERE") |>
  gm_subject("this is just a gmailr test") |>
  gm_text_body("Can you hear me now?")
```

When developing the message, you might want to use
[`gm_create_draft()`](https://gmailr.r-lib.org/reference/gm_create_draft.md),
if you’d like to view a draft and verify that it’s formatted as you
expect. Then you can send the draft with
[`gm_send_draft()`](https://gmailr.r-lib.org/reference/gm_send_draft.md)
or send the original MIME message with
[`gm_send_message()`](https://gmailr.r-lib.org/reference/gm_send_message.md).

``` r
# Verify it looks correct, i.e. look at your Gmail drafts in the browser
d <- gm_create_draft(test_email)

# If all is good with your draft, then you can send the existing draft
gm_send_draft(d)
#> Draft Id: 19c01d17602c97f8 
#> NULL

# or the existing MIME message
gm_send_message(test_email)
#> Id: 19c01d1785c5f52f
```

## Read email

You can retrieve all email threads with
[`gm_threads()`](https://gmailr.r-lib.org/reference/gm_threads.md) or
retrieve a specific thread with
[`gm_thread()`](https://gmailr.r-lib.org/reference/gm_thread.md). You
can then isolate a specific message and access its parts.

``` r
# view recent threads
my_threads <- gm_threads(num_results = 10)

# retrieve the latest thread by retrieving the first ID
latest_thread <- gm_thread(gm_id(my_threads)[[1]])

# messages in the thread will now be in a list
# retrieve parts of a specific message with the accessors
my_msg <- latest_thread$messages[[1]]

gm_date(my_msg)
#> [1] "Tue, 27 Jan 2026 15:37:11 -0800"
gm_subject(my_msg)
#> [1] "this is just a gmailr test"
gm_body(my_msg)
#> [[1]]
#> [1] "Can you hear me now?\r\n"
```

## Where to learn more

More details are available in the [Get
started](https://gmailr.r-lib.org/articles/gmailr.html) article and in
gmailr’s [other articles](https://gmailr.r-lib.org/articles/index.html).

## Policies

[Privacy policy](https://tidyverse.org/google_privacy_policy/)

# Package index

## Authentication and authorization

These functions are used to auth with the gmail API.
[`gm_auth_configure()`](https://gmailr.r-lib.org/reference/gm_auth_configure.md)
and [`gm_auth()`](https://gmailr.r-lib.org/reference/gm_auth.md) are the
most important for most users.

- [`gm_auth()`](https://gmailr.r-lib.org/reference/gm_auth.md) :
  Authorize gmailr
- [`gm_deauth()`](https://gmailr.r-lib.org/reference/gm_deauth.md) :
  Clear current token
- [`gm_auth_configure()`](https://gmailr.r-lib.org/reference/gm_auth_configure.md)
  [`gm_oauth_client()`](https://gmailr.r-lib.org/reference/gm_auth_configure.md)
  : Edit auth configuration
- [`gm_scopes()`](https://gmailr.r-lib.org/reference/gm_scopes.md) :
  Produce scopes specific to the Gmail API
- [`gm_has_token()`](https://gmailr.r-lib.org/reference/gm_has_token.md)
  : Is there a token on hand?
- [`gm_profile()`](https://gmailr.r-lib.org/reference/gm_profile.md) :
  Get info on current gmail profile
- [`gm_token()`](https://gmailr.r-lib.org/reference/gm_token.md) :
  Produce configured token
- [`gm_default_email()`](https://gmailr.r-lib.org/reference/gmailr-configuration.md)
  [`gm_default_oauth_client()`](https://gmailr.r-lib.org/reference/gmailr-configuration.md)
  : Configuring gmailr
- [`gm_token_write()`](https://gmailr.r-lib.org/reference/gm_token_write.md)
  [`gm_token_read()`](https://gmailr.r-lib.org/reference/gm_token_write.md)
  **\[experimental\]** : Write/read a gmailr user token

## Messages

These functions create, modify, query and delete email messages.

- [`gm_delete_message()`](https://gmailr.r-lib.org/reference/gm_delete_message.md)
  : Permanently delete a single message
- [`gm_id()`](https://gmailr.r-lib.org/reference/gm_id.md) : Get the id
  of a gmailr object
- [`gm_import_message()`](https://gmailr.r-lib.org/reference/gm_import_message.md)
  : Import a message into the gmail mailbox from a mime message
- [`gm_insert_message()`](https://gmailr.r-lib.org/reference/gm_insert_message.md)
  : Insert a message into the gmail mailbox from a mime message
- [`gm_message()`](https://gmailr.r-lib.org/reference/gm_message.md) :
  Get a single message
- [`gm_messages()`](https://gmailr.r-lib.org/reference/gm_messages.md) :
  Get a list of messages
- [`gm_modify_message()`](https://gmailr.r-lib.org/reference/gm_modify_message.md)
  : Modify the labels on a message
- [`gm_send_message()`](https://gmailr.r-lib.org/reference/gm_send_message.md)
  : Send a message from a mime message
- [`gm_trash_message()`](https://gmailr.r-lib.org/reference/gm_trash_message.md)
  : Send a single message to the trash
- [`gm_untrash_message()`](https://gmailr.r-lib.org/reference/gm_untrash_message.md)
  : Remove a single message from the trash

## Threads

These functions create, modify, query and delete email threads.

- [`gm_delete_thread()`](https://gmailr.r-lib.org/reference/gm_delete_thread.md)
  : Permanently delete a single thread.
- [`gm_modify_thread()`](https://gmailr.r-lib.org/reference/gm_modify_thread.md)
  : Modify the labels on a thread
- [`gm_thread()`](https://gmailr.r-lib.org/reference/gm_thread.md) : Get
  a single thread
- [`gm_threads()`](https://gmailr.r-lib.org/reference/gm_threads.md) :
  Get a list of threads
- [`gm_trash_thread()`](https://gmailr.r-lib.org/reference/gm_trash_thread.md)
  : Send a single thread to the trash
- [`gm_untrash_thread()`](https://gmailr.r-lib.org/reference/gm_untrash_thread.md)
  : Remove a single thread from the trash.

## Drafts

These functions create, modify, query and delete email drafts.

- [`gm_create_draft()`](https://gmailr.r-lib.org/reference/gm_create_draft.md)
  : Create a draft from a mime message
- [`gm_delete_draft()`](https://gmailr.r-lib.org/reference/gm_delete_draft.md)
  : Permanently delete a single draft
- [`gm_draft()`](https://gmailr.r-lib.org/reference/gm_draft.md) : Get a
  single draft
- [`gm_drafts()`](https://gmailr.r-lib.org/reference/gm_drafts.md) : Get
  a list of drafts
- [`gm_send_draft()`](https://gmailr.r-lib.org/reference/gm_send_draft.md)
  : Send a draft

## Labels

These functions create, modify, query and delete email labels.

- [`gm_create_label()`](https://gmailr.r-lib.org/reference/gm_create_label.md)
  : Create a new label
- [`gm_delete_label()`](https://gmailr.r-lib.org/reference/gm_delete_label.md)
  : Permanently delete a label
- [`gm_label()`](https://gmailr.r-lib.org/reference/gm_label.md) : Get a
  specific label
- [`gm_labels()`](https://gmailr.r-lib.org/reference/gm_labels.md) : Get
  a list of all labels
- [`gm_update_label()`](https://gmailr.r-lib.org/reference/gm_update_label.md)
  [`gm_update_label_patch()`](https://gmailr.r-lib.org/reference/gm_update_label.md)
  : Update a existing label.

## Attachments

These functions work with email attachments. `gm_attchments()` to list
the attachments of a message and
[`gm_save_attachments()`](https://gmailr.r-lib.org/reference/gm_save_attachments.md)
are generally the most useful for most users.

- [`gm_save_attachments()`](https://gmailr.r-lib.org/reference/gm_save_attachments.md)
  : Save attachments to a message
- [`gm_save_attachment()`](https://gmailr.r-lib.org/reference/gm_save_attachment.md)
  : Save the attachment to a file
- [`gm_attachments()`](https://gmailr.r-lib.org/reference/gm_attachments.md)
  : Retrieve information about attachments
- [`gm_attachment()`](https://gmailr.r-lib.org/reference/gm_attachment.md)
  : Retrieve an attachment to a message

## Email creation (MIME)

These functions are used to query or set parts of a Multipurpose
Internet Mail Extensions (MIME) messages. They can be used to generate
new emails from scratch.

- [`gm_to()`](https://gmailr.r-lib.org/reference/accessors.md)
  [`gm_from()`](https://gmailr.r-lib.org/reference/accessors.md)
  [`gm_cc()`](https://gmailr.r-lib.org/reference/accessors.md)
  [`gm_bcc()`](https://gmailr.r-lib.org/reference/accessors.md)
  [`gm_date()`](https://gmailr.r-lib.org/reference/accessors.md)
  [`gm_subject()`](https://gmailr.r-lib.org/reference/accessors.md) :
  Methods to get values from message or drafts
- [`gm_body()`](https://gmailr.r-lib.org/reference/gm_body.md) : Get the
  body text of a message or draft
- [`gm_mime()`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_to(`*`<mime>`*`)`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_from(`*`<mime>`*`)`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_cc(`*`<mime>`*`)`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_bcc(`*`<mime>`*`)`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_subject(`*`<mime>`*`)`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_text_body()`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_html_body()`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_attach_part()`](https://gmailr.r-lib.org/reference/gm_mime.md)
  [`gm_attach_file()`](https://gmailr.r-lib.org/reference/gm_mime.md) :
  Create a mime formatted message object
- [`as.character(`*`<mime>`*`)`](https://gmailr.r-lib.org/reference/as.character.mime.md)
  : Convert a mime object to character representation

## Miscellaneous tools

These functions don’t fit neatly into the above categories and are
generally used internally or for debugging.

- [`gm_history()`](https://gmailr.r-lib.org/reference/gm_history.md) :
  Retrieve change history for the inbox
- [`quoted_printable_encode()`](https://gmailr.r-lib.org/reference/quoted_printable_encode.md)
  : Encode text using quoted printable

# Articles

### All vignettes

- [Deploy a token](https://gmailr.r-lib.org/articles/deploy-a-token.md):
- [gmailr](https://gmailr.r-lib.org/articles/gmailr.md):
- [Set up an OAuth
  client](https://gmailr.r-lib.org/articles/oauth-client.md):
- [Sending Messages With
  Gmailr](https://gmailr.r-lib.org/articles/sending_messages.md):