ImapCon: An IMAP Connection Class

Description

Configure an IMAP connection using the ImapCon R6 class.

Arguments

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 = 5000,
  ...
)

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 5000ms (or 5 seconds). If a first execution is unsuccessful, an error handler in each function (depending on the retries value), will try to reconnect or re-execute the command.

...

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(url)

Arguments

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

Method `reset_username()`

Reset the previously informed username

Usage

ImapCon$reset_username(username)

Arguments

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

Method `reset_ssl()`

Reset the previously informed use_ssl parameter

Usage

ImapCon$reset_ssl(use_ssl)

Arguments

use_ssl: 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(verbose)

Arguments

verbose: 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(buffersize)

Arguments

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.

Method `reset_timeout_ms()`

Reset the previously informed buffersize parameter

Usage

ImapCon$reset_timeout_ms(timeout_ms)

Arguments

timeout_ms: Time in milliseconds (ms) to wait for the execution or re-xecution of a command. Default is 5000ms (or 5 seconds). If a first execution is unsuccessful, an error handler in each function (depending on the retries value), will try to reconnect or re-execute the command.

Method `reset_password()`

Reset the previously informed password

Usage

ImapCon$reset_password(password)

Arguments

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

xoauth2_bearer

A character string containing the oauth2 bearer token.

Method `reset_xoauth2_bearer()`

Reset the previously informed oauth2 bearer token

Usage

ImapCon$reset_xoauth2_bearer(xoauth2_bearer)

Arguments

xoauth2_bearer: 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 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

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

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

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

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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

negate

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

use_uid

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

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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format. POSIX* like objects, since IMAP servers use this unusual 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

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

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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

negate

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

use_uid

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

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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

before_date_char

A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

negate

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

use_uid

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

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 (RFC-2822 Header) date (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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

negate

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

use_uid

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

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 (RFC-2822 Header) date (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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

negate

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

use_uid

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

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 (RFC-2822 Header) date (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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

negate

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

use_uid

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

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 (RFC-2822 Header) date (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 opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

before_date_char

A character string with format "DD-Mon-YYYY", e.g. "01-Apr-2019". We opted for not to use Date or POSIX* like objects, since IMAP servers use this unusual date format.

negate

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

use_uid

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

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

esearch

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

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

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

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

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

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

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

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 is only effective when write_to_disk = TRUE and keep_in_mem = FALSE. It Provides a confirmation message if the command is successfully executed. 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

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 is only effective when write_to_disk = TRUE and keep_in_mem = FALSE. It Provides a confirmation message if the command is successfully executed. 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,
  metadata = 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

metadata

An optional character vector specifying one or more items 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 is only effective when write_to_disk = TRUE and keep_in_mem = FALSE. It Provides a confirmation message if the command is successfully executed. 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

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://tools.ietf.org/html/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://tools.ietf.org/html/rfc2183.

Examples

Run this code

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

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


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

# }
# NOT RUN {
cap <- con$list_server_capabilities()
cap
# }
# NOT RUN {
## ------------------------------------------------
## Method `ImapCon$list_mail_folders`
## ------------------------------------------------

# }
# NOT RUN {
folders <- con$list_mail_folders()
folders
# }
# NOT RUN {
## ------------------------------------------------
## Method `ImapCon$select_folder`
## ------------------------------------------------

# }
# NOT RUN {
con$select_mail_folder(name = "INBOX")
# }
# NOT RUN {
## ------------------------------------------------
## Method `ImapCon$examine_folder`
## ------------------------------------------------

# }
# NOT RUN {
con$select_folder(name = "INBOX")
con$examine_folder()

# or directly:
con$examine_folder("Sent")
# }
# NOT RUN {
## ------------------------------------------------
## Method `ImapCon$create_folder`
## ------------------------------------------------

# }
# NOT RUN {
con$create_folder(name = "New Folder Name")
# }
# 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")
# }
# NOT RUN {
## ------------------------------------------------
## Method `ImapCon$list_flags`
## ------------------------------------------------

# }
# NOT RUN {
con$select_folder(name = "INBOX")
con$list_flags()
# }
# 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")))
# }
# NOT RUN {
## ------------------------------------------------
## Method `ImapCon$search_larger_than`
## ------------------------------------------------

# }
# NOT RUN {
# search for messages with size larger than 512Kb
con$search_larger_than(size = 512000))
# }
# 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))
# }
# 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)
# }
# 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)
# }
# 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)
# }
# 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))
# }
# 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)
# }
# 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)
# }
# 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)
# }
# 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))
# }
# 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"))
# }
# 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)
# }
# 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)
# }
# 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")
# }
# 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)

# }
# 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()

# }
# 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)

# }
# 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)

# }
# 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")

# }
# 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")

# }
# 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"))
# }
# NOT RUN {
## ------------------------------------------------
## Method `ImapCon$delete_msg`
## ------------------------------------------------

# }
# NOT RUN {
con$select_folder(name = "INBOX")
# delete
con$delete_msg(flag = c("Flagged", "Answered"))
# }
# 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"))
# }
# 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")
# }
# 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")
# }
# 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")
# }
# 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")
# }
# 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")
# }
# 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)
# }
# 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

# }
# 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)

# }

Run the code above in your browser using DataLab

Description

Arguments

Methods

Public methods

Method new()

Usage

Arguments

Returns

Method reset_url()

Usage

Arguments

Method reset_username()

Usage

Arguments

Method reset_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 list_server_capabilities()

Usage

Arguments

Returns

Examples

Method list_mail_folders()

Usage

Arguments

Returns

Examples

Method select_folder()

Usage

Arguments

Returns

Examples

Method examine_folder()

Usage

Arguments

Returns

Examples

Method create_folder()

Usage

Arguments

Returns

Examples

Method rename_folder()

Usage

Arguments

Returns

Examples

Method list_flags()

Usage

Arguments

Returns

Examples

Method search()

Usage

Arguments

Returns

Examples

Method search_larger_than()

Usage

Arguments

Returns

Examples

Method search_smaller_than()

Usage

Arguments

Method `new()`

Method `reset_url()`

Method `reset_username()`

Method `reset_ssl()`

Method `reset_verbose()`

Method `reset_buffersize()`

Method `reset_timeout_ms()`

Method `reset_password()`

Method `reset_xoauth2_bearer()`

Method `list_server_capabilities()`

Method `list_mail_folders()`

Method `select_folder()`

Method `examine_folder()`

Method `create_folder()`

Method `rename_folder()`

Method `list_flags()`

Method `search()`

Method `search_larger_than()`

Method `search_smaller_than()`

Method `search_before()`

Method `search_since()`

Method `search_on()`

Method `search_period()`

Method `search_sent_before()`

Method `search_sent_since()`

Method `search_sent_on()`

Method `search_sent_period()`

Method `search_flag()`

Method `search_older_than()`

Method `search_younger_than()`

Method `search_string()`

Method `fetch_body()`

Method `fetch_header()`