---
title: "Sending Messages With Gmailr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Sending Messages With Gmailr}
  %\usepackage[utf8]{inputenc}
---

```{r}
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r}
#| label: setup
#| message: false
library(gmailr)
```

## Constructing a MIME message

### Text

First we will construct a simple text only message

```{r}
#| label: sending_messages_simple
text_msg <- gm_mime() |>
  gm_to("james.f.hester@gmail.com") |>
  gm_from("me@somewhere.com") |>
  gm_text_body("Gmailr is a very handy package!")
```

You can convert the message to a properly formatted MIME message using `as.character()`.

```{r}
#| label: sending_messages_simple_print
strwrap(as.character(text_msg))
```

### HTML

You can also construct html messages.  It is customary to provide a text
only message along with the html message, but with modern email clients this is
not strictly necessary.

```{r}
#| label: sending_messages_html
html_msg <- gm_mime() |>
  gm_to("james.f.hester@gmail.com") |>
  gm_from("me@somewhere.com") |>
  gm_html_body("<b>Gmailr</b> is a <i>very</i> handy package!")
```

### Attachments

You can add attachments to your message in two ways.

1. If the data is in a file, use `gm_attach_file()`.  The mime type is
   automatically guessed by `mime::guess_type`, or you can specify it yourself
   with the `type` parameter.
```{r}
#| label: sending_messages_attachments_2
write.csv(file = "iris.csv", iris)

msg <- html_msg |>
  gm_subject("Here are some flowers") |>
  gm_attach_file("iris.csv")
```

2. If the data are already loaded into R, you can use `gm_attach_part()` to attach the binary data to your file.
```{r}
#| label: sending_messages_attachments_1
msg <- html_msg |>
  gm_attach_part(part = charToRaw("attach me!"), name = "please")
```

### Including images

You can also add use attached images in HTML by setting the Content ID feature
of mime emails. This can be done by referencing the image via a `<img
src=cid:xyz>` tag using the `id` argument of `send_file()`. The tag value can
by any unique identifier. E.g. here is an example of including a ggplot2 image


```{r}
# First create a plot to send, and save it to mtcars.png
mtcars$gear <- as.factor(mtcars$gear)

png("mtcars.png", width = 400, height = 400, pointsize = 12)
with(
  mtcars,
  plot(hp,
    mpg,
    col = as.factor(gear),
    pch = 19,
    xlab = "Horsepower",
    ylab = "Miles / gallon"
  )
)
legend("topright",
  title = "# gears",
  pch = 19,
  col = seq_along(levels(mtcars$gear)),
  legend = levels(mtcars$gear)
)
dev.off()

# Next create an HTML email that references the plot as 'foobar'
email <- gm_mime() |>
  gm_to("someaddress@somewhere.com") |>
  gm_from("someaddress@somewhere.com") |>
  gm_subject("Cars report") |>
  gm_html_body(
    '<h1>A plot of <b>MotorTrend</b> data <i>(1974)</i></h1>
    <br><img src="cid:foobar">'
  ) |>
  gm_attach_file("mtcars.png", id = "foobar")
```

```{r}
#| include: false
unlink("mtcars.png")
```

## Uploading
### Create Draft

You can upload any mime message into your gmail drafts using `gm_create_draft()`.
Be sure to give yourself at least `compose` permissions first.

```{r}
#| label: sending_messages_create_draft
#| eval: false
gm_create_draft(file_attachment)
```

### Insert

This inserts the message directly into your mailbox, bypassing gmail's default
scanning and classification algorithms.

```{r}
#| label: sending_messages_insert_message
#| eval: false
gm_insert_message(file_attachment)
```

### Import

This imports the email as though it was a normal message, with the same
scanning and classification as normal email.

```{r}
#| label: sending_messages_file_attachment
#| eval: false
gm_import_message(file_attachment)
```

## Sending

### Draft

`gm_send_draft()` sends an email using the `draft_id` of an existing draft
(possibly created with `gm_create_draft()`).

```{r}
#| label: sending_messages_send_draft
#| eval: false
my_drafts <- gm_drafts()

gm_send_draft(gm_id(my_drafts, "draft_id")[1])
```
### Message

You can also send an email message directly from a `mime` object using `gm_send_message()`.

```{r}
#| label: sending_messages_send_message
#| eval: false
gm_send_message(file_attachment)
```

```{r}
#| label: sending_messages_clenup
#| include: false
unlink("iris.csv")
```

## Troubleshooting

### Gmail API error 400: Mail service not enabled

It is possible to have a high-functioning Google account that does not have
Gmail enabled. For example, your account might be fully operational with
respect to Google Drive and yet have no mail capabilities. Such an account
cannot be used with the Gmail API and therefore with `gmailr`. However, you
will still be able to complete the `gmailr` authorization process via
`gm_auth()`. The problem will only reveal itself upon the first attempt to
use the API and it will look something like this:

```
 Error in gmailr_POST(c("messages", "send"), user_id, class = "gmail_message",  :
  Gmail API error: 400
  Mail service not enabled
```

You can confirm the account's lack of mail capability by visiting
`https://mail.google.com/mail/` while logged in. If you don't already have
Gmail, this link gives you the option of adding mail to your existing account
or creating a new, mail-capable account.