Migrating old code to the new mRpostman’s syntax

Source: vignettes/code_migration.Rmd

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:

  • All main functions, except list_attachments and the custom-search helper functions, now are methods of the R6 class ImapConf;

  • The way the connection token is passed through functions (now methods) has changed. The connection handle is created inside configure_imap() (or ImapCon$new()) and modified with custom requests from the methods that trigger IMAP commands. As a consequence, the password is now hidden inside the curl handle C pointer, resulting in a more secure token chain. This resulted in changes in every request function. These functions (that are methods now) do not use config_handle() anymore, and a call to curl::set_opt() is made in every request function so that a custom request is supplied or replaced by a new one in the original handle.

  • The “by” argument used in search and fetch functions was replaced by use_uid, which is a logical now with the default value set as FALSE. This is equivalent to the former by = MSN default configuration.

  • all functions that returned invisible(0L) now return invisible(TRUE)

  • Users that prefer a tidy approach, only need to apply the pipe %>% operator between search and fetch methods (or other complementary operations), in which messages’ ids are carried from one level to another. The exposition pipe %$% is not necessary anymore.

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