mRpostman

Travis-CI Build Status CRAN_Status_Badge Downloads from the RStudio CRAN mirror CRAN/METACRAN

IMAP Toolkit for R

Overview

mRpostman makes extensive use of ‘curl’ and ‘libcurl’ capabilities, providing functions for mailboxes and electronic messages manipulation, such as moving, deleting, and searching messages using specific criteria, setting and clearing flags, selective fetching of message attributes and more.

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

First things first …

Before using mRpostman, it is essential to configure your email 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

  1. 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”.

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

  1. 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”.

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

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

Introduction

The package is divided in 8 groups of functions:

Installation

# CRAN version
install.packages("mRpostman")

# Dev version
if (!require('remotes')) install.packages('remotes')
remotes::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 <- configure_imap(url="imaps://imap.mail.yahoo.com/",
#                            username="your_user",
#                            password=rstudioapi::askForPassword()
#                           )

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

# Yandex Mail
# imapconf <- configure_imap(url="imaps://imap.yandex.com",
#                            username="your_user",
#                            password=rstudioapi::askForPassword()
#                           )

# you can try another IMAP server and see if it works

# 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

6) Attachments

This will list all the attachments filenames for each fetched message.

imapconf %>%
  select_mailbox(mbox = "INBOX") %>%
  search_since(date_char = "23-Sep-2019") %$%
  fetch_full_msg(imapconf, msg_id=msg_id) %>%
  list_attachments()

This extracts and decode your base64 text attachments from messages, and save them locally.

imapconf %>%
  select_mailbox(mbox = "INBOX") %>%
  search_since(date_char = "23-Sep-2019") %$%
  fetch_full_msg(imapconf, msg_id=msg_id) %>%
  get_attachments()

Future Improvements

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/