Imapc Mailbox Format

The imapc storage accesses a remote IMAP server as if it were a regular (local) Dovecot mailbox format. Dovecot can treat it as a dummy storage or optionally a more capable storage.

Settings

imapc

Value	Named Filter
See Also	imapc client_auth client_auth_authzid client_auth_authid client_auth_password client_auth_mechanism client authentication

This settings filter provides a scope for settings for imapc.

The filter is needed for configuring the generic client_auth and ssl_client_* settings for imapc specifically, since the same settings are used also by other clients.

Example:

imapc {
  host = imap.example.com
  ssl = imaps
  client_auth_authzid = %{user}
  client_auth_password = secret
}

imapc_cmd_timeout

Default	5 mins
Value	time

How long to wait for a reply to an IMAP command sent to the remote IMAP server before disconnecting and retrying.

imapc_connection_retry_count

Default	1
Value	unsigned integer

How many times to retry connection against a remote IMAP server?

imapc_connection_retry_interval

Default	1 secs
Value	time (milliseconds)

How long to wait between retries against a remote IMAP server?

imapc_connection_timeout_interval

Default	30secs
Value	time (milliseconds)

How long to wait before considering a connection attempt as timed out.

imapc_features

Default	[None]
Value	Boolean List
Changes	Changed: 3.0.0 Several features are now automatically enabled and the respective flags dropped. In their place new flags to disable these features were added.

List of features, optimizations, and workarounds that can be enabled.

Changed: 3.2.0 Any remote IMAP server extension can now be disabled by using no- prefixed with the capability name. For example no-sort, no-sort=display or no-quota.

Features

no-acl

If the imap-acl plugin is loaded, the imapc acl feature is automatically enabled. With it IMAP ACL commands (MYRIGHTS, GETACL, SETACL, DELETEACL) are proxied to the imapc remote location. Note that currently these commands are attempted to be used even if the remote IMAP server doesn't advertise the ACL capability.

To disable this feature either unload the imap-acl plugin or provide this feature.

Changed: 3.0.0

Earlier versions had an "acl" feature, which is now enabled by default.

no-delay-login

Immediately connect to the remote server. By default this is delayed until a command requires a connection.

Changed: 3.0.0

Earlier versions had a "delay-login" feature, which is now enabled by default.

gmail-migration

Enable Gmail-specific migration. Use IMAP X-GM-MSGID as POP3 UIDL. Add $GMailHaveLabels keyword to mails that have X-GM-LABELS except for Muted keyword (to be used for migrating only archived emails in All Mails). Add pop3_deleted_flag to mails that don't exist in POP3 server.

no-modseq

Disable access to MODSEQ and HIGHESTMODSEQ fields. By default these fields are available if the remote server advertises the CONDSTORE or the QRESYNC capability. If modseqs are disabled, or not supported by the new server, they can still be used if imapc is configured to have local index files.

Changed: 3.0.0

Earlier versions had a "modseq" feature, which is now enabled by default.

proxyauth

Use Sun/Oracle IMAP-server specific PROXYAUTH command to do master user authentication. Normally this would be done using the SASL PLAIN authentication.

send-id

Send session ID with the IMAP ID x-session-ext-id parameter. If login_trusted_networks on the target host is configured to trust the connecting imapc IP, the session ID is preserved as the new imapc connection's session ID prefix.

throttle:<INIT>:<MAX>:<SHRINK>

When receiving [THROTTLED] response (from Gmail), throttling is applied.

INIT = initial throttling msecs (default: 50 ms), afterwards each subsequent [THROTTLED] doubles the throttling until MAX is reached (default: 16000 ms). When [THROTTLED] is not received for a while, it's shrunk again. The initial shrinking is done after SHRINK (default: 500 ms). If [THROTTLED] is received again within this timeout, it's doubled, otherwise both throttling and the next shrinking timeout is shrank to 3/4 the previous value.

Optimizations

no-fetch-bodystructure

Disable fetching of IMAP BODY and BODYSTRUCTURE from the remote server. Instead, the whole message body is fetched to regenerate them.

Changed: 3.0.0

Earlier versions had a "fetch-bodystructure" feature, which is now enabled by default.

no-fetch-headers

Disable fetching of specific message headers from the remote server using the IMAP FETCH BODY.PEEK[HEADER.FIELDS(...)] command. Instead, the whole header is fetched and the wanted headers are parsed from it.

Changed: 3.0.0

Earlier versions had a "fetch-headers" feature, which is now enabled by default.

no-fetch-size

Disable fetching of message sizes from the remote server using the IMAP FETCH RFC822.SIZE command. Instead, the whole message body is fetched to calculate the size.

Changed: 3.0.0

Earlier versions had a "rfc822.size" feature, which is now enabled by default.

no-metadata

Disable the detection of the METADATA capability from the remote server. The client will receive a NO [UNAVAILABLE] response for any request that requires access to metadata on the remote server (the same happens if the server does not announce the capability at all).

no-search

Disable searching messages using the IMAP SEARCH command. Instead, all the message headers/bodies are fetched to perform the search locally.

Changed: 3.0.0

Earlier versions had a "search" feature, which is now enabled by default.

Workarounds

fetch-fix-broken-mails

If a FETCH returns NO (but not NO [LIMIT] or NO [SERVERBUG]), assume the mail is broken in server and just treat it as if it were an empty email.

DANGER

This is often a dangerous option! It's not safe to assume that NO means a permanent error rather than a temporary error. This feature should be enabled only for specific users who have been determined to be broken.

fetch-msn-workarounds

Try to ignore wrong message sequence numbers in FETCH replies whenever possible, preferring to use the returned UID number instead.

no-examine

