The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

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/

Cite mRpostman: A. V. C. Quadros, “mRpostman: An IMAP Client for R”, Journal of Open Research Software, vol. 12, no. 1, p. 4, 2024, doi: 10.5334/jors.480. http. Refer to citation("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.

  3. Most mail providers discontinued less secure apps access. If it is still available and you are comfortable with this type of access you can enable this option for your account on your mail provider. Some providers, such as Yahoo Mail, also offer the option to generate password to be used by third-party apps such as mRpostman. The other option, as mentioned above, is to set up OAuth2 (two-factor authentication) in order to access your mailbox. Please also refer to the “Using IMAP OAuth2.0 authentication in mRpostman” vignette.

Providers and their IMAP urls

Provider IMAP Server
Gmail imap.gmail.com
Office 365 outlook.office365.com*
Outlook.com (Hotmail and Live.com) imap-mail.outlook.com
Yahoo Mail imap.mail.yahoo.com
iCloud Mail imap.mail.me.com
AOL Mail imap.aol.com
Zoho Mail imap.zoho.com
Yandex Mail imap.yandex.com
GMX Mail imap.gmx.com
Mail.com imap.mail.com
FastMail imap.fastmail.com

* For Office 365 accounts, the username should be set as user@yourcompany.com or user@youruniversity.edu for example.

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, http.

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, http.

Quadros, A. V. C. mRpostman: An IMAP Client for R, Journal of Open Research Software, vol. 12, no. 1, p. 4, 2024, doi: 10.5334/jors.480. http.

Stenberg, D. Libcurl - The Multiprotocol File Transfer Library, http.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.