An IMAP Connection Class

Configure an IMAP connection using the ImapCon R6 class.

Note

ImapCon$new(): The configure_imap should be preferred instead of ImapCon$new().

ImapCon$search(): IMAP queries follow Polish notation, i.e. operators such as OR come before arguments, e.g. "OR argument1 argument2". Therefore, the relational-operator-helper-functions in this package should be used like the following examples: OR(before("17-Apr-2015"), string("FROM", "John")). Even though there is no "AND" operator in IMAP, this package adds a helper function AND to indicate multiple arguments that must be searched together, e.g. AND(since("01-Jul-2018"), smaller_than(16000)).

ImapCon$sent_before(): Search operations that use the origination/RFC-2822 Header date tend to be "slower" than those that use the internal date. Although the overhead is minimum, the difference is due to the fact that the internal date is kept on a database, while the origination date has to be retrieved from inside the message. Therefore, the server needs to access each message when executing this type of search. Despite this fact, both dates tend to be the same.

ImapCon$search_sent_since(): Search operations that use the origination/RFC-2822 Header date tend to be "slower" than those that use the internal date. Although the overhead is minimum, the difference is due to the fact that the internal date is kept on a database, while the origination date has to be retrieved from inside the message. Therefore, the server needs to access each message when executing this type of search. Despite this fact, both dates tend to be the same.

ImapCon$search_sent_on(): Search operations that use the origination/RFC-2822 Header date tend to be "slower" than those that use the internal date. Although the overhead is minimum, the difference is due to the fact that the internal date is kept on a database, while the origination date has to be retrieved from inside the message. Therefore, the server needs to access each message when executing this type of search. Despite this fact, both dates tend to be the same.

ImapCon$search_sent_period(): Search operations that use the origination/RFC-2822 Header date tend to be "slower" than those that use the internal date. Although the overhead is minimum, the difference is due to the fact that the internal date is kept on a database, while the origination date has to be retrieved from inside the message. Therefore, the server needs to access each message when executing this type of search. Despite this fact, both dates tend to be the same.

ImapCon$search_older_than(): To be able to use this functionality, the server must support the WITHIN capability. You can check it by running ImapCon$list_server_capabilities().

ImapCon$search_string(): Using where = "TEXT", may produce unexpected results since it will perform the search on raw data, i.e. the searched expression may be truncated by special formatting characters such as \r\n for example. It is recommended to perform this type of search using where = "BODY", instead of "TEXT" (Heinlein, P. and Hartleben, P. (2008)).

ImapCon$esearch_count(): This operation depends on the ESEARCH extension.

ImapCon$esearch_min_id(): This operation depends on the ESEARCH extension.

ImapCon$esearch_max_id(): This operation depends on the ESEARCH extension.

ImapCon$add_flags(): Unlike the search operations, the add/replace/delete flags operations demand system flag names to be preceded by two backslashes "\\".

ImapCon$add_flags(): add_flags, remove_flags, and replace_flags accept not only flags but also keywords (any word not beginning with two backslashes) which are custom flags defined by the user.

ImapCon$replace_flags(): Unlike the search operations, the add/replace/delete flags operations demand system flag names to be preceded by two backslashes "\\".

ImapCon$replace_flags(): add_flags, remove_flags, and replace_flags accept not only flags but also keywords (any word not beginning with two backslashes) which are custom flags defined by the user.

ImapCon$remove_flags(): Unlike the search operations, the add/replace/delete flags operations demand system flag names to be preceded by two backslashes "\\".

ImapCon$remove_flags(): add_flags, remove_flags, and replace_flags accept not only flags but also keywords (any word not beginning with two backslashes) which are custom flags defined by the user.

ImapCon$get_attachments(): This method is to be used after the body or the text part of one or more messages were fetched. This makes sense if the user is interested in keeping the message content (body or text) besides downloading the message attachments. Nonetheless, this is not the recommended approach if the user is only interested in downloading the files as the previous fetching operation will probably be costly. In this last case, the recommendation is to use ImapCon$fetch_attachments() as it will only fetch the attachment part.

ImapCon$get_attachments(): All attachments will be stored in a folder labeled with the message id inside the working directory > servername > foldername. This function currently handles only attachments encoded as base64 text. It tries to guess all file extensions while decoding the text, but it may not be possible to do so in some circumstances. If it happens, you can try to change the file extension directly by renaming the file.

ImapCon$get_attachments(): The "Content-Disposition" header specifies if the multipart electronic messages will be presented as a main document with a list of separate attachments ("Content-Disposition: attachment") or as a single document with the various parts displayed inline. The first requires positive action on the part of the recipient (downloading the file, for example) whereas inline components are displayed automatically when the message is viewed (Troost, R., Dorner, S., and K. Moore, Ed. (1997)). You can choose to download both, or only one type of attachment, using the argument content_disposition.

ImapCon$fetch_attachments(): All attachments will be stored in a folder labeled with the message id inside the working directory > servername > foldername. This function currently handles only attachments encoded as base64 text. It tries to guess all file extensions while decoding the text, but it may not be possible to do so in some circumstances. If it happens, you can try to change the file extension directly by renaming the file.

ImapCon$fetch_attachments(): The "Content-Disposition" header specifies if the multipart electronic messages will be presented as a main document with a list of separate attachments ("Content-Disposition: attachment") or as a single document with the various parts displayed inline. The first requires positive action on the part of the recipient (downloading the file, for example) whereas inline components are displayed automatically when the message is viewed (Troost, R., Dorner, S., and K. Moore, Ed. (1997)). You can choose to download both, or only one type of attachment, using the argument content_disposition.

References

ImapCon$search_string(): Heinlein, P. and Hartleben, P. (2008). The Book of IMAP: Building a Mail Server with Courier and Cyrus. No Starch Press. ISBN 978-1-59327-177-0.

ImapCon$get_attachments(): Troost, R., Dorner, S., and K. Moore (1997), Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field, RFC 2183, August 1997, https://www.rfc-editor.org/rfc/rfc2183.

ImapCon$fetch_attachments(): Troost, R., Dorner, S., and K. Moore (1997), Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field, RFC 2183, DOI 10.17487/RFC2183, August 1997, https://www.rfc-editor.org/rfc/rfc2183.

Methods

Public methods