Use SELECT instead of EXAMINE even when we don't want to modify anything in the mailbox. This is a Courier-workaround where it didn't permanently assign UIDVALIDITY to an EXAMINEd mailbox, but assigned it for SELECTed mailbox.

no-qresync Added: 3.0.0

This can be used to work around a Zimbra bug where it doesn't send untagged "OK [CLOSED]" imap-resp-code when selecting a folder.

zimbra-workarounds

Fetch full message using BODY.PEEK[HEADER] BODY.PEEK[TEXT] instead of just BODY.PEEK[] because the header differs between these two when there are illegal control chars or 8bit chars. This mainly caused problems with dsync, but this should no longer be a problem and there's probably no need to enable this workaround.

imapc_host

Default	[None]
Value	string

The remote IMAP host to connect to.

imapc_list_prefix

Default	[None]
Value	string

Access only mailboxes under this prefix.

Example, for a source IMAP server that uses an INBOX namespace prefix:

imapc_list_prefix = INBOX

imapc_master_user

Default	[None]
Value	string
See Also	imapc_password imapc_user
Changes	Removed: 3.3.0 Renamed to client_auth_authid inside the imapc filter, i.e. imapc/client_auth_authid.

The master username to authenticate as on the remote IMAP host.

To authenticate as a master user but use a separate login user, the following configuration should be employed, where the credentials are represented by masteruser and masteruser-secret:

imapc_user = %{user}
imapc_master_user = masteruser
imapc_password = masteruser-secret

Mail user variables can be used.

imapc_max_idle_time

Default	29 mins
Value	time

Send a command to the source IMAP server as a keepalive after no other command has been sent for this amount of time.

Dovecot will send either NOOP or DONE to the source IMAP server.

imapc_max_line_length

Default	unlimited
Value	size

The maximum line length to accept from the remote IMAP server.

This setting is used to limit maximum memory usage.

imapc_password

Default	[None]
Value	string
See Also	imapc_master_user imapc_user imapc_sasl_mechanisms
Changes	Removed: 3.3.0 Renamed to client_auth_password inside the imapc filter, i.e. imapc/client_auth_password.

The authentication password for the remote IMAP server.

If using master users, this setting will be the password of the master user.

imapc_port

Default	143
Value	Port Number

The port on the remote IMAP host to connect to.

imapc_rawlog_dir

Default	[None]
Value	directory path
See Also	rawlog
Changes	Changed: 3.2.0 Setting type changed.

Log all IMAP traffic input/output to this directory.

imapc_sasl_mechanisms

Default	plain
Value	Boolean List
Changes	Deprecated: 3.3.0 The setting is obsolete, and kept only for backwards compatibility. Each listed mechanism is translated into a client_auth filter in the listed order, so existing configurations keep working. New configurations should use client_auth directly.

The SASL mechanisms to use for authentication when connection to a remote IMAP server.

The first one advertised by the remote IMAP sever is used.

imapc_sasl_mechanisms {
  external = yes
  plain = yes
  login = yes
}

Supported mechanisms are:

• ANONYMOUS
• EXTERNAL
• LOGIN
• OAUTHBEARER
• PLAIN
• SCRAM-SHA-1
• SCRAM-SHA-1-PLUS
• SCRAM-SHA-256
• SCRAM-SHA-256-PLUS
• XOAUTH2

Note that imapc_password is ignored for ANONYMOUS and EXTERNAL mechanisms. For OAUTHBEARER and XOAUTH2 imapc_password should be bearer token.

imapc_ssl

Default	no
Value	string
Allowed Values	noimapsstarttls

Use TLS to connect to the remote IMAP server.

Value	Description
no	No TLS
imaps	Explicitly connect to remote IMAP port using TLS
starttls	Use IMAP STARTTLS command to switch to TLS connection

imapc_ssl_verify

Default	yes
Value	boolean
See Also	imapc_ssl
Changes	Removed: 3.1.0 Dropped in favor of using the global ssl_client_require_valid_cert.

Verify remote IMAP TLS certificate?

Verification may be disabled during testing, but should be enabled during production use.

Only used if imapc_ssl is enabled.

imapc_user

Default	%{owner_user}
Value	string
See Also	imapc_master_user imapc_password imapc_sasl_mechanisms
Changes	Removed: 3.3.0 Renamed to client_auth_authzid inside the imapc filter, i.e. imapc/client_auth_authzid.

The user identity to be used for performing a regular IMAP LOGIN to the source IMAP server.

Mail user variables can be used.

The login to the remote server is configured with the client authentication settings inside the imapc filter.

Configuration Example

Do a regular IMAP LOGIN, using STARTTLS, to imap.example.com:

# In-memory index files:
mail_driver = imapc
mail_path =

# OR, Store index files locally:
#mail_path = ~/imapc

imapc {
  host = imap.example.com
  port = 143
  ssl = starttls
  client_auth_authzid = user@example.com
  client_auth_password = secret
}

Quota

Using the imapc quota driver allows asking for the quota from remote IMAP server. By default it uses GETQUOTAROOT INBOX to retrieve the quota.

There are two parameters that can be used to control how the quota is looked up:

quota_imapc_mailbox_name

Default	INBOX
Value	string
See Also	quota_imapc_root_name

If non-empty, use GETQUOTAROOT <mailbox> to get the imapc quota root. Used only with Quota Driver: Imapc.

quota_imapc_root_name

Default	[None]
Value	string
See Also	quota_imapc_mailbox_name

If quota_imapc_mailbox_name is empty, use GETQUOTA <name> to get the imapc quota.

Some servers may have an empty quota root name. This is why if this setting and quota_imapc_mailbox_name both have empty values, this setting is used. Used only with Quota Driver: Imapc.

Example

quota "User Quota" {
  driver = imapc
  imapc_root_name = Remote Quota
}