forked from datawookie/emayili
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
205 lines (140 loc) · 5.53 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include=FALSE}
knitr::opts_chunk$set(comment=NA)
```
# emayili <img src="man/figures/emayili-hex.png" align="right" alt="" width="120" />
<!-- badges: start -->
[](https://cran.r-project.org/package=emayili)
[](https://travis-ci.org/datawookie/emayili)
[](https://codecov.io/github/datawookie/emayili)
[](https://lifecycle.r-lib.org/articles/stages.html)
<!-- badges: end -->
emayili is a package for sending emails from R. The design goals are:
- works on all manner of SMTP servers and
- has minimal dependencies (or dependencies which are easily satisfied).
The package name is an adaption of the Zulu word for email, imeyili.
## Installation
Get the stable version from [CRAN](https://CRAN.R-project.org/package=emayili).
```{r eval=FALSE}
install.packages("emayili")
```
Or grab it directly from [GitHub](https://github.com/datawookie/emayili).
```{r eval=FALSE}
# Install from the master branch.
remotes::install_github("datawookie/emayili")
# Install from the development branch.
remotes::install_github("datawookie/emayili", ref = "dev")
```
## Usage
First create a message object.
```{r message=FALSE}
library(emayili)
library(magrittr)
email <- envelope()
```
### Creating a Message
The message has class `envelope`.
```{r}
class(email)
```
Add addresses for the sender and recipient.
```{r}
email <- email %>%
from("alice@yahoo.com") %>%
to("bob@google.com") %>%
cc("craig@google.com")
```
There are also `bcc()` and `reply()` functions for setting the `Bcc` and `Reply-To` fields.
Add a subject.
```{r}
email <- email %>% subject("This is a plain text message!")
```
Add a text body. You can use `html()` to add an HTML body.
```{r eval=FALSE}
email <- email %>% text("Hello!")
```
Add an attachment.
```{r eval=FALSE}
email <- email %>% attachment("image.jpg")
```
You can also create the message in a single command:
```{r eval=FALSE}
email <- envelope(
to = "bob@google.com",
from = "alice@yahoo.com",
subject = "This is a plain text message!",
text = "Hello!"
)
```
Simply printing a message displays the header information.
```{r}
email
```
You can identify emails which have been sent using `{emayili}` by the presence of an `X-Mailer` header which includes both the package name and version.
If you want to see the complete MIME object, just convert to a string.
```{r eval=FALSE}
as.character(email)
```
### Adding an Inline Image
Adding an inline image to an HTML message is possible. There are two ways to achieve this.
_1. Base64 Encoding_
First you'll need to [Base64 encode](https://en.wikipedia.org/wiki/Base64) the image.
```{r eval=FALSE}
img_base64 <- base64enc::base64encode("image.jpg")
```
Then create the HTML message body.
```{r eval=FALSE}
html_body <- sprintf('<html><body><img src="data:image/jpeg;base64,%s"></body></html>', img_base64)
```
And finally add it to the email.
```{r eval=FALSE}
email <- envelope() %>% html(html_body)
```
_Note:_ It's important that you specify the appropriate media type (`image/jpeg` for JPEG and `image/png` for PNG).
_2. Using a CID_
Unfortunately some mail clients (like Gmail) will not display Base64 encoded images. In this case using a CID is a working alternative.
First create the message body which references an image by CID.
```{r eval=FALSE}
html_body <- '<html><body><img src="cid:image"></body></html>'
```
Then attach the image and specify the `cid` argument.
```{r eval=FALSE}
email <- envelope() %>%
html(html_body) %>%
attachment(path = "image.jpg", cid = "image")
```
### Sending a Message
Create a SMTP server object and send the message.
```{r eval=FALSE}
smtp <- server(host = "smtp.gmail.com",
port = 465,
username = "bob@gmail.com",
password = "bd40ef6d4a9413de9c1318a65cbae5d7")
smtp(email, verbose = TRUE)
```
To see the guts of the message as passed to the SMTP server:
```{r eval=FALSE}
print(email, details = TRUE)
```
### Using STARTTLS
If you're trying to send email with a host that uses the STARTTLS security protocol (like Google Mail, Yahoo! or AOL), then it will most probably be blocked due to insufficient security. In order to circumvent this, you can grant access to less secure apps. See the links below for specifics:
* [Google](https://myaccount.google.com/security) ([details](https://support.google.com/accounts/answer/6010255))
* [Yahoo!](https://login.yahoo.com/account/security) and
* [AOL](https://login.aol.com/account/security).
## Standards Documents
The following (draft) standards documents relate to emails:
- [RFC 2822](https://tools.ietf.org/html/rfc2822)
- [RFC 5322](https://tools.ietf.org/html/rfc5322)
- [RFC 6854](https://tools.ietf.org/html/rfc6854) (an update to RFC 5322).
## Similar Packages
There is a selection of other R packages which also send emails:
- [blastula](https://cran.r-project.org/package=blastula)
- [blatr](https://cran.r-project.org/package=blatr) (Windows)
- [gmailr](https://cran.r-project.org/package=gmailr)
- [mail](https://cran.r-project.org/package=mail)
- [mailR](https://cran.r-project.org/package=mailR)
- [sendmailR](https://cran.r-project.org/package=sendmailR)
- [ponyexpress](https://github.com/ropensci-archive/ponyexpress)