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.
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.
Previous code:
imapconf %>%
list_server_capabilities()New format:
con$list_server_capabilities()Previous code:
# Listing
imapconf %>%
list_mailboxes()New format:
# Listing
con$list_folders()Previous code:
imapconf %>%
select_mailbox(mbox = "INBOX") # only INBOX is case sensitiveNew format:
con$select_folder(name = "INBOX")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.
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 checkAll search functions now return only the message ids.
Previous code:
result <- imapconf %>%
select_mailbox(mbox = "K-State") %>%
search_before(date_char = "02-May-2019",
by = "UID",
flag = "UNANSWERED")
result$msg_id
New format:
con$select_folder(name = "K-State")
result <- con$search_before(date_char = "02-May-2019",
use_uid = TRUE,
flag = "UNANSWERED")
resultYou can also NEGATE the statement to search for messages NOT BEFORE a date:
Previous code:
results <- imapconf %>%
select_mailbox(mbox = "K-State") %>%
search_before(date_char = "02-May-2019",
negate = TRUE,
by = "UID",
flag = "UNANSWERED",
esearch = TRUE)
results$msg_idNew format:
con$select_folder(name = "K-State")
result <- con$search_before(date_char = "02-May-2019",
use_uid = TRUE,
flag = "UNANSWERED",
negate = TRUE)
resultThis pattern is applied to all SEARCH functions.
Special attention should be paid to the search_string and search_flag methods due to changes in the names and order of the arguments.
Previous code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_string(section_or_field = "FROM", string = "hadley@rstudio.com",
negate = TRUE) # not FROM "hadley@rstudio.com"
results$msg_id
New format:
con$select_folder(name = "INBOX")
result <- con$search_string(expr = "hadley@rstudio.com",
where = "FROM",
negate = TRUE) # not FROM "hadley@rstudio.com"
resultPrevious code:
results <- imapconf %>%
select_mailbox(mbox = "K-State") %>%
search_string(section_or_field = "TEXT", string = "Dear Allan")
New format:
con$select_folder(name = "K-State")
result <- con$search_string(expr = "Dear Allan", where = "TEXT")
resultPrevious code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_flag(flag = "RECENT", by = "UID")
New format:
con$select_folder(name = "INBOX")
result <- con$search_flag(expr = "RECENT", use_uid = TRUE)
resultNow you can check which flags are available in a mail folder with the list_flags() method. Also, you can pass multiple flags as the search criterion.
Previous code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
custom_search(custom_request =
AND(
string(section_or_field = "FROM", string = "@toronto"),
before(date_char = "12-Apr-2019")
)
)
results$msg_idNew format:
con$select_folder(name = "INBOX")
result <- con$search(custom_request =
AND(
string(expr = "@toronto", where = "FROM"),
before(date_char = "12-Apr-2019")
)
)
resultPrevious code:
results <- imapconf %>%
select_mailbox(mbox = "K-State") %>%
search_before(date_char = "10-Mar-2019", by = "UID") %$% #exposition pipe operator
fetch_full_msg(imapconf = imapconf, msg_id = msg_id,
by="UID", write_to_disk = TRUE, keep_in_mem = TRUE,
partial = "0.789")New format:
con$select_folder(name = "K-State")
results <- con$search_before(date_char = "10-Mar-2019", use_uid = TRUE) %>% #regular pipe
con$fetch_body(use_uid = TRUE, write_to_disk = TRUE,
keep_in_mem = TRUE, partial = "0.789")Previous code:
results <- imapconf %>%
select_mailbox(mbox = "K-State") %>%
search_since(date_char = "15-Aug-2019", by = "UID") %$% #exposition pipe operator
fetch_msg_header(imapconf = imapconf,
msg_id = msg_id,
fields = c("DATE", "SUBJECT"),
by = "UID")New format:
con$select_folder(name = "K-State")
results <- con$search_since(date_char = "15-Aug-2019", use_uid = TRUE) %>% #regular pipe
con$fetch_header(use_uid = TRUE, fields = c("DATE", "SUBJECT"))Previous code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_since(date_char = "17-Aug-2019", by = "UID") %$% #exposition pipe operator
fetch_msg_text(imapconf = imapconf, msg_id = msg_id, by = "UID", try_b64decode = TRUE)New format:
con$select_folder(name = "INBOX")
results <- con$search_since(date_char = "17-Aug-2019", use_uid = TRUE) %>% #regular pipe
con$fetch_text(use_uid = TRUE, base64_decode = TRUE))Previous code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_on(date_char = "10-May-2019", by = "UID") %$% #exposition pipe operator
fetch_msg_metadata(imapconf, msg_id = msg_id, by = "UID",
metadata = c("INTERNALDATE", "UID", "ENVELOPE"))New format:
con$select_folder(name = "INBOX")
results <- con$search_since(date_char = "10-May-2019", use_uid = TRUE) %>% #regular pipe
con$fetch_text(use_uid = TRUE, attribute = c("INTERNALDATE", "UID", "ENVELOPE"))You can check the available metadata attributes with metadata_options().
Previous code:
imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_on(date_char = "23-Sep-2019") %$%
fetch_full_msg(imapconf, msg_id=msg_id) %>%
list_attachments()
New format:
con$select_folder(name = "INBOX")
results <- con$search_on(date_char = "23-Sep-2019") %>% #regular pipe
con$fetch_body() %>% # or fetch_text()
list_attachments()Note that list_attachment() is an independent function. It is not a method of the ImapCon class that depends on the connection object.
The new version brings an alternative fetch method (fetch_atachments_list()) for listing attachments without the need of previously executing a fetch_body or fetch_text operation:
con$select_folder(name = "INBOX")
con$search_on(date_char = "23-Sep-2019") %>% #regular pipe
con$fetch_attachments_list()Previous code:
imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_on(date_char = "23-Sep-2019") %$%
fetch_full_msg(imapconf, msg_id=msg_id) %>%
get_attachments()
New format:
con$select_folder(name = "INBOX")
results <- con$search_on(date_char = "23-Sep-2019") %>% #regular pipe
con$fetch_body() %>% # or fetch_text()
get_attachments()The new version brings an alternative fetch method (fetch_atachments()) for downloading attachments without the need of previously executing a fetch_body or fetch_text operation:
con$select_folder(name = "INBOX")
con$search_on(date_char = "23-Sep-2019") %>% #regular pipe
con$fetch_attachments()Previous code:
results <- imapconf %>%
select_mailbox(mbox = "CRAN messages2") %>%
search_since(date_char = "10-May-2019") %$% #exposition pipe operator
copy_msg(imapconf = imapconf, msg_id = msg_id, to_mbox = "INBOX")New format:
con$select_folder(name = "CRAN messages2")
results <- con$search_since(date_char = "10-May-2019") %>%
con$copy_msg(to_folder = "INBOX", reselect = FALSE)Previous code:
results <- imapconf %>%
select_mailbox(mbox = "[Gmail]/Sent") %>%
search_before(date_char = "10-may-2012") %$% #exposition pipe operator
move_msg(imapconf = imapconf, msg_id = msg_id, to_mbox = "CRAN messages2")New format:
con$select_folder(name = "[Gmail]/Sent")
con$search_before(date_char = "10-May-2012") %>%
con$move_msg(to_folder = "CRAN messages2", reselect = FALSE)Previous code:
results <- imapconf %>%
select_mailbox(mbox = "[GMail]/Trash") %>%
get_min_id(flag = "UNSEEN")New format:
con$select_folder(name = "[GMail]/Trash")
con$esearch_min_id(flag = "UNSEEN")Previous code:
results <- imapconf %>%
select_mailbox(mbox = "[Gmail]/Trash") %>%
get_max_id(flag = "UNSEEN")New format:
con$select_folder(name = "[GMail]/Trash")
con$esearch_max_id(flag = "UNSEEN")Previous code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
delete_msg(msg_id = 66128)New format:
con$select_folder(name = "INBOX")
con$delete_msg(msg_id = 66128)Previous code:
results <- imapconf %>%
select_mailbox(mbox = "[Gmail]/Trash") %>%
delete_msg(msg_id = 71772, by = "UID") %$%
expunge(imapconf = imapconf, specific_UID = msg_id)
New format:
con$select_folder(name = "[GMail]/Trash")
con$delete_msg(msg_id = 71772, use_uid = TRUE) %>%
con$expunge() # expunge the specific UID
# or, if the user wants to expunge the entire mail folder:
con$expunge()Previous code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_since(date_char = "18-Aug-2020", by = "UID") %$% #exposition pipe operator
add_flags(imapconf = imapconf, msg_id = msg_id, flags_to_set = "\\Seen")New format:
con$select_folder(name = "INBOX")
con$search_since(date_char = "18-Aug-2020", use_uid = TRUE) %>%
con$add_flags(use_uid = TRUE, flags_to_set = "\\Seen") # system flags need the "\\" prefixPrevious code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_since(date_char = "18-Aug-2020", by = "UID") %$% #exposition pipe operator
remove_flags(imapconf = imapconf, msg_id = msg_id, flags_to_unset = "\\Seen")New format:
con$select_folder(name = "INBOX")
con$search_since(date_char = "18-Aug-2020", use_uid = TRUE) %>%
con$remove_flags(use_uid = TRUE, flags_to_unset = "\\Seen") # system flags need the "\\" prefixPrevious code:
results <- imapconf %>%
select_mailbox(mbox = "INBOX") %>%
search_since(date_char = "18-Aug-2020", by = "UID") %$% #exposition pipe operator
replace_flags(imapconf = imapconf, msg_id = msg_id, flags_to_set = "\\Seen")New format:
con$select_folder(name = "INBOX")
con$search_since(date_char = "18-Aug-2020", use_uid = TRUE) %>%
con$replace_flags(use_uid = TRUE, flags_to_set = "\\Seen") # system flags need the "\\" prefix