home | help 
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 fol-
     lowing 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 op-
     tions are available:

     source		=	       <scheme>://<username>[:<password>]@<host-
     name>[:<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 pass-
	     word is used as a refresh token to obtain an access token.  If  to-
	     ken_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 speci-
	 fied 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: 90s

     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 con-
	 nection dead and notifying the application layer.

	 By default, the system tcp socket settings are used.  If  keepalive-pe-
	 riod 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-pe-
	 riod 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  sup-
	 ports	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 sup-
	 ports 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  clean-
	 ing the cache

	 Default: 720h (30 days)

     idle-timeout = <duration>
	 The  length of time the client will wait for the server to send any fi-
	 nal 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

     expunge-policy = auto|low-to-high|stable
	 Specifies  the  deletion policy used when deleting multiple messages in
	 one shot. auto attempts to automatically detect it, and will be correct
	 most of the times. low-to-high specifies that the server  deletes  mes-
	 sages	in increasing sequence number order (this is what GMail or Fast-
	 Mail do, and will correctly handled by the automatic detection). stable
	 specifies that the server does not mutate the sequence numbers  it  re-
	 ceived  (this is what Dovecot or WorkMail do, and is not reliably auto-
	 matically detected).

	 Default: auto

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

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

				   2026-08-30			    AERC-IMAP(5)
home | help