Main features
- added RFC 2047 quoted-printable and base64 MIME header decoder
NEWS.md
clean_msg_text() no longer errors on messages carrying 8-bit bytes that are invalid in the session encoding (e.g. undeclared legacy charsets or binary fragments in old real-world corpora — Error in gsub("=\r\n", "", msg): input string 1 is invalid). Such strings are now made valid up front (latin1-to-UTF-8, which maps every byte and preserves ASCII) before any regex operation, and again after each base64 decoding, which can reintroduce raw bytes; declared-charset handling is unaffected. Additionally, the base64 decoding heuristic no longer aborts on payloads decoding to binary with embedded NULs (rawToChar() errors that a handler-less tryCatch() never actually caught): NUL bytes are dropped, and on any decoding error the text is kept unchanged instead of erroring. Found while decoding the full Enron corpus through the new sandbox ingestion.new ingest_maildir(): uploads any local maildir-style directory (one RFC 5322 message per file) to a folder on the connected IMAP server via APPEND — mail server backups, exported archives, or public corpora. Files are appended verbatim; failures are skipped with a warning, and an invisible manifest data.frame (path, size, appended) is returned.
new enron_sandbox(): on-demand download of the public Enron e-mail corpus (CMU May 7, 2015 release; ~423 MB, one time, consented via ask and cached under tools::R_user_dir("mRpostman", "cache")), with subset selection by custodian, folder-name pattern, and Date: header window, ingested through ingest_maildir() — one server folder per custodian. Provides real data for demonstrations and teaching on top of the synthetic corpus of sandbox_corpus(). The download is never triggered by examples, tests, or vignettes, and fails gracefully offline with an informative message.
clean_fetch_results() did not recognize Dovecot’s tagged completion line, which carries timing information (e.g. A240 OK Fetch completed (0.001 + 0.000 secs).), so fetch_text(), fetch_body(), and fetch_metadata() results kept the trailing server response. Found while testing against the new Docker sandbox; affects any Dovecot-based provider (e.g. FastMail, GMX, many self-hosted servers).new reproducible IMAP sandbox: the package now ships a disposable local IMAP server (Dovecot on Alpine Linux, in inst/docker/ — reachable via system.file("docker", package = "mRpostman")) and two new exported functions to exercise the package against it without a real mail account. sandbox_corpus() deterministically generates a corpus of synthetic RFC 822 messages (fixed RNG seed; Date: headers spread over 2020, large bodies, MIME encoded-word subjects, quoted-printable bodies, CSV, PNG, and one-page PDF attachments — all generated deterministically in base R — with repeated filenames, reply chains, and planned flags), and populate_sandbox() stores it in a mailbox using the package’s own IMAP operations (APPEND, CREATE, STORE). A thin Rscript wrapper (inst/docker/populate_mailbox.R) does the same from the shell.
new vignette “A reproducible IMAP sandbox with Docker” (sandbox) with setup instructions and a guided tour of searching, fetching, decoding, attachments, SORT/THREAD, and flag operations over the synthetic corpus.
testthat file (test-sandbox-corpus.R): determinism, RNG-state preservation, RFC 822 well-formedness, feature/metadata consistency, and round-trip decoding of the generated encoded-word subjects and quoted-printable bodies through the package’s own decoders.ImapCon$append_msg() no longer hangs after the server’s `+ go aheadcontinuation when it is called after another command on the same connection. The shared connection handle still carried the previous operation'sCURLOPT_CUSTOMREQUEST, which conflicted with theCURLOPT_UPLOADthatAPPEND` relies on; the custom request is now reset before the upload.
ImapCon$status() no longer returns an empty result after a mid-session reconnection. When libcurl transparently reconnects (e.g. after a stale connection), the response buffer also carries the CAPABILITY line, whose LIST-STATUS token — together with the ... authenticated (Success) line — made the parser lock onto the wrong parentheses. parse_status_counts() now anchors on the untagged `* STATUS` response.
list_server_capabilities()) instead of letting the server reply with a cryptic BAD Unknown command. This affects sort() (SORT), thread() (THREAD=), get_quota() / get_quota_root() (QUOTA), namespace() (NAMESPACE), id() (ID), unselect_folder() (UNSELECT), list_special_use_folders() (SPECIAL-USE), move_msg() (MOVE), and the ESEARCH path (search(esearch = TRUE), esearch_count(), esearch_min_id(), esearch_max_id()). Capabilities are fetched once and cached per connection. Mandatory IMAP4rev1 (RFC 3501) commands are unaffected.reworded the package description and README overview to state that mRpostman is a session-based IMAP client that implements the full functionality of the IMAP4rev1 protocol (RFC 3501) from within R.
the README now maps each IMAP command to its mRpostman method(s) — split into the mandatory RFC 3501 core and the optional, capability-checked extensions (with RFC references) — and its “available methods and functions” list was brought up to date with every method added since v1.1.6.
removed the obsolete code_migration vignette (migrating pre-0.9.0.0 syntax).
rewrote the OAuth2.0 vignette (xoauth2.0) with exact, image-free steps and R code to authenticate to Gmail via OAuth2.0 — covering both httr’s built-in flow and a manual loopback flow — plus a troubleshooting section. httr and jsonlite were added to Suggests.
fixed the basics vignette figures, which were not rendering on the package website.
new ImapCon$close_folder() (IMAP CLOSE) closes the selected folder and permanently removes its \Deleted messages; and ImapCon$unselect_folder() (IMAP UNSELECT, RFC 3691) closes it without expunging (requires the server UNSELECT capability). Both leave the connection with no folder selected.
new ImapCon$id() method (IMAP ID, RFC 2971) to exchange client/server identification. It optionally sends the client id fields (a named character vector) and returns the server’s id as a named character vector; parsed by an offline-tested parse_id() helper.
new ImapCon$get_quota_root() and ImapCon$get_quota() methods for the IMAP quota extension (GETQUOTAROOT / GETQUOTA, RFC 2087). They return a data.frame with quota_root, resource, usage, and limit (one row per resource; STORAGE is reported by the server in kibibytes). Requires the server QUOTA capability. The responses are parsed by an offline-tested parse_quota() helper.
new ImapCon$append_msg() method to append a full RFC 822 message to a mail folder (IMAP APPEND) — e.g. saving a message to Drafts or Sent. Unlike every other operation it is performed by an upload (CURLOPT_UPLOAD, via a read callback like curl::send_mail()) rather than a customrequest; it reuses the connection handle and restores it out of upload mode afterwards. The message is stored with the server’s default flags.
both new areas are documented in the basics vignette.
new ImapCon$namespace() method issuing the IMAP NAMESPACE command (RFC 2342). It returns a named list (personal, other_users, shared), each a data.frame of namespace prefix/delimiter pairs (or NULL when the server returns NIL). Requires the server NAMESPACE capability.
new ImapCon$list_special_use_folders() method issuing LIST (SPECIAL-USE) (RFC 6154). It returns a data.frame mapping each special-use folder to its attribute (\Sent, \Drafts, \Junk, \Trash, \Archive, \All, \Flagged). Requires the server SPECIAL-USE capability.
both are parsed by dedicated internal helpers (parse_namespace(), parse_special_use()) covered by offline tests, and documented in the basics vignette.
new ImapCon$sort() method for server-side sorting (IMAP SORT, RFC 5256). It returns the message ids ordered by the server according to the sort keys (by, any subset of ARRIVAL, CC, DATE, FROM, SIZE, SUBJECT, TO), with optional reverse (descending), a criteria restriction (default ALL), use_uid, and a configurable char_set. The server-provided order is preserved (the result is deliberately not passed through the ascending-order fix_search_stripping() used by search()). Requires the server SORT capability.
new ImapCon$thread() method for server-side threading (IMAP THREAD, RFC 5256), with algorithm (REFERENCES or ORDEREDSUBJECT), a criteria restriction, use_uid, and a configurable char_set. It returns a list of integer vectors, one per top-level thread (nested parent/child ids are flattened into their thread). Requires a server THREAD= capability.
both new methods are parsed by dedicated internal helpers (parse_sort(), parse_thread()) and share a new execute_ordered_search() engine that mirrors the search request/retry logic but keeps the server ordering intact. The parsers are covered by offline tests.
new ImapCon$list_subscribed_folders() method to list the subscribed mail folders (IMAP LSUB), complementing list_mail_folders() (which issues LIST and returns every folder).
new ImapCon$subscribe_folder() and ImapCon$unsubscribe_folder() methods to subscribe to / unsubscribe from a mail folder (IMAP SUBSCRIBE / UNSUBSCRIBE), i.e. to add or remove it from the set returned by list_subscribed_folders().
new ImapCon$noop() method issuing the IMAP NOOP command. It does nothing on the server other than resetting the inactivity autologout timer, which makes it useful as a keep-alive during long idle periods.
LIST response parsing was extracted from list_mail_folders_int() into a shared internal parse_folder_list() helper (parameterized by the command keyword), now used by both list_mail_folders() and the new list_subscribed_folders(). This removes the duplicated parsing that previously lived in the retry branch and adds offline test coverage (LIST, LSUB, and the Yandex | hierarchy separator).new ImapCon$delete_folder() method to delete a mail folder (IMAP DELETE), completing the folder-management set alongside create_folder() and rename_folder(). The target folder must be named explicitly (there is no implicit “delete the selected folder”), and a confirmation message is printed unless mute = TRUE.
new ImapCon$status() method to query a mail folder’s counters via the IMAP STATUS command without selecting the folder (unlike examine_folder(), which issues EXAMINE). It returns a named vector with the requested data items — any subset of MESSAGES, RECENT, UIDNEXT, UIDVALIDITY, and UNSEEN (all by default), configurable via the new items argument. The response is parsed by a dedicated internal parse_status_counts() helper, so the result stays correct regardless of the order in which the server returns the items.
search_string() (and the custom search()) now support non-ASCII search terms. When the term contains non-ASCII characters, the command declares CHARSET UTF-8 and sends the term as UTF-8 bytes, so servers such as Gmail can match accented/non-Latin text (GitHub issue #12). Pure-ASCII searches are unchanged.
fetch_attachments() and get_attachments() gained a local_dir argument to set the base directory where attachments are saved (default ".", the working directory). The <username>/<mail folder>/<msg id> subfolder tree is created inside it (GitHub issue #15).
new ImapCon$disconnect() method to release the connection handle when a session is finished (GitHub issue #13).
decode_mime_header() now honors the character set declared in the RFC 2047 encoded-word (=?<charset>?<enc>?...?=) instead of guessing it heuristically. The declared charset is passed to iconv() (via a new internal apply_charset() helper) for both the quoted-printable (Q) and base64 (B) encodings, so headers in any iconv-supported charset now decode correctly — including ones the previous heuristic could not handle or mislabeled (e.g. Windows-1251 and KOI8-R Cyrillic, ISO-8859-2/Windows-1250 Central European, Big5, Shift_JIS, EUC-KR). The legacy heuristic is kept only as a fallback for “loose” quoted-printable strings that carry no declared charset.
the message-body decoders (decode_mime_text(), used by clean_msg_text()) now honor the charset declared in the MIME Content-Type for quoted-printable and base64 parts, via the same apply_charset() helper as the header decoder. The previous heuristic is kept as a fallback when no charset is declared, and the charset is not re-applied to parts already normalized to UTF-8 by the HTML parser (avoiding a double conversion).
the esearch = TRUE search path no longer evaluates server-provided text as R code. The ALL sequence-set of the ESEARCH response is now expanded by a dedicated parser (parse_esearch_all()) instead of eval(parse(...)), removing a code-injection/robustness risk while producing identical results for valid responses.
examine_folder() no longer assumes the server returns both EXISTS and RECENT, in that order. The counts are now parsed and labeled by their actual keyword (new internal parse_examine_counts()), so the result stays correct when the order differs and no longer errors when RECENT is absent.
fixed several English spelling and grammar errors throughout the roxygen2 documentation of the ImapCon R6 methods and the helper functions (e.g. “trough” → “through”, “successfuly” → “successfully”, “queries follows” → “queries follow”, “multiples arguments” → “multiple arguments”, “depend on ESEARCH” → “depends on ESEARCH”).
corrected copy-paste mistakes in the method documentation: search_string() now belongs to the search by string family (was search by date), search_sent_on() now belongs to search by date (was search by size), and the size parameter of the size-search helpers is described in bytes instead of seconds.
fixed broken examples in the ImapCon documentation: select_folder() (was select_mail_folder()), a missing closing parenthesis in the replace_flags() example, a missing space after #' in the fetch_text() example, and <- in the fetch_attachments_list() example (was <).
removed a duplicated \link{younger_than} cross-reference in the custom search documentation (now correctly links to older_than) and cleaned up duplicated lines in the search_since() date_char description.
fixed typos in user-facing messages, including the flag confirmation messages (“successfuly” → “successfully”), the esearch_*_id() type-check message (“must of type” → “must be of type”), the buffer size and length checks (“equal or greater than” → “equal to or greater than”), and the dead-connection error (ImapConf$new() → ImapCon$new()).
fixed English spelling and grammar errors in the README and in the basics, code_migration, and xoauth2.0 vignettes, including invalid Portuguese month abbreviations in date examples (“30-Ago-2019” → “30-Aug-2019”) and misspelled function/class references (e.g. confiure_imap(), list_atachments(), fetch_attachents(), ImapConf).
decode_quoted_printable_header(): changed the conversion engine to iconv and added useBytes = TRUE to the gsub() call; and added support to ISO-8859-10 and Windows-1252 (Nordic/latin6), and ISO-8859-9 and Windows-1254 (Turkish) encodings.
decode_quoted_printable_text(): changed the conversion engine to iconv and added useBytes = TRUE to the gsub() call; and added support to ISO-8859-10 and Windows-1252 (Nordic/latin6), and ISO-8859-9 and Windows-1254 (Turkish) encodings.
zzz() - removed message from the transition to R6 structure and added the citation request instead.
decode_quoted_printable_header() and decode_quoted_printable_text() (needed to rewind to v1.1.2 before moving again to v1.1.4)clean_fetch_results(): added argument useBytes = TRUE to all gsub() calls. According to Kurt Hornik, “fetching fails using current versions of R for some contents with non-ASCII characters”.
Added bypass argument as_is to methods/functions get_attachments(), execute_fetch_attachments(), fetch_attachments(); and as_is functionality to get_attachments() and execute_fetch_attachments as proposed by Paul Smith to handle non-base64 files.
list_attachments()
README.Rmd
./allanvcq@gmail.com/INBOX/UID1430/ instead of “imap.gmail.com/INBOX/UID1430”. This will allow users to better differentiate between local folders, when using different mailboxes in the same server.added the clean_msg_text() function. It will be particularly useful for cleaning and preparing message text retrieved with fetch_body(..., mime_level = 1). These texts can be used for sentiment analysis and other text mining tasks;
added internal functions decode_mime_text() and decode_quoted_printable_text(). The second is called by the first one;
renamed the original decode_quoted_printable called from decode_mime_header() to decode_quoted_printable_text();
included the xml2 and the rvest packages as dependencies because of the addition of the clean_msg_text().
mime_level argument to the fetch_body() method. Now, the user can choose whether the fetch will retrieve the full body content or an specific one. This is particularly helpful for retrieving clean text parts without inline and regular attachments for instance.adapts to the new return pattern of MS Exchange IMAP servers without losing the compatibility with others;
fixed the misbehavior for the attachment fetching of message in message attachments. Now, either fetch_attachments() and fetch_text/body() + get_attachments() combo can handle this specific case;
changed the attachment identification to the “name” field instead of the “filename”. In very rare cases, the “filename” field identification fails because of encoding errors on the sender’s side;
incorrect decoding of ordinary words (such as “ResearchGate”, for instance) in decode_mime_header().
decode_mime_header() function
get_attachments() and fetch_attachments() for correctly setting the filenameslist_mail_folders(): fixed the regex related to the hierarchy separator to accept the “|” separator. It was causing a misbehavior in Yandex accounts.
clean_fetch_results() (internal): fixed the regex responsible for cleaning the attachment content. It was causing a misbehavior in Yandex accounts. All calls to gsub() in this function now have ignore.case = TRUE.
reset_*() methods: Except by reset_password() and reset_xoauth2_bearer(), the other methods were not reflecting the changes in the ImapCon$con_params object, although they were succesfully modifying the ImapCon$con_handle, which was sufficient to work properly. It could cause the user to thing that the changes wouldn’t taking any effect.
fetch_attahments() changed to “\n::mRpostman: the fetch operation is complete.\n”;rename_folder().reset_*() methods now are x in order to prevent wordy method calls and repetition. The older ones will be deprecated in version 0.9.1-2;reset_ssl() method had the name changed to reset_use_ssl() to better reflect the connection parameter to be reset.metadata argument in fetch_metadata now is attribute.In this version, in order to drastically enhance the package usability, we had to adopt several profound changes with no backward compatibility. We are sorry that these changes will be painful for old users but it will certainly be strongly beneficial even in the short term. The primary update is that mRpostman now is built on an R6 class and its methods, providing a much more convenient and elegant way of usage. It is structured following an OO framework that works well either with the tidy style using pipes or under the base R approach. The syntax now will be ConnectionObject$method(), where the ConnectionObject is created with configure_imap() or ImapCon$new(). This completely modifies how the connection handle and other configuration information is passed among the methods/functions in mRpostman.
This is a summary of the main modifications in the package:
The package title has changed to mRpostman: An IMAP client for R
All the main functions, except by list_attachments and the custom-search helper functions, now are methods of the R6 class ImapConf;
The way the connection token is passed between the functions has changed. The connection handle is created only inside configure_imap() (or ImapCon$new()) and only modified with custom requests inside the methods. As a consequence, the password, username, and other connection parameters are hidden inside the curl handle C pointer, resulting in a more secure token chain. This resulted in changes in every request-functions. They 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 argument “by” used in search and fetch functions was replaced by use_uid, which is a logical with 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)
list_mailboxes() -> list_mail_folders()
select_mailbox() -> select_folder()
examine_mailbox() -> examine_folder()
custom_search() -> search()
fetch_full_msg() -> fetch_body()
fetch_msg_header() -> fetch_header()
fetch_msg_text() -> fetch_text()
fetch_msg_metadata() -> fetch_metadata()
get_min_id() -> esearch_min_id()
get_max_id() -> esearch_max_id()
count_msg() -> esearch_count()
mbox -> name:
OBS: type has not changed, still a character string
Affected functions: select_folder() (former select_mailbox), examine_folder() (former select_mailbox), rename_folder() (former rename_mailbox)
reselect_mbox -> reselect:
OBS: type has not changed, still a logical with TRUE as default
Affected functions: rename_folder() (former rename_mailbox), copy_msg(), move_msg()
by -> use_uid:
OBS: type HAS CHANGED from a character string with default value MSN to a logical with FALSE as default. Former by = "UID" now is equivalent to use_uid = TRUE
Affected functions:
all search operations: search() (former custom search), search_before(), search_since(), search_on(), search_period(), search_sent_before(), search_sent_since(), search_sent_on(), search_sent_period(), search_larger_than(), search_smaller_than(), search_older_than(), search_younger_than(), search_flag(), search_string();
all fetch operations: fetch_body() (former fetch_full_msg), fetch_header() (former fetch_msg_text), fetch_text() (former fetch_msg_text), fetch_metadata() (former fetch_msg_metadata);
all complementary operations: copy_msg(), move_msg(), delete_msg(), esearch_max_id() (former get_max_id), esearch_min_id() (former get_min_id), esearch_count() (former count_msg), add/replace/remove_flags()
flag -> name:
OBS: type has not changed, still a character string containing the flag name
Affected functions: search_flag(), flag() (custom search helper function)
string -> expr:
OBS: type has not changed, still a character string containing the string or expression to be searched; shifted to the first position of the arguments in the functions/methods.
Affected functions: search_string(), string() (custom search helper function)
section_or_fields -> where:
OBS: type has not changed, still a character string containing the name of the message section or the header field in which to execute the search for the informed expression;
Affected functions: search_string(), string() (custom search helper function)
specific_UID -> msg_uid:
OBS: type has not changed, still a numeric vector containing message uids
Affected functions: expunge()
to_mbox -> to_folder:
OBS: type has not changed, still a character vector containing the folder name
Affected functions: copy_msg(), move_msg()
try_b64decode -> base64_decode:
OBS: type has not changed, still a logical with default value FALSE
Affected functions: fetch_text() (former fetch_msg_text)
show_pass -> removed:
OBS: This argument is not available anymore.
Affected functions: configure_imap()
fresh_connect -> removed:
OBS: This curl argument is not accepted by mRpostman anymore.
Affected functions: configure_imap()
return_imapconf -> removed:
OBS: This argument is not available anymore.
Affected functions: all search methods.
search_string() and string():
expr (former string) now is 1st; where (former section or fields)` now is 2ndesearch_count() (former count_msgs), esearch_max_id() (former get_max_id), esearch_min_id() (former get_min_id):
use_uid (former by) and flag
returned object:
functions/methods that returned invisible(0L) in the previous version, now return invisible(TRUE). Applied to: select_folder(), create_folder(), rename_folder(), get_attachments(), fetch_attachments(), expunge()
all search functions now return NA when there is no match. The previous behavior was to return 0.
add/replace/remove_flags() methods now invisibly return the msg_ids in case the user intends to chain any further operation (perhaps expunge) using the pipe.
default value of arguments:
retries = 2 -> retries = 1 in all functionscreate_folder(): Create a new mail folder (New IMAP functionality!)
list_flags(): List flags in a selected mail folder (New IMAP functionality!)
fetch_attachments_list(): Fetch attachments’ list without the previously need to fetch a message’s text or body
fetch_attachments(): Fetch attachments without the previously need to fetch a message’s text or body
reset_*(): reset one (*) of the original parameter that were informed in configure_imap().
mute:
OBS: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE. In the case of the fetch_*() functions, it only has effect when write_to_disk = TRUE.
applied to methods/functions: select_folder(), create_folder(), rename_folder(), fetch_body(), fetch_header(), fetch_text(), fetch_metadata(), copy_msg(), move_msg(), delete_msg(), expunge(), add/replace/remove_flags(), get_attachments(), fetch_attachments()
override:
OBS: A logical. If TRUE, overrides existent files containing the same name in the local directory. Default is FALSE.
applied to methods/functions: get_attachments(), fetch_attachments().
xoauth2_bearer:
OBS: added the xoauth2_bearer parameter for oauth2.0 authentication (libcurl >= 7.70 is required because of bugs in previous versions). In Linux, if you use Ubuntu 20, you should be fine. Versions below this require updating libcurl if the user intends to use oauth2.0 authentication.
applied to methods/functions: configure_imap()
examine_folder() and rename_folder():
name argumentflag argument in all search functions:
flag now accept more than one flag as a filtering parametername argument in search_flag
flag parameter was added to the search_string methodget_attachments() and fetch_attachments():
override argument was added and allows to control over the file writing processretry bug fixed: it was causing the loss of the search and fetch customrequest when executing a retry + selection operation or when there was a considerable period between two requests given that the second depends on a previous folder selection. When there was a considerable delay between the executions of two commands, the curl handle would establish a new connection to execute the last one, but without the mail folder selection. This was causing an error during the retry or the next IMAP command since the IMAP session would have lost the mail folder selection. This bug was happening mainly when the functions were used under the base R approach
fixed bug that was writing metadata .txt files as textUID*.txt
Better error handling:
An unique internal function called check_args() was created to check for the validity of the arguments of all methods and functions, replacing all the cheack_args_* specific functions
added the response_error_handling() function to catch operation/resolving timeout errors and login error as well
All methods work as wrappers for internal functions with similar names and suffix *_int
Search, Fetch and Complementary functions have a central internal function called execute_*() that is responsible for configuring and executing the requests towards the IMAP server
removed config_handle()as the connection token chain has changed
added config_conn_handle() which is called inside the iniliaze() method of the R6 ImapCon class.
added adjust_repeated_filenames(), serialize_filenames() and extract_MIME_level_and_filenames() as helper functions to the new attachments fetch operations
added adjust_folder_name() which is called in almost every request function
some regex adjustments were made to fix_search_stripping(), has_attachment(), and clear_fetch_results()
in list_server_capabilities(): changed IMAP command to “CAPABILITY” instead of establishing a new connection
REGEX structure replacement from stringr to base R in: list_server_capabalities(), examine_folder() (former examine_mailbox), list_mail_folders() (former list_mailboxes), select_folder() (former select_mailbox)
fetch_attachments_list() and fetch_attachments() are a faster and smart way to respectively list and download messages’ attachments. They do not depend on a former fetching step, unlike list_attachments() and get_attachments(). the new methods use BODYSTRUCTURE metadata fetching to identify the attachments, and fetch_attachments() also issue a FETCH BODY[level.MIME] command to fetch only the parts of the messages that contain the attachments. This prevents unnecessary fetching when users are only interested in attachments. However, get_attachments() and list_attachments() are still available in the package.
All fetch_* methods, and get_attachments() now use a different path for saving the fetched files. The folder to be created now will have the following structure: imap_server > mail_folder >
Fetched messages that are saved to disk will have different filename structures:
use_uid = FALSE: bodyuse_uid = TRUE: bodyConfirmation messages were added to methods: select_folder(), create_folder(), rename_folder(), copy_msg(), move_msg(), delete_msg(), expunge(), fetch_*(), add/replace/remove_flags(), get_attachments(), fetch_attachments()
A startup message informing about the breaking changes of the version were added by creating the zzz.R file
Besides the mRpostman Basics vignette, two more were added: Migrating old code to the new mRpostman’s syntax, and IMAP OAuth2.0 authentication in mRpostman
get_attachments() function:
check_args_get_atatchments() helper function:
"content_disposition"
list_attachments() function:
"content_disposition" to outputcheck_args_list_attachments() function:
check_args_list_attachments()
has_attachment() helper function:
loop_fetch_msg_*() functions group:
get_attachments():
check_args_get_attachments():
"content_disposition"
get_attachments() function:
get_attachments()
has_attachment(), check_args_get_attachments()
list_attachments() function:
list_attachments()
loop_fetch_msg_*() functions:
examineMailbox() to examine_mailbox()
loop_fetch_full_msg()
[\\/:*?\"<>|], considering WIN-*NIX-OSX casesfetch_full_msg():
added warning message related to get_attachments() when keep_in_mem = TRUE
fetch_*() functions:
added attr(msg_list, which = 'mbox') = new_imapconf$mbox to all – to be used by get_attachments()
list_server_capabilities() function:
converted regex match/extraction from stringr to base R
examples:
fixed typo - from “configureIMAP” to “configure_imap” in the following functions examples: list_mailboxes(), list_server_capabilities()
changed all imaps://imap.gmail.com server examples to a generic one: imaps://your.imap.server.com
devtools to remotes because the former depends on curl
configure_imap() exampleconfigure_imap() examplecount_msgs():
loop_fetch_msg_XXXX() functions for fetching msgs:
select_mailbox(imapconf = new_imapconf, mbox = new_imapconf$mbox) inside the tryCatch in the while loop – it prevents errors especially when messages have larger attachments taking too much time to fetch. In some IMAP servers (such as Yandex) it may lose the mbox selection. Other alternatives: set a larger timeout_ms in configure_imap().list_mailboxes():
list_mailboxes() was modified to deal with the return of Yandex IMAP server: from .*\" \"*(.*?)\\"\r\n' to '.*\" \"*(.*?)[(\\"\r\n)|(\r\n\\*)]
configure_imap():
@param retries description typo: from “retires” to “retries”conifg_handle():
@family config, so it does not appear as “see also” in config_IMAP()
flag_options():
@note to be more clear@family check args search:
@param esearch typo: from code{1,2,3,4,5} to \code{1,2,3,4,5}
changed function name patterns to those specified in the tidyverse style guide
changed return from mailboxes operation functions and some miscellanea functions:
select_mailbox(), rename_mailbox(), copy_msg(), move_msg(), delete_msg(), expunge(), add/remove/replace_flags() outputs are invisible and only return imapconf or a list (imapconf+msg_ids).changed package logo