title: "gmailr"

output: rmarkdown::html_vignette

vignette: >

In order to use gmailr, you **must** provide your own OAuth client.

The article [Set up an OAuth client](https://gmailr.r-lib.org/dev/articles/oauth-client.html) explains how to obtain an OAuth client and how to configure it for gmailr's use.

The help topics for `?gm_auth_configure` and `?gm_default_oauth_client` will also be useful.

Unless you have reason to do otherwise, my recommendation is to place the JSON file for your OAuth client in the default location, so that it is discovered automatically.

The default location is returned by `rappdirs::user_data_dir("gmailr")`.

Alternatively, you can also make autodiscovery work by exposing the client's JSON filepath as the `GMAILR_OAUTH_CLIENT` environment variable.

If your client is configured for auto-discovery, your gmailr code should "just work", without any explicit configuration around the client:

library(gmailr)

Otherwise, your code must always include a call to `gm_auth_configure()`, probably right after you attach gmailr:

library(gmailr)

gm_auth_configure("path/to/your/oauth_client.json")

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

For most folks and especially in early usage, you can just allow the OAuth dance to be 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 need to be repeated in subsequent sessions, because, by default, your credentials are cached locally and can be refreshed.

If, however, you want to take more control over auth, you can call `gm_auth()` explicitly and proactively.

The arguments that are most useful in practice are:

* `email`: Use this to specify the target user. This can be useful if you have

a cached token and you want code to run without an attempt to get interactive

confirmation that it's OK to use it.

* `scopes`: Following the principle of least privilege, if you have no intention

of sending email, it could be wise to deliberately use a token with a

"read only" scope.

* `token`: In a deployed setting, it can be useful to directly provide a stored

token to gmailr. This use case is documented in `vignettes("deploy-a-token")`.

Here's how a script might begin if the OAuth client can't be auto-discovered and the user needs to request non-default behaviour from `gm_auth()`:

`gm_profile()` is a handy function to confirm that gmailr is using the intended Google identity.

Create a new email with `gm_mime()` and then build it up from parts, using helper functions like `gm_to()` and `gm_subject()`.

You can even add a file attachment with `gm_attach_file()`:

When developing a message, it's a good idea to first create a draft with `gm_create_draft()`

Then you can visit your Gmail drafts in the browser and confirm that the message content and formatting is as you intend.

If you're happy, you can either send that draft from the web UI or with `gm_send_draft()`:

Or you can send the original MIME message with `gm_send_message()`:

You can retrieve email threads with `gm_threads()`:

You can retrieve a specific thread with `gm_thread()`:

The messages in `latest_thread` are stored as a list.

You can then isolate a specific message and access its parts.

If a message has attachments, you can download them all locally with `gm_save_attachments()`:

The Gmail API is free to use for modest levels of activity.

To learn more about Gmail API quotas see <https://developers.google.com/gmail/api/reference/quota>.