ImapCon$new()
ImapCon$reset_url()
ImapCon$reset_username()
ImapCon$reset_use_ssl()
ImapCon$reset_verbose()
ImapCon$reset_buffersize()
ImapCon$reset_timeout_ms()
ImapCon$reset_password()
ImapCon$reset_xoauth2_bearer()
ImapCon$disconnect()
ImapCon$list_server_capabilities()
ImapCon$namespace()
ImapCon$id()
ImapCon$get_quota_root()
ImapCon$get_quota()
ImapCon$noop()
ImapCon$list_mail_folders()
ImapCon$list_subscribed_folders()
ImapCon$list_special_use_folders()
ImapCon$select_folder()
ImapCon$close_folder()
ImapCon$unselect_folder()
ImapCon$examine_folder()
ImapCon$status()
ImapCon$create_folder()
ImapCon$rename_folder()
ImapCon$delete_folder()
ImapCon$subscribe_folder()
ImapCon$unsubscribe_folder()
ImapCon$list_flags()
ImapCon$sort()
ImapCon$thread()
ImapCon$search()
ImapCon$search_larger_than()
ImapCon$search_smaller_than()
ImapCon$search_before()
ImapCon$search_since()
ImapCon$search_on()
ImapCon$search_period()
ImapCon$search_sent_before()
ImapCon$search_sent_since()
ImapCon$search_sent_on()
ImapCon$search_sent_period()
ImapCon$search_flag()
ImapCon$search_older_than()
ImapCon$search_younger_than()
ImapCon$search_string()
ImapCon$fetch_body()
ImapCon$fetch_header()
ImapCon$fetch_metadata()
ImapCon$fetch_text()
ImapCon$copy_msg()
ImapCon$move_msg()
ImapCon$append_msg()
ImapCon$esearch_count()
ImapCon$delete_msg()
ImapCon$expunge()
ImapCon$esearch_min_id()
ImapCon$esearch_max_id()
ImapCon$add_flags()
ImapCon$replace_flags()
ImapCon$remove_flags()
ImapCon$get_attachments()
ImapCon$fetch_attachments_list()
ImapCon$fetch_attachments()
ImapCon$clone()

Method `new()`

Configure and create a new IMAP connection.

Usage

ImapCon$new(
  url,
  username,
  password = NULL,
  xoauth2_bearer = NULL,
  use_ssl = TRUE,
  verbose = FALSE,
  buffersize = 16000,
  timeout_ms = 0,
  ...
)

Arguments

url: A character string containing the IMAP server address
username: A character string containing the username.
password: A character string containing the user's password.
xoauth2_bearer: A character string containing the oauth2 bearer token.
use_ssl: A logical indicating the use or not of Secure Sockets Layer encryption when connecting to the IMAP server. Default is TRUE.
verbose: If FALSE, mutes the flow of information between the server and the client. Default is FALSE.
buffersize: The size in bytes for the receive buffer. Default is 16000 bytes or 16kb, which means it will use the libcurl's default value. According to the libcurl's documentation, the maximum buffersize is 512kb (or 512000 bytes), but any number passed to buffersize is treated as a request, not an order.
timeout_ms: Time in milliseconds (ms) to wait for the execution or re-execution of a command. Default is 0, which means that no timeout limit is set.
...: Further curl parameters (see curl::curl_options) that can be used with the IMAP protocol. Only for advanced users.

Returns

A new `ImapCon` object.

Method `reset_url()`

Reset the previously informed url

Usage

ImapCon$reset_url(x)

Arguments

x: A character string containing a new url to be set.

Method `reset_username()`

Reset the previously informed username

Usage

ImapCon$reset_username(x)

Arguments

x: A character string containing a new username to be set.

Method `reset_use_ssl()`

Reset the previously informed use_ssl parameter

Usage

ImapCon$reset_use_ssl(x)

Arguments

x: A logical indicating the use or not of Secure Sockets Layer encryption when connecting to the IMAP server. Default is TRUE.

Method `reset_verbose()`

Reset the previously informed verbose parameter

Usage

ImapCon$reset_verbose(x)

Arguments

x: If FALSE, mutes the flow of information between the server and the client.

Method `reset_buffersize()`

Reset the previously informed buffersize parameter

Usage

ImapCon$reset_buffersize(x)

Arguments

x: The size in bytes for the receive buffer. Default is 16000 bytes or 16kb, which means it will use the libcurl's default value. According to the libcurl's documentation, the maximum buffersize is 512kb (or 512000 bytes), but any number passed to buffersize is treated as a request, not an order.

Method `reset_timeout_ms()`

Reset the previously informed buffersize parameter

Usage

ImapCon$reset_timeout_ms(x)

Arguments

x: Time in milliseconds (ms) to wait for the execution or re-execution of a command. Default is 0, which means that no timeout limit is set.

Method `reset_password()`

Reset the previously informed password

Usage

ImapCon$reset_password(x)

Arguments

x: A character string containing the user's password.

Method `reset_xoauth2_bearer()`

Reset the previously informed oauth2 bearer token

Usage

ImapCon$reset_xoauth2_bearer(x)

Arguments

x: A character string containing the oauth2 bearer token.

Method `disconnect()`

Disconnect and release the connection handle. After calling this method the connection object can no longer be used to issue commands; a new one must be created with configure_imap. Dropping the handle reference lets 'libcurl' close the underlying connection when the handle is garbage-collected.

Usage

ImapCon$disconnect()

Returns

TRUE, invisibly.

Examples

\dontrun{
con$disconnect()
}

Method `list_server_capabilities()`

List the server's IMAP capabilities.

Usage

