mRpostman

CRAN_Status_Badge Downloads from the RStudio CRAN mirror CRAN/METACRAN R-CMD-check

An IMAP Client for R

Overview

mRpostman is an easy-to-use IMAP client that provides tools for message searching, selective fetching of message attributes, mailbox management, attachment extraction, and several other IMAP features. The aim of this package is to pave the way for email data analysis in R. To do so, mRpostman makes extensive use of the {curl} package and the libcurl C library.

mRpostman’s official website: https://allanvc.github.io/mRpostman/

IMPORTANT:

  1. In version 0.9.0.0, mRpostman went trough substantial changes, including ones that have no backward compatibility with versions <= 0.3.1. A detailed vignette on how to migrate your mRpostman’s deprecated code to the new syntax is available at “Migrating old code to the new mRpostman’s syntax”.

  2. Old versions of the libcurl C library ({curl}’s main engine) will cause the malfunction of this package. If your libcurl’s version is above 7.58.0, you should be fine. In case you intend to use OAuth 2.0 authentication, then you will need libcurl >= 7.65.0. To learn more about the OAuth 2.0 authentication in this package, refer to the “Using IMAP OAuth2.0 authentication in mRpostman” vignette.

Authentication

There are two ways of connecting to your IMAP server: using plain or OAuth2.0 authentication. Here, we only describe the plain authentication process. If you want to use OAuth2.0 authentication, please read the aforementioned vignette.

Allowing less secure apps access

When using plain authentication, most of the mail providers will require the user to enable less secure apps access. Once it is done, you will be able to access your mailbox using a “third party app” as mRpostman.

Plain authentication

Before using mRpostman, it is essential to configure the access to your email account. Various mail providers require that you enable “less secure apps” access to accept plain authentication between the IMAP server and a third-party app.

Let’s see how to configure simple plain authentication for Gmail, Yahoo Mail, AOL Mail, Hotmail, and Office 365.

Outlook - Office 365

There is no need to execute any external configuration. Please, note that the url parameter in configure_imap() should be set as url = "imaps://outlook.office365.com", and the username should be set as user@yourcompany.com.

Hotmail

There is no need to execute any external configuration. Please, note that the url parameter in configure_imap() should be set as url = "imaps://imap-mail.outlook.com", and the username should be set as user@hotmail.com.

Gmail

  1. Go to the Gmail website and log in with your credentials.

  2. Then, go to https://myaccount.google.com/u/1/lesssecureapps?pageId=none

  1. Set “Allow less secure apps” to ON.

Yahoo Mail

  1. Go to the Yahoo Mail website and log in with your credentials.

  2. Click on “Account Info”.

  1. Click on “Account Security” on the left menu.

  1. Then, set “Allow apps that use less secure sign in” ON

AOL Mail

  1. Go to the AOL Mail website and log in with your credentials.

  2. Click on “Options” and then on “Account Info”.

  1. Click on “Account Security” on the left menu.

  1. After, set “Allow apps that use less secure sign in” ON

Introduction

From version 0.9.0.0 onward, mRpostman is implemented under the OO paradigm, based on an R6 class called ImapCon. Its derived methods, and a few independent functions enable the R user to perform a myriad of IMAP commands.

The package is divided in 8 groups of operations. Below, we present all the available methods and functions:

Installation

# CRAN version
install.packages("mRpostman")

# Dev version
if (!require('remotes')) install.packages('remotes')
remotes::install_github("allanvc/mRpostman")

Basic Usage

1) Configure an IMAP connection and list the server’s capabilities


library(mRpostman)

# Outlook - Office 365
con <- configure_imap(url="imaps://outlook.office365.com",
                      username="your_user@company.com",
                      password=rstudioapi::askForPassword()
)

# other IMAP providers that were tested: Hotmail ("imaps://imap-mail.outlook.com"),
#  Gmail (imaps://imap.gmail.com), Yahoo (imaps://imap.mail.yahoo.com/), 
#  AOL (imaps://export.imap.aol.com/), Yandex (imaps://imap.yandex.com)

# Other non-tested mail providers should work as well

con$list_server_capabilities()

2) List mail folders and select “INBOX”


# Listing
con$list_mail_folders()

# Selecting
con$select_folder(name = "INBOX")

3) Search messages by date


res1 <- con$search_on(date_char = "02-Jan-2020")

res1

4) Customizing a search with multiple criteria

Executing a search by string:


# messages that contain either "@k-state.edu" OR "ksu.edu" in the "TO" header field
res2 <- con$search(OR(
  string(expr = "@k-state.edu", where = "TO"),
  string(expr = "@ksu.edu", where = "TO")
))

res2

5) Fetch messages’ text using single-search results


res3 <- con$search_string(expr = "Welcome!", where = "SUBJECT") %>%
  con$fetch_text(write_to_disk = TRUE) # also writes results to disk

res3

6) Attachments

You can list the attachments of one or more messages with:

  1. the list_attachments() function:

con$search_since(date_char = "02-Jan-2020") %>%
  con$fetch_text() %>% # or with fetch_body()
  list_attachments() # does not depend on the 'con' object

… or more directly with:

  1. fetch_attachments_list()

con$search_since(date_char = "02-Jan-2020") %>%
  con$fetch_attachments_list()

If you want to download the attachments of one or more messages, there are also two ways of doing that.

  1. Using the get_attachments() method:

con$search_since(date_char = "02-Jan-2020") %>%
  con$fetch_text() %>% # or with fetch_body()
  con$get_attachments()

… and more directly with the

  1. fetch_attachments() method:

con$search_since(date_char = "02-Jan-2020") %>%
  con$fetch_attachments()

Future Improvements

Known bugs

License

This package is licensed under the terms of the GPL-3 License.

References

Crispin, M. (2003), INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1, RFC 3501, March 2003, https://www.rfc-editor.org/rfc/rfc3501.

Heinlein, P. and Hartleben, P. (2008). The Book of IMAP: Building a Mail Server with Courier and Cyrus. No Starch Press. ISBN 978-1-59327-177-0.

Ooms, J. (2020), curl: A Modern and Flexible Web Client for R. R package version 4.3, https://CRAN.R-project.org/package=curl

Stenberg, D. Libcurl - The Multiprotocol File Transfer Library, https://curl.se/libcurl/