Ingest a Local Maildir into an IMAP Folder

Uploads every message file found under a local directory to a folder on the connected IMAP server, using the package's own APPEND implementation (ImapCon$append_msg()). Message files are read as raw bytes and appended verbatim, so any RFC 5322-conformant maildir-style layout (one message per file) can be ingested -- mail server backups, exported archives, or public corpora such as the Enron corpus (see enron_sandbox).

ingest_maildir(
  con,
  path = NULL,
  folder = basename(path),
  create = TRUE,
  recursive = TRUE,
  files = NULL,
  mute = FALSE,
  retries = 1
)

Arguments

con	An ImapCon object, as returned by configure_imap.
path	A string with the path to a local directory containing message files.
folder	A string with the name of the destination folder on the server. Default is basename(path).
create	A logical. If TRUE (default), the destination folder is created with CREATE when it does not exist yet.
recursive	A logical. If TRUE (default), message files are searched recursively under path.
files	An optional character vector of message file paths to ingest, overriding the directory listing. When provided, path and recursive are ignored for file discovery (a subset selected by the caller -- see enron_sandbox -- is uploaded as given). Default is NULL.
mute	A logical. If FALSE, prints progress every 500 messages and a final summary. Default is FALSE.
retries	Number of attempts for each APPEND. Default is 1.

Value

Invisibly, a data.frame with one row per message file: path, size, and appended (a logical indicating whether the upload succeeded).

Details

APPEND via libcurl stores messages with the \Seen flag and the current internal date (see populate_sandbox for the implications); header-based SENT* searches are therefore the appropriate way to query ingested corpora by date. Files that fail to upload (e.g., malformed messages rejected by the server) are skipped with a warning rather than aborting the ingestion.

See also

Other sandbox: enron_sandbox(), populate_sandbox(), sandbox_corpus()

Examples

if (FALSE) {
con <- configure_imap(url = "imap://localhost:1430",
                      username = "testuser", password = "sandbox",
                      use_ssl = FALSE)
# upload a locally stored maildir folder to the server
manifest <- ingest_maildir(con, path = "~/backup/maildir/archive2020",
                           folder = "archive2020")
table(manifest$appended)
}