ImapCon$list_server_capabilities(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A character vector containing the server's IMAP capabilities.

Examples

\dontrun{
cap <- con$list_server_capabilities()
cap
}

Method `namespace()`

Request the server's namespaces (IMAP NAMESPACE, RFC 2342): the personal, other users', and shared namespace prefixes and their hierarchy delimiters. Requires the server NAMESPACE capability.

Usage

ImapCon$namespace(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A named list with elements personal, other_users and shared, each a data.frame with prefix and delimiter columns, or NULL when the server returns NIL for that component.

Examples

\dontrun{
con$namespace()
}

Method `id()`

Exchange client/server identification (IMAP ID, RFC 2971). Optionally sends the client's id fields and returns the server's id. Requires the server ID capability.

Usage

ImapCon$id(fields = NULL, retries = 1)

Arguments

fields: A named character vector with the client id fields to send, e.g. c(name = "mRpostman", version = "1.2.1"). If NULL (default), sends ID NIL (asks for the server id without disclosing the client id).
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A named character vector with the server's id fields (empty when the server returns NIL).

Examples

\dontrun{
con$id()
con$id(fields = c(name = "mRpostman", version = "1.2.1"))
}

Method `get_quota_root()`

Get the quota root(s) and quota usage/limits of a mail folder (IMAP GETQUOTAROOT, RFC 2087). Requires the server QUOTA capability.

Usage

ImapCon$get_quota_root(name = NULL, retries = 1)

Arguments

name: A character string with the mail folder name. If no name is passed, the command uses the previously selected folder.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A data.frame with columns quota_root, resource, usage and limit (one row per resource; STORAGE is reported by the server in kibibytes).

Examples

\dontrun{
con$get_quota_root(name = "INBOX")
}

Method `get_quota()`

Get the quota usage/limits of a quota root (IMAP GETQUOTA, RFC 2087). Requires the server QUOTA capability.

Usage

ImapCon$get_quota(quota_root = "", retries = 1)

Arguments

quota_root: A character string with the quota root name. Default is "" (the default root). Use get_quota_root() to discover the root(s) of a folder.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A data.frame with columns quota_root, resource, usage and limit.

Examples

\dontrun{
con$get_quota(quota_root = "")
}

Method `noop()`

Issue a 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 and as a way to keep the connection handle alive between operations.

Usage

ImapCon$noop(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$noop()
}

Method `list_mail_folders()`

List mail folders in a mailbox.

Usage

ImapCon$list_mail_folders(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list containing the mail folder names and their inherent structure.

Examples

\dontrun{
folders <- con$list_mail_folders()
folders
}

Method `list_subscribed_folders()`

List the subscribed mail folders in a mailbox (IMAP LSUB). Unlike list_mail_folders() (which issues LIST and returns every folder), this returns only the folders the user is subscribed to.

Usage

ImapCon$list_subscribed_folders(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list containing the subscribed mail folder names and their inherent structure.

Examples

\dontrun{
subscribed <- con$list_subscribed_folders()
subscribed
}

Method `list_special_use_folders()`

List the special-use mail folders (IMAP LIST (SPECIAL-USE), RFC 6154), i.e. the folders the server has tagged with a role such as \Sent, \Drafts, \Junk, \Trash, \Archive, \All, or \Flagged. Requires the server SPECIAL-USE capability.

Usage

ImapCon$list_special_use_folders(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A data.frame with columns folder and special_use (one row per folder/attribute).

Examples

\dontrun{
con$list_special_use_folders()
}

Method `select_folder()`

Select a mail folder.

Usage

ImapCon$select_folder(name, mute = FALSE, retries = 1)

Arguments

name: A string containing the name of an existing mail folder on the user's mailbox.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list containing the mail folder names and their inherent structure.

Examples

\dontrun{
con$select_folder(name = "INBOX")
}

Method `close_folder()`

Close the currently selected mail folder (IMAP CLOSE), permanently removing the messages flagged \Deleted. After this, no folder is selected.

Usage

ImapCon$close_folder(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$select_folder("INBOX")
con$close_folder()
}

Method `unselect_folder()`

Close the currently selected mail folder without expunging (IMAP UNSELECT, RFC 3691). Requires the server UNSELECT capability. After this, no folder is selected.

Usage

ImapCon$unselect_folder(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$select_folder("INBOX")
con$unselect_folder()
}

Method `examine_folder()`

Examine the number of messages in a mail folder.

Usage

ImapCon$examine_folder(name = NULL, retries = 1)

Arguments

name: A character string containing the name of an existing mail folder on the user's mailbox. If no name is passed, the command will be executed using the previously selected mail folder name.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A vector (with names "EXISTS" and "RECENT") containing the number of messages in each category.

Examples

\dontrun{
con$select_folder(name = "INBOX")
con$examine_folder()

# or directly:
con$examine_folder("Sent")
}

Method `status()`

Request the status of a mail folder without selecting it. Unlike examine_folder(), this does not change the currently selected folder.

Usage

ImapCon$status(
  name = NULL,
  items = c("MESSAGES", "RECENT", "UIDNEXT", "UIDVALIDITY", "UNSEEN"),
  retries = 1
)

Arguments

name: A character string containing the name of an existing mail folder on the user's mailbox. If no name is passed, the command will be executed using the previously selected mail folder name.
items: A character vector with the status data items to request. Must be a subset of "MESSAGES", "RECENT", "UIDNEXT", "UIDVALIDITY", and "UNSEEN". Default is all of them.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A named numeric vector with the requested status counts.

Examples

\dontrun{
con$status(name = "INBOX")

# or, for the selected folder and specific items only:
con$select_folder("INBOX")
con$status(items = c("MESSAGES", "UNSEEN"))
}

Method `create_folder()`

Create a new mail folder.

Usage

ImapCon$create_folder(name, mute = FALSE, retries = 1)

Arguments

name: A string containing the name of the new mail folder to be created.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$create_folder(name = "New Folder Name")
}

Method `rename_folder()`

Rename a mail folder.

Usage

ImapCon$rename_folder(
  name = NULL,
  new_name,
  reselect = TRUE,
  mute = FALSE,
  retries = 1
)

Arguments

name: A string containing the name of the mail folder to be renamed. If no name is passed, the command will be executed using the previously selected mail folder name.
new_name: A string containing the new name to be assigned.
reselect: A logical. If TRUE, calls select_folder(name = to_folder) under the hood before returning the output. Default is TRUE.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$select_folder(name = "Folder A")
con$rename_folder(new_name = "Folder B")
# or directly:
con$rename_folder(name = "Folder A", new_name = "Folder B")
}

Method `delete_folder()`

Delete a mail folder.

Usage

ImapCon$delete_folder(name, mute = FALSE, retries = 1)

Arguments

name: A string containing the name of the mail folder to be deleted.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$delete_folder(name = "Folder to remove")
}

Method `subscribe_folder()`

Subscribe to a mail folder (IMAP SUBSCRIBE), adding it to the set returned by list_subscribed_folders().

Usage

ImapCon$subscribe_folder(name, mute = FALSE, retries = 1)

Arguments

name: A string containing the name of the mail folder to subscribe to.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$subscribe_folder(name = "INBOX")
}

Method `unsubscribe_folder()`

Unsubscribe from a mail folder (IMAP UNSUBSCRIBE), removing it from the set returned by list_subscribed_folders().

Usage

ImapCon$unsubscribe_folder(name, mute = FALSE, retries = 1)

Arguments

name: A string containing the name of the mail folder to unsubscribe from.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$unsubscribe_folder(name = "INBOX")
}

Method `list_flags()`

List flags in a selected mail folder

Usage

ImapCon$list_flags(retries = 1)

Arguments

retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
con$select_folder(name = "INBOX")
con$list_flags()
}

Method `sort()`

Sort messages on the server (IMAP SORT, RFC 5256). Returns the message ids ordered by the server according to the sort keys. Requires the server to advertise the SORT capability (check with list_server_capabilities()).

Usage

ImapCon$sort(
  by = "DATE",
  reverse = FALSE,
  criteria = "ALL",
  use_uid = FALSE,
  char_set = "UTF-8",
  retries = 1
)

Arguments

by: A character vector of sort keys, a subset of "ARRIVAL", "CC", "DATE", "FROM", "SIZE", "SUBJECT", and "TO". Default is "DATE".
reverse: A logical. If TRUE, each sort key is prefixed with REVERSE (descending order). Default is FALSE.
criteria: A character string with the search criteria that restricts the set to be sorted. Default is "ALL".
use_uid: A logical. If TRUE, issues UID SORT and returns UIDs instead of sequence numbers. Default is FALSE.
char_set: A character string with the charset of the search criteria. Default is "UTF-8".
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

An integer vector of message ids in the server-provided (sorted) order.

Examples

\dontrun{
con$select_folder("INBOX")
con$sort(by = "DATE", reverse = TRUE)
}

Method `thread()`

Thread messages on the server (IMAP THREAD, RFC 5256). Returns the messages grouped into threads. Requires the server to advertise a THREAD= capability (check with list_server_capabilities()).

Usage

ImapCon$thread(
  algorithm = "REFERENCES",
  criteria = "ALL",
  use_uid = FALSE,
  char_set = "UTF-8",
  retries = 1
)

Arguments

algorithm: A character string with the threading algorithm, either "REFERENCES" or "ORDEREDSUBJECT". Default is "REFERENCES".
criteria: A character string with the search criteria that restricts the set to be threaded. Default is "ALL".
use_uid: A logical. If TRUE, issues UID THREAD and returns UIDs instead of sequence numbers. Default is FALSE.
char_set: A character string with the charset of the search criteria. Default is "UTF-8".
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list of integer vectors, one per top-level thread.

Examples

\dontrun{
con$select_folder("INBOX")
con$thread(algorithm = "REFERENCES")
}

Method `search()`

Execute a custom search

