AERC-IMAP(5)                  File Formats Manual                 AERC-IMAP(5)

NAME
       aerc-imap - IMAP configuration for aerc(1)

SYNOPSIS
       aerc implements the IMAP protocol as specified by RFC 3501, with the
       following IMAP extensions:

       •   IDLE (RFC 2177)
       •   LIST-STATUS (RFC 5819)
       •   X-GM-EXT-1 (Gmail)

CONFIGURATION
       Basic IMAP configuration may be done interactively with the :new-
       account command.

       In accounts.conf (see aerc-accounts(5)), the following IMAP-specific
       options are available:

       source =
       <scheme>://<username>[:<password>]@<hostname>[:<port>]?[<oauth2_params>]
           Remember that all fields must be URL encoded. The @ symbol, when
           URL encoded, is %40.

           Possible values of <scheme> are:

           imap
               IMAP with STARTTLS

           imap+insecure
               IMAP without STARTTLS

           imaps
               IMAP with TLS/SSL

           imaps+insecure
               IMAP with TLS/SSL, skipping certificate verification

           imaps+oauthbearer
               IMAP with TLS/SSL using OAUTHBEARER Authentication

               <oauth2_params>:

               If specified and a token_endpoint is provided, the configured
               password is used as a refresh token to obtain an access token.
               If token_endpoint is omitted, refresh token exchange is
               skipped, and the password acts like an access token instead.

               •   token_endpoint (optional)
               •   client_id (optional)
               •   client_secret (optional)
               •   scope (optional)

               Example:
                   imaps+oauthbearer://...?token_endpoint=https://...&client_id=

           imaps+xoauth2
               IMAP with TLS/SSL using XOAUTH2 Authentication. Parameters are
               the same as OAUTHBEARER.

       source-cred-cmd = <command>
           Specifies the command to run to get the password for the IMAP
           account. This command will be run using sh -c command. If a
           password is specified in the source option, the password will take
           precedence over this command.

           Example:
               source-cred-cmd = pass hostname/username

       connection-timeout = <duration>
           Maximum delay to establish a connection to the IMAP server. See
           https://pkg.go.dev/time#ParseDuration.

           Default: 30s

       keepalive-period = <duration>
           The interval between the last data packet sent (simple ACKs are not
           considered data) and the first keepalive probe. After the
           connection is marked to need keepalive, this counter is not used
           any further. See https://pkg.go.dev/time#ParseDuration.

           By default, the system tcp socket settings are used.

       keepalive-probes = <int>
           The number of unacknowledged probes to send before considering the
           connection dead and notifying the application layer.

           By default, the system tcp socket settings are used. If keepalive-
           period is specified, this option defaults to 3 probes.

           This option is only supported on linux. On other platforms, it will
           be ignored.

       keepalive-interval = <duration>
           The interval between subsequential keepalive probes, regardless of
           what the connection has exchanged in the meantime. Fractional
           seconds are truncated.

           By default, the system tcp socket settings are used. If keepalive-
           period is specified, this option defaults to 3s.

           This option is only supported on linux. On other platforms, it will
           be ignored.

       check-mail-include = <folder1,folder2,folder3...>
           Specifies the comma separated list of folders to include when
           checking for new mail with :check-mail. Names prefixed with ~ are
           interpreted as regular expressions. This setting is ignored if your
           IMAP server supports the LIST-STATUS command, in which case all
           folders will be checked.

           By default, all folders are included.

       check-mail-exclude = <folder1,folder2,folder3...>
           Specifies the comma separated list of folders to exclude when
           checking for new mail with :check-mail. Names prefixed with ~ are
           interpreted as regular expressions. This setting is ignored if your
           IMAP server supports the LIST-STATUS command, in which case all
           folders will be checked. Note that this overrides anything from
           check-mail-include.

           By default, no folders are excluded.

       cache-headers = true|false
           If set to true, headers will be cached. The cached headers will be
           stored in $XDG_CACHE_HOME/aerc, which defaults to ~/.cache/aerc.

           Default: false

       cache-max-age = <duration>
           Defines the maximum age of cached files. Note: the longest unit of
           time cache-max-age can be specified in is hours. Set to 0 to
           disable cleaning the cache

           Default: 720h (30 days)

       idle-timeout = <duration>
           The length of time the client will wait for the server to send any
           final update before the IDLE is closed.

           Default: 10s

       idle-debounce = <duration>
           Specifies the length of time from the last client command until the
           idler starts.

           Default: 10ms

       use-gmail-ext = true|false
           If set to true, the X-GM-EXT-1 extension will be used if supported.
           This only works for Gmail accounts.

           Default: false

SEE ALSO
       aerc(1) aerc-accounts(5)

AUTHORS
       Originally created by Drew DeVault and maintained by Robin Jarry who is
       assisted by other open source contributors. For more information about
       aerc development, see https://sr.ht/~rjarry/aerc/.

                                  2024-07-30                      AERC-IMAP(5)