mRpostman Basics

Introduction

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.

In this vignette, we present all available functions of this package, but not all the possibilities one can explore.

Allowing Less Secure Apps Access

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

See README.md for more details on Allowing Less Secure Apps Access.

Package Structure

The package is divided in 8 groups of functions:

How do I start?

1) Configuration

After enabling (if needed) “Non secure apps access” in your Mail provider, you have to configure your IMAP settings:

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

Another useful options are: timeout_ms, verbose = TRUE, buffersize and fresh_connect = TRUE. Further ‘curl’ options related to IMAP functionalities can be passed to configure_imap(). See curl::curl_options().

2) Mailbox Commands

2.1) Listing Mailboxes

From now on, you will have to select a mailbox to issue further commands.

2.2) Selecting a Mailbox

2.3) Examining a Mailbox

Select a mailbox and count the number of existent and recent messages.

2.4) Renaming a Mailbox

3) Options Listing

Before executing search and fetch commands, it is recommended to check which are your options regarding to flags, message’s section and fields, and you server capabilities as well.

3.1) Server capabilities

Knowing you server capabilities is important when searching because you can execute an optimized search using “ESEARCH” extension. Also, if your server has the “WITHIN” extension, you can use search_younger_than() and search_older_than() functions.

If your server provides “MOVE” capabilities, you can use move_msg() for moving messages between two mailboxes.

Note that Gmail does not provide the “WITHIN” extension.

3.2) Flag Options

Flags work like tags attached to messages. You can check the options with:

3.2) Section and Fields Options

To see which section and/or fields of a message you can specify in some searches or when fetching a message, use:

3.3) Metadata Options

You can search for a specific content in a message’s metadata as well. Check your options:

6) Fetch

You can fetch full messages, message headers, message texts, or only metadata field(s) of messages.

We usually fetch messages after a search. Given the output of search functions in mRpostman, you will have to use the exposition pipe %$% in order to retrieve and correctly map the imapconf object and the msg_id (search results).

You can also choose to write fetch results to disk (working directory) using write_to_file = TRUE. If you choose to do so, mRpostman creates a folder with the mailbox name in your wd and save the parts of the messages you are fetching to text files using each message sequence number (MSN) or unique identifier (UID) as names.

6.1) Fetch Full Message

Do not forget to re-specify by = "UID" inside fetch_full_msg().

IMPORTANT: Some servers may require larger timeout_ms parameter inside configure_imap() in order to successfully fetch your messages. This is particularly important when your messages have large attachments, which can sensibly increase the fetching time.

6.2) Fetch Message Header

6.3) Fetch Message Text

6.4) Fetch Message Metadata

You can check metadata options with metadata_options().

7) Attachments

After fetching full messages, it is possible to list and get the attachments of those messages.

fetch_full_msg() will return a list with the full message content, i.e. header, text, and attachments. You can access this content and list or get/save the attachments from each message with the following functions.

IMPORTANT: you cannot set keep_in_mem = FALSE in fetch_full_msg() if you intend to list or get attachments after fetching your messages.

7.1) Listing Attachments

This will list your attachments filenames for each fetched message.

7.1) Getting Attachments

get_attachments() will try to convert base64 text inside your message to the appropriate file extension. This will create a folder with the selected mailbox in your working directory. Inside it, you will have other folders with the respective message sequence number (MSN) or unique id (UID), e.g.: msgMSN8 or msgUID8, and the attachment(s) inside it.

The result will be like this:

8) Miscellanea

Here we present other functions to perform useful IMAP operations.

8.1) Copy Message(s)

Copying seach results form “CRAN messages2” to “INBOX” mailbox:

8.2) Get minimum (smaller) message ID with specific flag

8.3) Get maximum (larger) message ID with specific flag

8.4) Delete message(s)

Deleting a specific “msg_id” without a previous search:

8.5) Expunge

Expunges message(s) marked with the “DELETED” flag in a mailbox or a specific message using the specific_UID attribute.

8.6) Add/Remove/Replace Flags

Adding, removing and replacing one or more flags to messages.

8.6.1) Add Flags

You cannot add a flag that is the antonym of an already existent flag in the message, e.g. cannot add “UNSEEN” flag when a message already has flag “SEEN”. Use replace_flags() instead.

8.7) Move Message(s)

move_msg() uses IMAP “MOVE” EXTENSION. Check if your server supports “MOVE” capability with list_server_capabilities().

If your server does not provide “MOVE” capability, the same result can be achieved with a combination of add_flags() and expunge():

References

Babcock, N., Introduction to IMAP, Blog, May 2016, https://nbsoftsolutions.com/blog/introduction-to-imap.

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/

Freed, N. and N. Borenstein, Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types, RFC 2046, DOI: 10.17487/RFC2046, November 1996, https://www.rfc-editor.org/info/rfc2046.

Resnick, P., Ed., Internet Message Format, RFC 2822, DOI: 10.17487/RFC2822, April 2001, https://www.rfc-editor.org/info/rfc2822.

Resnick, P., Ed., Internet Message Format, RFC 5322, DOI: 10.17487/RFC5322, October 2008, https://www.rfc-editor.org/info/rfc5322.