Usage

ImapCon$search(
  request,
  negate = FALSE,
  use_uid = FALSE,
  esearch = FALSE,
  retries = 1
)

Arguments

request: A string directly specifying what to search or constructed by a combination of relational-operator-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 older_than.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERIA". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list containing the flags (character vector), the permanent flags (character vector), and an indication if custom flags are allowed by the server (logical vector).

Examples

\dontrun{
con$select_folder(name = "INBOX")
# ex1
con$search(OR(before(date_char = "17-Apr-2015"),
              string(expr = "John", where = "FROM")))

# ex2
con$search(AND(smaller_than(size = "512000"),
               string(expr = "John", where = "FROM"),
               string(expr = "@ksu.edu", where = "CC")))
}

Method `search_larger_than()`

Search by size (LARGER)

Usage

ImapCon$search_larger_than(
  size,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

size: An integer specifying the size in bytes to be used as the search criterion.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
# search for messages with size larger than 512Kb
con$search_larger_than(size = 512000)
}

Method `search_smaller_than()`

Search by size (SMALLER)

Usage

ImapCon$search_smaller_than(
  size,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

size: An integer specifying the size in bytes to be used as the search criterion.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for messages with size smaller than 512Kb
con$search_smaller_than(size = 512000)
}

Method `search_before()`

Search by internal date (BEFORE)

Usage

ImapCon$search_before(
  date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for messages with date before "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_before(date = "02-Jan-2020", use_uid = TRUE)
}

Method `search_since()`

Search by internal date (SINCE)

Usage

ImapCon$search_since(
  date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for messages with date since "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_since(date = "02-Jan-2020", use_uid = TRUE)
}

Method `search_on()`

Search by internal date (ON)

Usage

ImapCon$search_on(
  date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for messages received on date "02-Jan-2020", presenting the
#... results as unique identifiers (UID)
con$search_on(date = "02-Jan-2020", use_uid = TRUE)
}

Method `search_period()`

Search by internal date (Period)

Usage

ImapCon$search_period(
  since_date_char,
  before_date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

since_date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
before_date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for all messages in the mail folder, EXCEPT (negate = TRUE) by
#... those received between the dates "02-Jan-2020" and "22-Mar-2020"
con$search_period(since_date_char = "02-Jan-2020",
                  before_date_char = "22-Mar-2020",
                  negate = TRUE)
}

Method `search_sent_before()`

Search by origination date (RFC 2822 Header - SENT BEFORE)

Usage

ImapCon$search_sent_before(
  date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
# search for messages with date before "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_sent_before(date = "02-Jan-2020", use_uid = TRUE)
}

Method `search_sent_since()`

Search by origination date (RFC 2822 Header - SENT SINCE)

Usage

ImapCon$search_sent_since(
  date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
# search for messages with date before "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_sent_since(date = "02-Jan-2020", use_uid = TRUE)
}

Method `search_sent_on()`

Search by origination date (RFC 2822 Header - SENT ON)

Usage

ImapCon$search_sent_on(
  date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for messages received on date "02-Jan-2020", presenting the
#... results as unique identifiers (UID)
con$search_sent_on(date = "02-Jan-2020", use_uid = TRUE)
}

Method `search_sent_period()`

Search by origination date (RFC 2822 Header - SENT Period)

Usage

ImapCon$search_sent_period(
  since_date_char,
  before_date_char,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

since_date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
before_date_char: A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opt not to use Date or POSIX* like objects, since IMAP servers use this uncommon date format.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for all messages in the mail folder, EXCEPT (negate = TRUE) by
#... those received between the dates "02-Jan-2020" and "22-Mar-2020"
con$search_sent_period(since_date_char = "02-Jan-2020",
                  before_date_char = "22-Mar-2020",
                  negate = TRUE)
}

Method `search_flag()`

Search by flag(s)

Usage

ImapCon$search_flag(
  name,
  negate = FALSE,
  use_uid = FALSE,
  esearch = FALSE,
  retries = 1
)

Arguments

name: A string containing one or more flags to search for. Use ImapCon$list_flags() to list the flags in a selected mail folder.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for all messages in the mail folder that are marked as "SEEN" AND
#.. "ANSWERED"
con$search_flag(name = c("SEEN", "ANSWERED"))
}

Method `search_older_than()`

Search WITHIN a specific time (OLDER)

Usage

ImapCon$search_older_than(
  seconds,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

seconds: An integer specifying the number of seconds to be used as the search criterion.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for all messages received in the last hour (not older than 3600 seconds)
con$search_older_than(seconds = 3600, negate = TRUE)
}

Method `search_younger_than()`

Search WITHIN a specific time (YOUNGER)

Usage

ImapCon$search_younger_than(
  seconds,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

seconds: An integer specifying the number of seconds to be used as the search criterion.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for all messages received in the last hour (younger than 3600 seconds)
con$search_younger_than(seconds = 3600)
}

Method `search_string()`

Search by string or expression

Usage

ImapCon$search_string(
  expr,
  where,
  negate = FALSE,
  use_uid = FALSE,
  flag = NULL,
  esearch = FALSE,
  retries = 1
)

Arguments

expr: A character string specifying the word or expression to search for in messages.
where: A mandatory character string specifying in which message's Section or Header Field to search for the provided string.
negate: If TRUE, negates the search and seeks for "NOT SEARCH CRITERION". Default is FALSE.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
flag: An optional argument that sets one or more flags as an additional filter to the search. Use ImapCon$list_flags() to list the flags in a selected mail folder. Default is NULL.
esearch: A logical. Default is FALSE. If the IMAP server has ESEARCH capability, it can be used to optimize search results. It will condense the results: instead of writing down the whole sequences of messages' ids, such as {1 2 3 4 5}, it will be presented as {1:5}, which decreases transmission costs. This argument can be used along with buffersize to avoid results stripping. Check if your IMAP server supports ESEARCH with ImapCon$list_server_capabilities().
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# search for messages with "@k-state.edu" in the FROM field
con$search_string(expr = "@k-state.edu", where = "FROM")
}

Method `fetch_body()`

