CRAN_Status_Badge Downloads

Overview

mailR allows users to send emails from R.

It is developed as a wrapper around Apache Commons Email and offers several features to send emails from R such as:

  • using authentication-based SMTP servers
  • sending emails to multiple recipients (including the use of Cc, Bcc, and ReplyTo recipients)
  • attaching multiple files from the file system or from URLs
  • sending HTML formatted emails with inline images

What's new in version 0.6

18th January 2016

Enhancements

  • Refinement to the stripped down text version of HTML emails for incompatible clients (thanks to @dtenenba)
  • Ability to add email headers by passing a named list headers (thanks to @dtenenba)

Installation instructions

You can install the latest development version of mailR using devtools:

install.packages("devtools", dep = T)
library(devtools)
install_github("rpremraj/mailR")

library(mailR)

The latest release of mailR is available on CRAN:

install.packages("mailR", dep = T)

library(mailR)

Usage

To send an email via a SMTP server that does not require authentication:

send.mail(from = "sender@gmail.com",
          to = c("Recipient 1 <recipient1@gmail.com>", "recipient2@gmail.com"),
          cc = c("CC Recipient <cc.recipient@gmail.com>"),
          bcc = c("BCC Recipient <bcc.recipient@gmail.com>"),
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "aspmx.l.google.com", port = 25),
          authenticate = FALSE,
          send = TRUE)

Note that aspmx.l.google.com works for gmail recipients only. Check your gmail spam folder if using this server.

To send an email via a SMTP server that requires authentication:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "Recipient 2 <recipient2@gmail.com>"),
          replyTo = c("Reply to someone else <someone.else@gmail.com>")
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

To send an email with utf-8 or other encoding:

email <- send.mail(from = "Sender Name <sender@gmail.com>",
                   to = "recipient@gmail.com",
                   subject = "A quote from Gandhi",
                   body = "In Hindi :  थोडा सा अभ्यास बहुत सारे उपदेशों से बेहतर है।
                   English translation: An ounce of practice is worth more than tons of preaching.",
                   encoding = "utf-8",
                   smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = T),
               authenticate = TRUE,
                   send = TRUE)

To send an email with one or more file attachments, and set the debug parameter to see a detailed log message:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE,
          attach.files = c("./download.log", "upload.log", "https://dl.dropboxusercontent.com/u/5031586/How%20to%20use%20the%20Public%20folder.rtf"),
          file.names = c("Download log.log", "Upload log.log", "DropBox File.rtf"), # optional parameter
          file.descriptions = c("Description for download log", "Description for upload log", "DropBox File"), # optional parameter
          debug = TRUE)

To send a HTML formatted email:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "<html>The apache logo - <img src=\"http://www.apache.org/images/asf_logo_wide.gif\"></html>", # can also point to local file (see next example)
          html = TRUE,
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

To send a HTML formatted email with embedded inline images:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "path.to.local.html.file",
          html = TRUE,
          inline = TRUE,
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

send.mail expects the images in the HTML file to be referenced relative to the current working directory (something to improve upon in the future).

You can add headers to your emails by passing a named list called headers. Some mail clients allow defining rules based on email headers, where such a feature can come in handy.

send.mail(from = "sender@gmail.com",
          to = c("Recipient 1 <recipient1@gmail.com>", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "aspmx.l.google.com", port = 25),
          headers = list("X-Department" = "Finance", "X-Source" = "Automated report"),
          authenticate = FALSE,
          send = TRUE)

This will result in additional headers added to your email as below:

X-Department: Finance
X-Source: Automated report

MS Exchange server

Provided you have the correct SMTP settings, mailR plays well with MS Exchange. Two mailR users confirmed being able to send emails via Exchange using the following code. I also successfully use mailR at work connecting to MS Exchange.

send.mail(from = from,
          to = to,
          subject = subject,
          body = msg, 
          authenticate = TRUE,
          smtp = list(host.name = "smtp.office365.com", port = 587,
                      user.name = "xxx@domain.com", passwd = "xxx", tls = TRUE))

Sending HTML files compiled using Markdown

mailR does not currently support resolving inline images encoded using the data URI scheme. Use the workaround below instead:

First off, create the HTML file from the R terminal (the important thing here is that options does not include "base64_images" --- see ?markdown::markdownHTMLOptions):

library(knitr)
knit2html("my_report.Rmd", options = "")

Now you can send the resulting HTML file via mailR:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "HTML file generated using Markdown",
          body = "my_report.html",
          html = TRUE,
          inline = TRUE,
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

mailR equivalent of "Blue Screen of Death"

Many folks have run into this error using mailR: Error in ls(envir = envir, all.names = private).

