In order to use gmailr, you must provide your own
OAuth client. The article Set up an
OAuth client explains how to obtain an OAuth client and how to
configure it for gmailr’s use. The help topics for
?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
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:
Otherwise, your code must always include a call to
gm_auth_configure(), probably right after you attach
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:
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
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
library(gmailr) gm_auth_configure("path/to/your/oauth_client.json") gm_auth( "[email protected]", scopes = "gmail.readonly", cache = "some/nice/directory/" )
gm_profile() is a handy function to confirm that gmailr
is using the intended Google identity.
gm_profile() #> Logged in as: #> * email: [email protected] #> * num_messages: 121 #> * num_threads: 121
Create a new email with
gm_mime() and then build it up
from parts, using helper functions like
You can even add a file attachment with
When developing a message, it’s a good idea to first create a draft
gm_create_draft() Then you can visit your Gmail drafts
in the browser and confirm that the message content and formatting is as
If you’re happy, you can either send that draft with
Or you can send the original MIME message with
You can retrieve email threads with
You can retrieve a specific thread with
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
tmp2 <- tempfile("attachments-") dir.create(tmp2) gm_save_attachments(my_msg, path = tmp2) # let's take a peek tmp2 |> list.files(full.names = TRUE, pattern = "[.]csv$") |> read.csv() |> head() #> X mpg cyl disp hp drat wt qsec vs am gear carb #> 1 Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 #> 2 Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 #> 3 Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 #> 4 Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 #> 5 Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2 #> 6 Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1
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.