Fetch message body (message's full content)

Usage

ImapCon$fetch_body(
  msg_id,
  use_uid = FALSE,
  mime_level = NULL,
  peek = TRUE,
  partial = NULL,
  write_to_disk = FALSE,
  keep_in_mem = TRUE,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
mime_level: An integer specifying MIME multipart to fetch from the message's body. Default is NULL, which retrieves the full body content.
peek: If TRUE, it does not mark messages as "read" after fetching. Default is TRUE.
partial: NULL or a character string with format "startchar.endchar" indicating the size (in characters) of a message slice to fetch. Default is NULL, which will fetch the full specified content.
write_to_disk: If TRUE, writes the fetched content of each message to a text file in a local folder inside the working directory, also returning the results with invisible(). Default is FALSE.
keep_in_mem: If TRUE, keeps a copy of each fetch result while the operation is being performed with write_to_disk = TRUE. Default is FALSE, and it can only be set TRUE when write_to_disk = TRUE.
mute: A logical. It provides a confirmation message if the command is successfully executed. It is only effective when write_to_disk = TRUE and keep_in_mem = FALSE. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list with the fetch contents or a logical if write_to_disk = TRUE and keep_in_mem = FALSE.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and fetch the results (saving to disk) using the pipe
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_body(write_to_disk = TRUE, keep_in_mem = FALSE)

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")

con$fetch_body(msg = res, write_to_disk = TRUE, keep_in_mem = FALSE)

}

Method `fetch_header()`

Fetch message header

Usage

ImapCon$fetch_header(
  msg_id,
  use_uid = FALSE,
  fields = NULL,
  negate_fields = FALSE,
  peek = TRUE,
  partial = NULL,
  write_to_disk = FALSE,
  keep_in_mem = TRUE,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
fields: An optional character vector specifying which field(s) will be fetched from the message's header. If none is specified, it will fetch the full header.
negate_fields: If TRUE, negates the operation and seeks for "NOT in the field". Default is FALSE.
peek: If TRUE, it does not mark messages as "read" after fetching. Default is TRUE.
partial: NULL or a character string with format "startchar.endchar" indicating the size (in characters) of a message slice to fetch. Default is NULL, which will fetch the full specified content.
write_to_disk: If TRUE, writes the fetched content of each message to a text file in a local folder inside the working directory, also returning the results with invisible(). Default is FALSE.
keep_in_mem: If TRUE, keeps a copy of each fetch result while the operation is being performed with write_to_disk = TRUE. Default is FALSE, and it can only be set TRUE when write_to_disk = TRUE.
mute: A logical. It provides a confirmation message if the command is successfully executed. It is only effective when write_to_disk = TRUE and keep_in_mem = FALSE. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list with the fetch contents or a logical if write_to_disk = TRUE and keep_in_mem = FALSE.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and fetch the results (also saving to disk) using the pipe
out <- con$search_string(expr = "@k-state.edu", where = "CC") %>%
  con$fetch_header()

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "CC")
out <- con$fetch_header()

}

Method `fetch_metadata()`

Fetch message metadata

Usage

ImapCon$fetch_metadata(
  msg_id,
  use_uid = FALSE,
  attribute = NULL,
  write_to_disk = FALSE,
  keep_in_mem = TRUE,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
attribute: An optional character vector specifying one or more attributes of the metadata of a message to fetch. See metadata_options.
write_to_disk: If TRUE, writes the fetched content of each message to a text file in a local folder inside the working directory, also returning the results with invisible(). Default is FALSE.
keep_in_mem: If TRUE, keeps a copy of each fetch result while the operation is being performed with write_to_disk = TRUE. Default is FALSE, and it can only be set TRUE when write_to_disk = TRUE.
mute: A logical. It provides a confirmation message if the command is successfully executed. It is only effective when write_to_disk = TRUE and keep_in_mem = FALSE. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.
peek: If TRUE, it does not mark messages as "read" after fetching. Default is TRUE.
partial: NULL or a character string with format "startchar.endchar" indicating the size (in characters) of a message slice to fetch. Default is NULL, which will fetch the full specified content.

Returns

A list with the fetch contents or a logical if write_to_disk = TRUE and keep_in_mem = FALSE.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and fetch the results using the pipe
out <- con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_metadata()

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
out <- con$fetch_metadata(msg = res)

}

Method `fetch_text()`

Fetch message text

Usage

ImapCon$fetch_text(
  msg_id,
  use_uid = FALSE,
  peek = TRUE,
  partial = NULL,
  write_to_disk = FALSE,
  keep_in_mem = TRUE,
  mute = FALSE,
  base64_decode = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
peek: If TRUE, it does not mark messages as "read" after fetching. Default is TRUE.
partial: NULL or a character string with format "startchar.endchar" indicating the size (in characters) of a message slice to fetch. Default is NULL, which will fetch the full specified content.
write_to_disk: If TRUE, writes the fetched content of each message to a text file in a local folder inside the working directory, also returning the results with invisible(). Default is FALSE.
keep_in_mem: If TRUE, keeps a copy of each fetch result while the operation is being performed with write_to_disk = TRUE. Default is FALSE, and it can only be set TRUE when write_to_disk = TRUE.
mute: A logical. It provides a confirmation message if the command is successfully executed. It is only effective when write_to_disk = TRUE and keep_in_mem = FALSE. Default is FALSE.
base64_decode: If TRUE, tries to guess and decode the fetched text from base64 format to character. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list with the fetch contents or a logical if write_to_disk = TRUE and keep_in_mem = FALSE.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and partially fetch the results using the pipe
# first 200 characters, writing to disk, silence results in the console
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_text(partial = "0.200",
                 write_to_disk = TRUE,
                 keep_in_mem = FALSE)

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$fetch_text(msg = res,
               partial = "0.200",
               write_to_disk = TRUE,
               keep_in_mem = FALSE)

}

Method `copy_msg()`

Copy message(s) between the selected folder and another one

Usage

ImapCon$copy_msg(
  msg_id,
  use_uid = FALSE,
  to_folder,
  reselect = TRUE,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
to_folder: A character string specifying the folder to which the messages will be copied.
reselect: A logical. If TRUE, calls ImapCon$select_folder(name = to_folder) under the hood before returning the output. Default is TRUE.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

An invisible numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and copy the results to another folder
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$copy(to_folder = "Sent")

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$copy(msg = res, to_folder = "Sent")

}

Method `move_msg()`

Move message(s) between the selected folder and another one

Usage

ImapCon$move_msg(
  msg_id,
  use_uid = FALSE,
  to_folder,
  reselect = TRUE,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
to_folder: A character string specifying the folder to which the messages will be copied.
reselect: A logical. If TRUE, calls ImapCon$select_folder(name = to_folder) under the hood before returning the output. Default is TRUE.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

An invisible numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and copy the results to another folder
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$move(to_folder = "Sent")

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$move(msg = res, to_folder = "Sent")

}

Method `append_msg()`

Append a full RFC 822 message to a mail folder (IMAP APPEND). Useful to save a message to folders such as Drafts or Sent. Unlike the other operations this is performed by an upload to the folder; the message is stored with the server's default flags.

Usage

ImapCon$append_msg(message, folder = NULL, mute = FALSE, retries = 1)

Arguments

message: A character string or raw vector with the full RFC 822 message (headers and body).
folder: A character string with the destination folder. If no folder is passed, the previously selected folder is used.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE in case the operation is successful.

Examples

\dontrun{
msg <- paste("From: me@example.com", "To: you@example.com",
             "Subject: Hi", "", "Message body.", sep = "\r\n")
con$append_msg(message = msg, folder = "Drafts")
}

Method `esearch_count()`

Count the number of messages with a specific flag(s) in a folder (depends on ESEARCH capability)

Usage

ImapCon$esearch_count(flag, use_uid = FALSE, retries = 1)

Arguments

flag: A mandatory parameter that specifies one or more flags as a filter to the counting operation. Use ImapCon$list_flags() to list the flags in a selected mail folder.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector of length 1 containing the number of messages in the folder that meet the specified criteria.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# count the number of messages marked as "Flagged" and "Answered"
con$esearch_count(flag = c("Flagged", "Answered"))
}

Method `delete_msg()`

Delete message(s) in the selected mail folder

Usage

ImapCon$delete_msg(msg_id, use_uid = FALSE, mute = FALSE, retries = 1)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

An invisible numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# delete
con$delete_msg(flag = c("Flagged", "Answered"))
}