The source of the problem most likely lies in the connection to the SMTP server. This could either be due to incorrect settings (someone confirmed trying several servers at work until finally discovering the one playing well with mailR) or be a proxy issue. Turn on the debug parameter to get more pointers to resolving your problem.

While I will do my best to support you, there is little I can do remotely if you fall into this trap.

Issues/Contibutions

Happy to hear about issues you encounter using mailR via Github's issue tracker.

If you would like to submit a patch to improve mailR, please send a pull request to the develop branch.

Change log

6th December 2015

Enhancements

  • Better handling of errors thrown by Java (thanks to @chlorenz)
  • Email clients unable to view HTML emails now receive stripped down version of message (Fixes #24)

30th December 2014

Features

  • Attach files to the email using URLs, e.g., you can send files from your Dropbox public folder using the URL.
  • A 'debug' parameter to set that will make send.mail() provide a detailed log.
  • Option to set a email address to reply to using the 'replyTo' parameter.

Enhancement

  • Upgraded Commons Email Jar to version 1.3.3
  • Upgraded Javax.mail Jar to version 1.5.2

08th September 2014

Enhancement

  • Better resolution of paths to allow attaching files from locations other than the working directory.
  • Updated documentation to give example of use on MS Exchange

12th May 2014

Features

  • Added support to encode emails using iso-8859-1, utf-8, us-ascii, and koi8-r character sets.
  • The body parameter can point to a locally stored text (or HTML) file and mailR will parse its contents to create the body of the email.

Bug fixes

  • Experimental: changed called methods to set SSL/TLS to true to check whether it resolves issue that causes port number to default to 465.

20th April 2014

Features

  • mailR now allows sending email content as HTML including allowing for embedding images as inline (currently an experimental feature).
  • Email addresses conforming to RFC 2822 allowed, e.g., "FirstName LastName sender@domain.com" allowed.
  • A java stacktrace is printed out in case of failure when sending the email to allow better root cause analysis.

Bug fixes

  • Fixed a bug that incorrectly set the TLS parameter as TRUE whenever the SSL parameter was set as TRUE.


Overview

mailR允许用户从R发送电子邮件。

它作为围绕 Apache Commons Email 的包装开发,并提供了几种从R发送电子邮件的功能作为:

  • 使用基于身份验证的SMTP服务器
  • 将电子邮件发送给多个收件人(包括使用Cc,Bcc和ReplyTo收件人)
  • 从文件系统或URL
  • 附加多个文件
  • 发送带有内联图片的HTML格式的电子邮件

版本0.6的新功能

2016年1月18日

  • 细化不兼容客户端的HTML电子邮件的文本版本(感谢@dtenenba)
  • 通过传递命名列表添加电子邮件标题 headers (感谢@dtenenba)

Installation instructions

您可以使用devtools安装最新的开发版本的mailR:

install.packages("devtools", dep = T)
library(devtools)
install_github("rpremraj/mailR")

library(mailR)

最新版本的mailR可从 CRAN 获取:

install.packages("mailR", dep = T)

library(mailR)

Usage

要通过不需要身份验证的SMTP服务器发送电子邮件:

send.mail(from = "sender@gmail.com",
          to = c("Recipient 1 <recipient1@gmail.com>", "recipient2@gmail.com"),
          cc = c("CC Recipient <cc.recipient@gmail.com>"),
          bcc = c("BCC Recipient <bcc.recipient@gmail.com>"),
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "aspmx.l.google.com", port = 25),
          authenticate = FALSE,
          send = TRUE)

请注意,aspmx.l.google.com仅适用于Gmail收件人。如果使用此服务器,请检查您的Gmail邮件文件夹。

要通过需要身份验证的SMTP服务器发送电子邮件:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "Recipient 2 <recipient2@gmail.com>"),
          replyTo = c("Reply to someone else <someone.else@gmail.com>")
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

要发送带有utf-8或其他编码的电子邮件:

email <- send.mail(from = "Sender Name <sender@gmail.com>",
                   to = "recipient@gmail.com",
                   subject = "A quote from Gandhi",
                   body = "In Hindi :  थोडा सा अभ्यास बहुत सारे उपदेशों से बेहतर है।
                   English translation: An ounce of practice is worth more than tons of preaching.",
                   encoding = "utf-8",
                   smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = T),
               authenticate = TRUE,
                   send = TRUE)

要发送带有一个或多个文件附件的电子邮件,并设置调试参数以查看详细的日志消息:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE,
          attach.files = c("./download.log", "upload.log", "https://dl.dropboxusercontent.com/u/5031586/How%20to%20use%20the%20Public%20folder.rtf"),
          file.names = c("Download log.log", "Upload log.log", "DropBox File.rtf"), # optional parameter
          file.descriptions = c("Description for download log", "Description for upload log", "DropBox File"), # optional parameter
          debug = TRUE)

