mRpostman

IMAP Tools for R in a Tidy Way

Overview

mRpostman provides multiple IMAP (Internet Message Access Protocol) commands based on the RFC 3501 manual (Crispin, 2003), its updates, and other related documents. Besides other features, this package presents functions for listing, selecting and renaming mailboxes, as well as moving, fetching, and searching for messages using several criteria.

mRpostman website: https://allanvc.github.io/mRpostman

First things first …

Before using mRpostman, it is essential to configure your mail account. Many mail providers require authorizing “less secure apps” to access your account from a third part app.

See how to do it for Gmail, Yahoo Mail and AOL Mail.

Gmail

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

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

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

Yahoo Mail

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

2. Click on “Account Info”.

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

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

AOL Mail

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

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

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

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

Introduction

The package is divided in 7 groups of functions:

• configuration: configure_imap();
• mailboxes commands: list_mailboxes(), select_mailbox(), examine_mailbox(), rename_mailbox();
• options listing: list_server_capabilities(),flag_options(), section_or_field_options(), metadata_options();
• search: search_before(), search_since(), search_period(), search_on(), search_sent_before(),search_sent_since(), search_sent_period(), search_sent_on(), search_string(), search_flag(), search_smaller_than(), search_larger_than(), search_younger_than(), search_older_than(), custom_search();
• custom search helper functions:
  • relational operators functions: AND(), OR();
  • criteria definition functions: before(), since(), on(), sent_before(), sent_since(), sent_on(), string(), flag(), smaller_than(), larger_than(), younger_than(), older_than();
• fetch: fetch_full_msg(), fetch_msg_header(), fetch_msg_text(), fetch_msg_metadata();
• miscellania: copy_msg(), get_min_id(), get_max_id(), delete_msg(), expunge(), add_flags(), remove_flags(), replace_flags(), move_msg().

Installation

# CRAN version
install.packages("mRpostman")

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

Basic Usage

1) Configuring IMAP and listing mailboxes

library(mRpostman)

# IMAP settings
# Gmail
imapconf <- configure_imap(url="imaps://imap.gmail.com",
                          username="your_user",
                          password=rstudioapi::askForPassword()
                          )

# Yahoo Mail
# imapconf <- configureIMAP(url="imaps://export.imap.aol.com/",
#                           username="your_user",
#                           password=rstudioapi::askForPassword()
#                           )

# AOL Mail
# imapconf <- configureIMAP(url="imaps://export.imap.aol.com/",
#                           username="your_user",
#                           password=rstudioapi::askForPassword()
#                           )

# you can try another IMAP server

# Listing
imapconf %>%
  list_mailboxes()

2) Examining a Mailbox

# examine mailbox -- number of existent and recent messages
imapconf %>%
  select_mailbox(mbox = "UC Riverside") %>% # mbox names are case sensitive
  examine_mailbox()

3) Searching by period using a flag

# search
results <- imapconf %>%
  select_mailbox(mbox = "INBOX") %>%
  search_period(since_date_char = "17-May-2018",
               before_date_char = "30-Jun-2019",
               flag = "ANSWERED")

results$msg_id

4) Searching for a string in the “Text” section of messages

# search
results <- imapconf %>%
  select_mailbox(mbox = "UC Riverside") %>%
  search_string(section_or_field = "TEXT", string = "Welcome!")

results$msg_id

5) Fetch headers after searching

results <- imapconf %>%
  select_mailbox(mbox = "UC Riverside") %>%
  search_string(section_or_field = "TEXT", string = "Welcome!") %$% # exposition pipe, not %>%!!
  fetch_msg_header(imapconf = imapconf, msg_id = msg_id, 
                 fields = c("DATE", "SUBJECT"))

results

Future Improvements

• better error handling and messages;

• add further IMAP functionalities;

• include SMTP support for sending emails.

If you want to contribute, specially with the SMTP support, please contact the package mantainer.

License

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

References

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

Ooms, J. curl: A Modern and Flexible Web Client for R. R package version 3.3, 2019, https://CRAN.R-project.org/package=curl

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