Method `expunge()`

Permanently removes all or specific messages marked as deleted from the selected folder

Usage

ImapCon$expunge(msg_uid = NULL, mute = FALSE, retries = 1)

Arguments

msg_uid: A numeric vector containing one or more messages UIDs. Only UIDs are allowed in this operation (note the "u" in msg_uid).
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

TRUE if the operation is successful.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# count the number of messages marked as "Flagged" and "Answered"
con$esearch_count(flag = c("Flagged", "Answered"))
}

Method `esearch_min_id()`

Search the minimum message id in the selected mail folder (depends on ESEARCH capability)

Usage

ImapCon$esearch_min_id(flag, use_uid = FALSE, retries = 1)

Arguments

flag: A mandatory parameter that specifies one or more flags as a filter to the searching operation. Use ImapCon$list_flags() to list the flags in a selected mail folder.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector of length 1 containing the minimum message id in the folder.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# Search the minimum id of messages marked as "Answered"
con$esearch_min_id(flag = "Answered")
}

Method `esearch_max_id()`

Search the maximum message id in the selected mail folder (depends on ESEARCH capability)

Usage

ImapCon$esearch_max_id(flag, use_uid = FALSE, retries = 1)

Arguments

flag: A mandatory parameter that specifies one or more flags as a filter to the searching operation. Use ImapCon$list_flags() to list the flags in a selected mail folder.
use_uid: Default is FALSE. In this case, results will be presented as message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier, and results are presented as such. UIDs are always the same during the life cycle of a message in a mail folder.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A numeric vector of length 1 containing the maximum message id in the folder.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# Search the minimum id of messages marked as "Seen"
con$esearch_max_id(flag = "Seen")
}

Method `add_flags()`

Add flags to one or more messages

Usage

ImapCon$add_flags(
  msg_id,
  use_uid = FALSE,
  flags_to_set,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
flags_to_set: A character vector containing one or more flag names to add to the specified message ids. If the flag to be set is a system flag, such as \SEEN, \ANSWERED, the name should be preceded by two backslashes \.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

An invisible numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# Add the "\Seen" permanent flag to the messages received in the last hour
con$search_younger_than(seconds = 3600) %>% # depends on the WITHIN extension
  con$add_flags(flags_to_set = "\\Seen")
}

Method `replace_flags()`

Replace the current flags of one or more messages

Usage

ImapCon$replace_flags(
  msg_id,
  use_uid = FALSE,
  flags_to_set,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
flags_to_set: A character vector containing one or more flag names that will replace the current ones. If the flag to be set is a system flag, such as \SEEN, \ANSWERED, the name should be preceded by two backslashes \.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

An invisible numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# Replace the current flags of the messages in the search results for the
#.. flags "\UNSEEN" and "\Flagged"
con$search_since(date_char = "20-Aug-2020") %>%
  con$replace_flags(flags_to_set = c("\\UNSEEN", "\\Flagged"))
}

Method `remove_flags()`

Remove flag(s) of one or more messages

Usage

ImapCon$remove_flags(
  msg_id,
  use_uid = FALSE,
  flags_to_unset,
  mute = FALSE,
  retries = 1
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
flags_to_unset: A character vector containing one or more flag names that will be unset (removed). If the flag to be removed is a system flag, such as \SEEN, \ANSWERED, the name should be preceded by two backslashes \.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

An invisible numeric vector containing the message ids.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# Remove the "\SEEN" flag from the messages in the search result
con$search_since(date_char = "20-Aug-2020") %>%
  con$remove_flags(flags_to_unset = "\\UNSEEN")
}

Method `get_attachments()`

Extract attached file(s) from fetched message(s)

Usage

ImapCon$get_attachments(
  msg_list,
  content_disposition = "both",
  override = FALSE,
  mute = FALSE,
  as_is = FALSE,
  local_dir = "."
)

Arguments

msg_list: A list with the body or text content of the messages fetched with ImapCon$fetch_body() or ImapCon$fetch_text().
content_disposition: A string indicating which type of "Content-Disposition" attachments should be retrieved. Default is "both", which retrieves regular attachments ("Content-Disposition: attachment") and inline attachments ("Content-Disposition: inline").
override: A logical. Provides a confirmation message if the command is successfully executed. Default is FALSE.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
as_is: If TRUE then write out attachments without base64 decoding. Default is FALSE.
local_dir: A character string with the base directory where the attachments will be saved. A subfolder tree <local_dir>/<username>/<mail folder>/<msg id> is created inside it. Default is "." (the current working directory).

Returns

TRUE if the operation is successful. The files are saved locally.

Examples

\dontrun{
# example 1
con$select_folder(name = "INBOX")
con$search_string(expr = "@gmail", where = "CC") %>%
  con$fetch_text(write_to_disk = TRUE) %>% # saving the message's content as txt files
  con$get_attachments()

# example 2
res <- con$search_string(expr = "@gmail", where = "CC")
out <- con$fetch_body(msg = res)
con$get_attachments(msg_list = out)
}

Method `fetch_attachments_list()`

Fetch attachments' list

Usage

ImapCon$fetch_attachments_list(msg_id, use_uid = FALSE, retries = 1)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
retries: Number of attempts to connect and execute the command. Default is 1.

Returns

A list with the fetch contents.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and fetch the attachments' list of the messages
out <- con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_attachments_list()
out

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
out <- con$fetch_attachments_list(msg = res)
out

}

Method `fetch_attachments()`

Fetch message attachments

Usage

ImapCon$fetch_attachments(
  msg_id,
  use_uid = FALSE,
  content_disposition = "both",
  override = FALSE,
  mute = FALSE,
  retries = 1,
  as_is = FALSE,
  local_dir = "."
)

Arguments

msg_id: A numeric vector containing one or more message ids.
use_uid: Default is FALSE. In this case, the operation will be performed using message sequence numbers. A message sequence number is a message's relative position to the oldest message in a mail folder. It may change after deleting or moving messages. If a message is deleted, sequence numbers are reordered to fill the gap. If TRUE, the command will be performed using the "UID" or unique identifier. UIDs are always the same during the life cycle of a message in a mail folder.
content_disposition: A string indicating which type of "Content-Disposition" attachments should be retrieved. The options are both, attachment, and inline. Default is "both", which retrieves regular attachments ("Content-Disposition: attachment") and inline attachments ("Content-Disposition: inline").
override: A logical. Provides a confirmation message if the command is successfully executed. Default is FALSE.
mute: A logical. If TRUE, mutes the confirmation message when the command is successfully executed. Default is FALSE.
retries: Number of attempts to connect and execute the command. Default is 1.
as_is: If TRUE then write out attachments without base64 decoding. Default is FALSE.
local_dir: A character string with the base directory where the attachments will be saved. A subfolder tree <local_dir>/<username>/<mail folder>/<msg id> is created inside it. Default is "." (the current working directory).

Returns

A list with the fetch contents.

Examples

\dontrun{
con$select_folder(name = "INBOX")
# do a search and fetch the attachments' list of the messages
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_attachments() # the attachments will be downloaded to disk


# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$fetch_attachments(msg = res)

}

Method `clone()`

The objects of this class are cloneable with this method.

Usage

ImapCon$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

