ImapCon {mRpostman}R Documentation

An IMAP Connection Class

Description

Configure an IMAP connection using the ImapCon R6 class.

Methods

Public methods

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 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 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 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_mail_folder(name = "INBOX")
}

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 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 new 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 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 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 younger_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. POSIX* like objects, since IMAP servers use this uncommon date format. POSIX* like, since IMAP servers like this not so common 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 all messages received in the last hour (younger than 3600 seconds)
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 esearch_count()

Count the number of messages with a specific flag(s) in a folder (depend 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 (depend 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 (depend 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 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
)
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.

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
)
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.

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.

Note

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

ImapCon$search(): IMAP queries follows 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 multiples 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_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 formating 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.

See Also

Other custom search: AND(), OR(), before(), flag(), larger_than(), older_than(), on(), sent_before(), sent_on(), sent_since(), since(), smaller_than(), string(), younger_than()

Other attachments: list_attachments()

Examples

## Not run: 
# 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...")


## End(Not run)



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

## Not run: 
cap <- con$list_server_capabilities()
cap

## End(Not run)

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

## Not run: 
folders <- con$list_mail_folders()
folders

## End(Not run)

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

## Not run: 
con$select_mail_folder(name = "INBOX")

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
con$examine_folder()

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

## End(Not run)

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

## Not run: 
con$create_folder(name = "New Folder Name")

## End(Not run)

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

## Not run: 
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")

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
con$list_flags()

## End(Not run)

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

## Not run: 
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")))

## End(Not run)

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

## Not run: 
# search for messages with size larger than 512Kb
con$search_larger_than(size = 512000))

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# search for messages with size smaller than 512Kb
con$search_smaller_than(size = 512000))

## End(Not run)

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

## Not run: 
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)

## End(Not run)

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

## Not run: 
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)

## End(Not run)

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

## Not run: 
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)

## End(Not run)

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

## Not run: 
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))

## End(Not run)

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

## Not run: 
# 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)

## End(Not run)

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

## Not run: 
# 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)

## End(Not run)

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

## Not run: 
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)

## End(Not run)

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

## Not run: 
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))

## End(Not run)

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

## Not run: 
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"))

## End(Not run)

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

## Not run: 
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)

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# search for all messages received in the last hour (younger than 3600 seconds)
con$search_younger_than(seconds = 3600)

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# search for all messages received in the last hour (younger than 3600 seconds)
con$search_string(expr = "@k-state.edu", where = "FROM")

## End(Not run)

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

## Not run: 
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)


## End(Not run)

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

## Not run: 
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()


## End(Not run)

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

## Not run: 
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)


## End(Not run)

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

## Not run: 
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)


## End(Not run)

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

## Not run: 
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")


## End(Not run)

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

## Not run: 
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")


## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# count the number of messages marked as "Flagged" and "Answered"
con$esearch_count(flag = c("Flagged", "Answered"))

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# delete
con$delete_msg(flag = c("Flagged", "Answered"))

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# count the number of messages marked as "Flagged" and "Answered"
con$esearch_count(flag = c("Flagged", "Answered"))

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# Search the minimum id of messages marked as "Answered"
con$esearch_min_id(flag = "Answered")

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# Search the minimum id of messages marked as "Seen"
con$esearch_max_id(flag = "Seen")

## End(Not run)

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

## Not run: 
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")

## End(Not run)

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

## Not run: 
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")

## End(Not run)

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

## Not run: 
con$select_folder(name = "INBOX")
# Remove the 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")

## End(Not run)

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

## Not run: 
# 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)

## End(Not run)

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

## Not run: 
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


## End(Not run)

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

## Not run: 
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)


## End(Not run)
[Package mRpostman version 1.1.2 Index]