Migrating old code to the new mRpostman’s syntax

Introduction

This vignette aims to provide an easy source of code migration examples so old mRpostman users can transition between the old version and the new format which implements an OO approach trough the use of R6 class and methods.

This is the summary of the main modifications in the package between versions 0.3.1 and 0.9.X:

In the following sections, we present some code migration examples between the old and the new version of mRpostman.

1) Configuring the IMAP connection

Previous code:

library(mRpostman)

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

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


New format:

library(mRpostman)

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

# alternative
con <- ImapCon$new(url="imaps://outlook.office365.com",
                   username="your_user@company.com",
                   password=rstudioapi::askForPassword())

Although the object that is created is different (now we have an R6 ImapCon class), the code to create a connection object is pretty much the same, but with an alternative that uses the “initialize” method of the R6 class.

Other useful options are timeout_ms, verbose = TRUE, and buffersize. Further ‘curl’ options related to IMAP functionalities can be passed to configure_imap(), depending on the libcurl version installed on the user’s machine. See curl::curl_options(). In this new version, there is an important curl parameter exposed, xoauth2_bearer, which enables OAuth2.0 authentication. For more details, check the “IMAP OAuth2.0 authentication in mRpostman” vignette.

2) Listing Server Capabilities

Previous code:

imapconf %>%
  list_server_capabilities()

New format:

con$list_server_capabilities()

3) Mailbox Commands

3.1) Listing mail folders

Previous code:

# Listing
imapconf %>%
  list_mailboxes()

New format:

# Listing
con$list_folders()

3.2) Folder selection

Previous code:

imapconf %>%
  select_mailbox(mbox = "INBOX") # only INBOX is case sensitive

New format:

con$select_folder(name = "INBOX")

3.3) Examining a mail folder

Previous code:

imapconf %>%
  select_mailbox(mbox = "K-State") %>%
  examine_mailbox()

New format:

con$select_folder(name = "K-State")

con$examine_folder()

In the new format, the previously selected folder is kept during the session unless you execute a new selection.

3.4) Renaming a mail folder

Previous code:

imapconf %>%
  select_mailbox(mbox = "CRAN messages") %>%
  rename_mailbox(new_name = "CRAN messages2") %>%
  list_mailboxes() # and list again to check



New format:

con$select_folder(name = "CRAN messages")

con$rename_folder(new_name = "CRAN messages2")

con$list_mail_folders() # and list again to check