if (FALSE) {
# w/ Plain authentication
con <- configure_imap(
  url="imaps://outlook.office365.com",
  username="user@agency.gov.br",
  password=rstudioapi::askForPassword(),
  verbose = TRUE)

# OR
con <- ImapCon$new(
  url="imaps://outlook.office365.com",
  username="user@agency.gov.br",
  password=rstudioapi::askForPassword(),
  verbose = TRUE)

# w/ OAuth2.0 authentication
con <- configure_imap(
  url="imaps://outlook.office365.com",
  username="user@agency.gov.br",
  verbose = TRUE,
  xoauth2_bearer = "XX.Ya9...")

# OR
con <- ImapCon$new(
  url="imaps://outlook.office365.com",
  username="user@agency.gov.br",
  verbose = TRUE,
  xoauth2_bearer = "XX.Ya9...")

}



## ------------------------------------------------
## Method `ImapCon$disconnect`
## ------------------------------------------------

if (FALSE) {
con$disconnect()
}

## ------------------------------------------------
## Method `ImapCon$list_server_capabilities`
## ------------------------------------------------

if (FALSE) {
cap <- con$list_server_capabilities()
cap
}

## ------------------------------------------------
## Method `ImapCon$namespace`
## ------------------------------------------------

if (FALSE) {
con$namespace()
}

## ------------------------------------------------
## Method `ImapCon$id`
## ------------------------------------------------

if (FALSE) {
con$id()
con$id(fields = c(name = "mRpostman", version = "1.2.1"))
}

## ------------------------------------------------
## Method `ImapCon$get_quota_root`
## ------------------------------------------------

if (FALSE) {
con$get_quota_root(name = "INBOX")
}

## ------------------------------------------------
## Method `ImapCon$get_quota`
## ------------------------------------------------

if (FALSE) {
con$get_quota(quota_root = "")
}

## ------------------------------------------------
## Method `ImapCon$noop`
## ------------------------------------------------

if (FALSE) {
con$noop()
}

## ------------------------------------------------
## Method `ImapCon$list_mail_folders`
## ------------------------------------------------

if (FALSE) {
folders <- con$list_mail_folders()
folders
}

## ------------------------------------------------
## Method `ImapCon$list_subscribed_folders`
## ------------------------------------------------

if (FALSE) {
subscribed <- con$list_subscribed_folders()
subscribed
}

## ------------------------------------------------
## Method `ImapCon$list_special_use_folders`
## ------------------------------------------------

if (FALSE) {
con$list_special_use_folders()
}

## ------------------------------------------------
## Method `ImapCon$select_folder`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
}

## ------------------------------------------------
## Method `ImapCon$close_folder`
## ------------------------------------------------

if (FALSE) {
con$select_folder("INBOX")
con$close_folder()
}

## ------------------------------------------------
## Method `ImapCon$unselect_folder`
## ------------------------------------------------

if (FALSE) {
con$select_folder("INBOX")
con$unselect_folder()
}

## ------------------------------------------------
## Method `ImapCon$examine_folder`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
con$examine_folder()

# or directly:
con$examine_folder("Sent")
}

## ------------------------------------------------
## Method `ImapCon$status`
## ------------------------------------------------

if (FALSE) {
con$status(name = "INBOX")

# or, for the selected folder and specific items only:
con$select_folder("INBOX")
con$status(items = c("MESSAGES", "UNSEEN"))
}

## ------------------------------------------------
## Method `ImapCon$create_folder`
## ------------------------------------------------

if (FALSE) {
con$create_folder(name = "New Folder Name")
}

## ------------------------------------------------
## Method `ImapCon$rename_folder`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "Folder A")
con$rename_folder(new_name = "Folder B")
# or directly:
con$rename_folder(name = "Folder A", new_name = "Folder B")
}

## ------------------------------------------------
## Method `ImapCon$delete_folder`
## ------------------------------------------------

if (FALSE) {
con$delete_folder(name = "Folder to remove")
}

## ------------------------------------------------
## Method `ImapCon$subscribe_folder`
## ------------------------------------------------

if (FALSE) {
con$subscribe_folder(name = "INBOX")
}

## ------------------------------------------------
## Method `ImapCon$unsubscribe_folder`
## ------------------------------------------------

if (FALSE) {
con$unsubscribe_folder(name = "INBOX")
}

## ------------------------------------------------
## Method `ImapCon$list_flags`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
con$list_flags()
}

## ------------------------------------------------
## Method `ImapCon$sort`
## ------------------------------------------------

