mRpostman (version 0.3.1)

custom_search: Custom Search

Description

Allows a combination of several arguments using helper functions that serve as relational operators, such as OR and AND; and criteria helper functions such as before, since, on, sent_before, sent_since, sent_on, flag, string, smaller_than, larger_than, younger_than, or younger_than, in order to execute a custom search (with multiple arguments).

Usage

custom_search(imapconf, custom_request, negate = FALSE, by = "MSN",
  esearch = FALSE, return_imapconf = TRUE, retries = 2)

Arguments

imapconf

An object of class imapconf generated with configure_imap and with a mbox item added after a mailbox selection with select_mailbox.

custom_request

A string directly specifying what to search or constructed by a combination of operators helper functions OR and AND, and criteria helper functions such as before, since, on, sent_before, sent_since, sent_on, flag, string, smaller_than, larger_than, younger_than, or younger_than.

negate

If TRUE, negates the search and seeks for "NOT search_criterion". Default is FALSE.

by

Which id (MSN or UID) to use when searching for messages. "MSN" or message squence number is a message's relative position to the older message in the mailbox. It may change after deleting or moving messages. For instance, if a message is deleted, message sequence numbers are reordered to fill the gap. "UID" or unique identifier is always the same during the life cycle of a message. Default is "MSN".

esearch

A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It allows to condense results to message sets to cut down on transmission costs, e.g. 1:5 instead of writing ids individually such as 1,2,3,4,5. It can be used along with buffersize to avoid results stripping. Check if your IMAP server supports SEARCH with list_server_capabilities.

return_imapconf

A logical. If TRUE, the function returns a list of length 2, containing the imapconf object (IMAP settings) and the search results as message ids ("MSN" or "UID"). If FALSE, returns only the message ids as a numeric vector. Default is TRUE.

retries

Number of attempts to connect and execute the command. Default is 2.

Value

Depending on the return_imapconf parameter, it can be a list of length 2 containing the imapconf object and message ids resulted from search, or a numeric vector containing only message ids.

See Also

Other Date-search operations: search_before, search_on, search_period, search_sent_before, search_sent_on, search_sent_period, search_sent_since, search_since

Other Size-search operations: search_larger_than, search_smaller_than

Other Flag-search operations: search_flag

Other Within-search operations: search_older_than, search_younger_than

Examples

# NOT RUN {
# }
# NOT RUN {
# configure IMAP
library(mRpostman)
imapconf <- configure_imap(url="imaps://your.imap.server.com",
                           username="your_username",
                           password=rstudioapi::askForPassword()
                          )
# search1
result1 <- imapconf %>%
    select_mailbox(mbox = "TAM") %>%
    custom_search(custom_request = AND(string(section_or_field = "TO",
                                              string = "allan"),
                                       before(date_char = "12-Apr-2009")
                                      ))
# searches for messages containing the string "allan" in the "TO" field
# and that were received before "12-Apr-2009".

# search2
result2 <- imapconf %>%
    select_mailbox(mbox = "INBOX") %>%
    custom_search(custom_request = OR(string(section_or_field = "TEXT",
                                             string = "Contract 2872827"),
                                      string(section_or_field = "Subject",
                                             string = "Buying operation")
                                             ))
# searches for messages containing the string "Contract 2872827" in the
# "TEXT" section or the string "Buying operation" in the "Subject" field
# of the HEADER.

# }
# NOT RUN {
# }