IMAP

The IMAP integration backs up mailbox contents from an IMAP server into a Kloset store and restores them to an IMAP server. IMAP (Internet Message Access Protocol) is a standard email protocol used by mail clients to retrieve messages from a mail server over TCP/IP.

The integration includes two connectors:

Requirements

• An IMAP account with read access for backup, and write access for restore.

Typical use cases

• Long-term archival and audit of email hosted on IMAP servers, including folders, metadata and attachments.
• Restoring mailbox snapshots to any compatible IMAP destination, preserving folder structure and message integrity.
• Backing up a single mailbox and its sub-mailboxes rather than an entire account.

Compatibility

• Works with standard IMAP servers, including self-hosted and enterprise environments. Verified end-to-end against Dovecot.

Installation

The IMAP integration is distributed as a Plakar package.

$ plakar pkg add imap

$ plakar pkg show

$ plakar pkg build imap

$ plakar pkg add -allow-unsigned ./imap_v1.0.0_darwin_arm64.ptar

$ plakar pkg show

To list, upgrade, or remove the package, see managing packages guide.

How a backup works

A backup captures the messages of the whole account, or of a single mailbox and everything nested under it when the location ends with a mailbox path. The rest of the account is left untouched. Messages are fetched with BODY.PEEK, so a backup never alters the source mailbox.

Folder hierarchy is preserved across servers even when source and destination use different hierarchy delimiters, for example Dovecot’s . and /. Each mailbox segment is percent-encoded into the snapshot path, so a folder named Work/Notes or Reçus round-trips intact.

Message flags (\Seen, \Answered, \Flagged, \Draft, \Deleted, and keywords such as $Junk) are encoded into each message’s file name and re-applied on restore. The session-only \Recent flag is intentionally dropped.

How a restore works

A restore recreates mailboxes according to the snapshot. Missing mailboxes and their parents are created automatically. Any mailbox path in the destination location is ignored.

Configuration

Backup flow

flowchart LR

subgraph Source["IMAP Server"]
  FS["Mailbox"]
end

Plakar["Plakar"]

Via["Retrieve messages via
IMAP source connector"]

Store["Kloset Store"]

FS --> Via --> Plakar --> Store

Restore flow

flowchart LR

Store["Kloset Store"]

Plakar["Plakar"]

Via["Push messages via
IMAP destination connector"]

subgraph Destination["IMAP Server"]
  FS["Mailbox"]
end

Store --> Plakar --> Via --> FS

Shared configuration

The following options apply to both source and destination connectors. They are set with plakar source add or plakar destination add, and changed with plakar source set or plakar destination set.

Source configuration

The source location can end with a mailbox path to scope the backup. For example, imap://host/Archive backs up Archive and everything nested under it. Nested folders use / regardless of the server’s hierarchy delimiter, and a mailbox name containing / must be percent-encoded (%2F).

During a backup, a stalled or failed message-body fetch is retried once on a fresh connection before being recorded as a per-message error. A transient throttle is therefore recovered transparently.

Destination configuration

Example

Back up an account, or a single folder and its sub-folders:

# Configure an IMAP source connector
$ plakar source add myIMAPsrc imap://imap.mydomain.com:143 \
  username=myuser \
  password=mypassword \
  tls=starttls

# Back up the mailbox
$ plakar at /var/backups backup "@myIMAPsrc"

# Back up only a specific folder (and its sub-folders)
$ plakar source add myArchive imap://imap.mydomain.com/Archive \
  username=myuser password=mypassword tls=starttls
$ plakar at /var/backups backup "@myArchive"

Restore a snapshot:

# Configure an IMAP destination connector
$ plakar destination add myIMAPdst imap://imap.alsomydomain.com:143 \
  username=alsomyuser password=alsomypassword tls=starttls

# Restore the snapshot to the destination
$ plakar at /var/backups restore -to "@myIMAPdst" <snapshot_id>

Limitations and scope

A backup captures the messages within the scoped mailbox, or the entire account when no mailbox path is given, including folder structure and flags.

A backup does not capture:

• Server-side configuration outside the mailbox contents, such as server settings or ACLs.
• The session-only \Recent flag.