if (FALSE) {
con$select_folder("INBOX")
con$sort(by = "DATE", reverse = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$thread`
## ------------------------------------------------

if (FALSE) {
con$select_folder("INBOX")
con$thread(algorithm = "REFERENCES")
}

## ------------------------------------------------
## Method `ImapCon$search`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# ex1
con$search(OR(before(date_char = "17-Apr-2015"),
              string(expr = "John", where = "FROM")))

# ex2
con$search(AND(smaller_than(size = "512000"),
               string(expr = "John", where = "FROM"),
               string(expr = "@ksu.edu", where = "CC")))
}

## ------------------------------------------------
## Method `ImapCon$search_larger_than`
## ------------------------------------------------

if (FALSE) {
# search for messages with size larger than 512Kb
con$search_larger_than(size = 512000)
}

## ------------------------------------------------
## Method `ImapCon$search_smaller_than`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for messages with size smaller than 512Kb
con$search_smaller_than(size = 512000)
}

## ------------------------------------------------
## Method `ImapCon$search_before`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for messages with date before "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_before(date = "02-Jan-2020", use_uid = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_since`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for messages with date since "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_since(date = "02-Jan-2020", use_uid = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_on`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for messages received on date "02-Jan-2020", presenting the
#... results as unique identifiers (UID)
con$search_on(date = "02-Jan-2020", use_uid = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_period`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for all messages in the mail folder, EXCEPT (negate = TRUE) by
#... those received between the dates "02-Jan-2020" and "22-Mar-2020"
con$search_period(since_date_char = "02-Jan-2020",
                  before_date_char = "22-Mar-2020",
                  negate = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_sent_before`
## ------------------------------------------------

if (FALSE) {
# search for messages with date before "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_sent_before(date = "02-Jan-2020", use_uid = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_sent_since`
## ------------------------------------------------

if (FALSE) {
# search for messages with date before "02-Jan-2020", presenting the
# .. results as unique identifiers (UID)
con$search_sent_since(date = "02-Jan-2020", use_uid = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_sent_on`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for messages received on date "02-Jan-2020", presenting the
#... results as unique identifiers (UID)
con$search_sent_on(date = "02-Jan-2020", use_uid = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_sent_period`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for all messages in the mail folder, EXCEPT (negate = TRUE) by
#... those received between the dates "02-Jan-2020" and "22-Mar-2020"
con$search_sent_period(since_date_char = "02-Jan-2020",
                  before_date_char = "22-Mar-2020",
                  negate = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_flag`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for all messages in the mail folder that are marked as "SEEN" AND
#.. "ANSWERED"
con$search_flag(name = c("SEEN", "ANSWERED"))
}

## ------------------------------------------------
## Method `ImapCon$search_older_than`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for all messages received in the last hour (not older than 3600 seconds)
con$search_older_than(seconds = 3600, negate = TRUE)
}

## ------------------------------------------------
## Method `ImapCon$search_younger_than`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for all messages received in the last hour (younger than 3600 seconds)
con$search_younger_than(seconds = 3600)
}

## ------------------------------------------------
## Method `ImapCon$search_string`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# search for messages with "@k-state.edu" in the FROM field
con$search_string(expr = "@k-state.edu", where = "FROM")
}

## ------------------------------------------------
## Method `ImapCon$fetch_body`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and fetch the results (saving to disk) using the pipe
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_body(write_to_disk = TRUE, keep_in_mem = FALSE)

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")

con$fetch_body(msg = res, write_to_disk = TRUE, keep_in_mem = FALSE)

}

## ------------------------------------------------
## Method `ImapCon$fetch_header`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and fetch the results (also saving to disk) using the pipe
out <- con$search_string(expr = "@k-state.edu", where = "CC") %>%
  con$fetch_header()

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "CC")
out <- con$fetch_header()

}

## ------------------------------------------------
## Method `ImapCon$fetch_metadata`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and fetch the results using the pipe
out <- con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_metadata()

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
out <- con$fetch_metadata(msg = res)

}

## ------------------------------------------------
## Method `ImapCon$fetch_text`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and partially fetch the results using the pipe
# first 200 characters, writing to disk, silence results in the console
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_text(partial = "0.200",
                 write_to_disk = TRUE,
                 keep_in_mem = FALSE)

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$fetch_text(msg = res,
               partial = "0.200",
               write_to_disk = TRUE,
               keep_in_mem = FALSE)

}

## ------------------------------------------------
## Method `ImapCon$copy_msg`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and copy the results to another folder
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$copy(to_folder = "Sent")

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$copy(msg = res, to_folder = "Sent")

}

## ------------------------------------------------
## Method `ImapCon$move_msg`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and copy the results to another folder
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$move(to_folder = "Sent")

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$move(msg = res, to_folder = "Sent")

}

## ------------------------------------------------
## Method `ImapCon$append_msg`
## ------------------------------------------------

if (FALSE) {
msg <- paste("From: me@example.com", "To: you@example.com",
             "Subject: Hi", "", "Message body.", sep = "\r\n")
con$append_msg(message = msg, folder = "Drafts")
}

## ------------------------------------------------
## Method `ImapCon$esearch_count`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# count the number of messages marked as "Flagged" and "Answered"
con$esearch_count(flag = c("Flagged", "Answered"))
}

## ------------------------------------------------
## Method `ImapCon$delete_msg`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# delete
con$delete_msg(flag = c("Flagged", "Answered"))
}

## ------------------------------------------------
## Method `ImapCon$expunge`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# count the number of messages marked as "Flagged" and "Answered"
con$esearch_count(flag = c("Flagged", "Answered"))
}

## ------------------------------------------------
## Method `ImapCon$esearch_min_id`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# Search the minimum id of messages marked as "Answered"
con$esearch_min_id(flag = "Answered")
}

## ------------------------------------------------
## Method `ImapCon$esearch_max_id`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# Search the minimum id of messages marked as "Seen"
con$esearch_max_id(flag = "Seen")
}

## ------------------------------------------------
## Method `ImapCon$add_flags`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# Add the "\Seen" permanent flag to the messages received in the last hour
con$search_younger_than(seconds = 3600) %>% # depends on the WITHIN extension
  con$add_flags(flags_to_set = "\\Seen")
}

## ------------------------------------------------
## Method `ImapCon$replace_flags`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# Replace the current flags of the messages in the search results for the
#.. flags "\UNSEEN" and "\Flagged"
con$search_since(date_char = "20-Aug-2020") %>%
  con$replace_flags(flags_to_set = c("\\UNSEEN", "\\Flagged"))
}

## ------------------------------------------------
## Method `ImapCon$remove_flags`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# Remove the "\SEEN" flag from the messages in the search result
con$search_since(date_char = "20-Aug-2020") %>%
  con$remove_flags(flags_to_unset = "\\UNSEEN")
}

## ------------------------------------------------
## Method `ImapCon$get_attachments`
## ------------------------------------------------

if (FALSE) {
# example 1
con$select_folder(name = "INBOX")
con$search_string(expr = "@gmail", where = "CC") %>%
  con$fetch_text(write_to_disk = TRUE) %>% # saving the message's content as txt files
  con$get_attachments()

# example 2
res <- con$search_string(expr = "@gmail", where = "CC")
out <- con$fetch_body(msg = res)
con$get_attachments(msg_list = out)
}

## ------------------------------------------------
## Method `ImapCon$fetch_attachments_list`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and fetch the attachments' list of the messages
out <- con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_attachments_list()
out

# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
out <- con$fetch_attachments_list(msg = res)
out

}

## ------------------------------------------------
## Method `ImapCon$fetch_attachments`
## ------------------------------------------------

if (FALSE) {
con$select_folder(name = "INBOX")
# do a search and fetch the attachments' list of the messages
con$search_string(expr = "@k-state.edu", where = "FROM") %>%
  con$fetch_attachments() # the attachments will be downloaded to disk


# or using a traditional approach
res <- con$search_string(expr = "@k-state.edu", where = "FROM")
con$fetch_attachments(msg = res)

}

Note

References

See also

Methods

Public methods

Method new()

Usage

Arguments

Returns

Method reset_url()

Usage

Arguments

Method reset_username()

Usage

Arguments

Method reset_use_ssl()

Usage

Arguments

Method reset_verbose()

Usage

Arguments

Method reset_buffersize()

Usage

Arguments

Method reset_timeout_ms()

Usage

Arguments

Method reset_password()

Usage

Arguments

Method reset_xoauth2_bearer()

Usage

Arguments

Method disconnect()

Usage

Returns

Examples

Method list_server_capabilities()

Usage

Arguments

Returns

Examples

Method namespace()

Usage

Arguments

Returns

Examples

Method id()

Usage

Arguments

Returns

Examples

Method get_quota_root()

Usage

Arguments

Returns

Examples

Method get_quota()

Usage

Arguments

Returns

Examples

Method noop()

Usage

Arguments

Returns

Examples

Method list_mail_folders()

Usage

Arguments

Returns

Examples

Method list_subscribed_folders()

Usage

Arguments

Returns

Examples

Method list_special_use_folders()

Usage

Method `new()`

Method `reset_url()`

Method `reset_username()`

Method `reset_use_ssl()`

Method `reset_verbose()`

Method `reset_buffersize()`

Method `reset_timeout_ms()`

Method `reset_password()`

Method `reset_xoauth2_bearer()`

Method `disconnect()`

Method `list_server_capabilities()`

Method `namespace()`

Method `id()`

Method `get_quota_root()`

Method `get_quota()`

Method `noop()`

Method `list_mail_folders()`

Method `list_subscribed_folders()`

Method `list_special_use_folders()`

Method `select_folder()`

Method `close_folder()`

Method `unselect_folder()`

Method `examine_folder()`

Method `status()`

Method `create_folder()`

Method `rename_folder()`

Method `delete_folder()`

Method `subscribe_folder()`

Method `unsubscribe_folder()`

Method `list_flags()`

Method `sort()`

Method `thread()`

Method `search()`