发送HTML格式的电子邮件:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "<html>The apache logo - <img src=&#34;http://www.apache.org/images/asf_logo_wide.gif&#34;></html>", # can also point to local file (see next example)
          html = TRUE,
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

发送带有嵌入式内嵌图片的HTML格式的电子邮件:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "path.to.local.html.file",
          html = TRUE,
          inline = TRUE,
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

send.mail希望HTML文件中的图像相对于当前的工作目录被引用(将来会有所改进)。

您可以通过传递名为 headers 的命名列表将邮件头添加到电子邮件中。某些邮件客户端允许基于电子邮件标题来定义规则,这样的功能可以派上用场。

send.mail(from = "sender@gmail.com",
          to = c("Recipient 1 <recipient1@gmail.com>", "recipient2@gmail.com"),
          subject = "Subject of the email",
          body = "Body of the email",
          smtp = list(host.name = "aspmx.l.google.com", port = 25),
          headers = list("X-Department" = "Finance", "X-Source" = "Automated report"),
          authenticate = FALSE,
          send = TRUE)

这将导致在您的电子邮件中添加额外的标题,如下所示:

X-Department: Finance
X-Source: Automated report

MS Exchange server

如果您具有正确的SMTP设置,mailR可以与MS Exchange一起播放。两个mailR用户确认能够使用以下代码通过Exchange发送电子邮件。我也在连接到MS Exchange的工作中成功地使用mailR。

send.mail(from = from,
          to = to,
          subject = subject,
          body = msg,
          authenticate = TRUE,
          smtp = list(host.name = "smtp.office365.com", port = 587,
                      user.name = "xxx@domain.com", passwd = "xxx", tls = TRUE))

Sending HTML files compiled using Markdown

mailR目前不支持使用数据URI方案编码的内联图像。请使用下面的解决方法:

首先,从R终端创建HTML文件(这里重要的是该选项不包括base64_images—请参阅?markdown :: markdownHTMLOptions ):

library(knitr)
knit2html("my_report.Rmd", options = "")

现在,您可以通过mailR发送生成的HTML文件:

send.mail(from = "sender@gmail.com",
          to = c("recipient1@gmail.com", "recipient2@gmail.com"),
          subject = "HTML file generated using Markdown",
          body = "my_report.html",
          html = TRUE,
          inline = TRUE,
          smtp = list(host.name = "smtp.gmail.com", port = 465, user.name = "gmail_username", passwd = "password", ssl = TRUE),
          authenticate = TRUE,
          send = TRUE)

mailR equivalent of "Blue Screen of Death"

许多人使用mailR:在ls(envir = envir,all.names = private)中出现错误。

问题的根源在于与SMTP服务器的连接。这可能是由于不正确的设置(有人确认在工作中尝试了几台服务器,直到最终发现与mailR一起播放的服务器)或成为代理问题。打开 debug 参数,以获得更多的指针来解决您的问题。

虽然我会尽力支持你,但如果你陷入这个陷阱,那么我可以做远程工作。

Issues/Contibutions

很高兴听到您通过Github的问题追踪程序使用mailR遇到的问题。

如果您想提交修补程序来改进mailR,请将请求发送到开发分支

Change log

2015年12月6日

  • 更好地处理由Java抛出的错误(感谢@chlorenz)
  • 电子邮件客户端无法查看HTML电子邮件现在会收到消息的修复版本(修复#24)

2014年12月30日

  • 使用URL将文件附加到电子邮件,例如,您可以使用URL从Dropbox公共文件夹发送文件。
  • 要设置的’debug’参数,将使send.mail()提供详细的日志。
  • 选择设置电子邮件地址以回复使用’replyTo’参数。

增强

  • 升级后的Commons Email Jar为1.3.3版
  • 将Javax.mail Jar升级到版本1.5.2

2014年9月8日

增强

  • 更好地解决路径以允许从工作目录以外的位置附加文件。
  • 更新文档以提供在MS Exchange上使用的示例

2014年5月12日

  • 增加了使用iso-8859-1,utf-8,us-ascii和koi8-r字符集对电子邮件进行编码的支持。
  • body参数可以指向本地存储的文本(或HTML)文件,mailR将解析其内容以创建电子邮件的正文。

修正错误

  • 实验:更改调用方法将SSL / TLS设置为true,以检查是否解决导致端口号默认为465的问题。

2014年4月20日

  • mailR现在允许以HTML形式发送电子邮件内容,包括允许嵌入图像为内联(目前为实验功能)。
  • 允许符合RFC 2822的电子邮件地址,例如FirstName LastName sender@domain.com
  • 发送电子邮件以便更好地进行根本原因分析时,打印出一个java堆栈跟踪。

修正错误

  • 修正了SSL参数设置为TRUE时将TLS参数设置为TRUE的错误。




相关问题推荐