AERC-IMAP(5)

📦
version 0.22.0 · 17 versions
, in arch rolling

✨ aerc-imap ✨

okay bestie, welcome to the aerc-imap manual page — she's part of the aerc(1) family and she's literally all about getting your IMAP life together 💌

🌸 NAME 🌸

aerc-imap — the IMAP configuration page for aerc(1), aka the glow-up guide for your mail account 🎀

🦋 SYNOPSIS 🦋

So here's the vibe: aerc implements the IMAP protocol exactly as specified by RFC 3501, and on top of that she speaks these IMAP extensions, no cap:

like, she's fluent 💅

💖 CONFIGURATION 💖

The basic IMAP setup can be done interactively with the :new-account command — yes, a whole wizard, we love a low-effort moment ✨

Then, inside accounts.conf (peep aerc-accounts(5) for that whole situation), these IMAP-specific options are available:

  • source =
<scheme>://<username>[:<password>]@<hostname>[:<port>]?[<oauth2_params>]

okay IMPORTANT: every single field has to be URL encoded, bestie. The @ symbol, when URL encoded, is %40. Don't forget or she will simply not work 😭

The 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, but skipping certificate verification
  • imaps+login — IMAP with TLS/SSL using the LOGIN authentication mechanism. This one is the fallback when PLAIN authentication isn't available. Most users should not need to specify this explicitly 🫶
  • imaps+oauthbearer — IMAP with TLS/SSL using OAUTHBEARER Authentication

and here's the <oauth2_params> tea ☕:

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, the refresh token exchange is skipped entirely, and the password just acts like an access token instead. iconic behaviour honestly.

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

Example, because we're visual learners:

imaps+oauthbearer://...?token_endpoint=https://...&client_id=
  • imaps+xoauth2 — IMAP with TLS/SSL using XOAUTH2 Authentication. The parameters are the same as OAUTHBEARER, so no new lore 🔥
  • source-cred-cmd = <command> — tells aerc which command to run to get the password for the IMAP account. This command will be run using sh -c command. And heads up: if a password is specified in the source option, that password takes precedence over this command 👑

Example:

source-cred-cmd = pass hostname/username

Default: 90s

  • keepalive-period = <duration> — the interval between the last data packet sent (simple ACKs are not considered data, bestie) and the first keepalive probe. Once the connection is marked as needing 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. sorry babes 🫠
  • keepalive-interval = <duration> — the interval between subsequential keepalive probes, regardless of what the connection has exchanged in the meantime. Fractional seconds are truncated, so no half-seconds for you.

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. same energy as above 🙈
  • check-mail-include = <folder1,folder2,folder3...> — 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...> — 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 also 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 — she's the main character here 💅

By default, no folders are excluded.

  • cache-headers = true|false — if set to true, headers will be cached. The cached headers get 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> — the length of time from the last client command until the idler starts.

Default: 10ms

  • expunge-policy = auto|low-to-high|stable — 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 messages in increasing sequence number order (this is what GMail and FastMail do, and is correctly handled by the automatic detection). stable specifies that the server does not mutate the sequence numbers it received (this is what Dovecot and WorkMail do, and is not reliably automatically detected — so be careful with that one, fr fr).

Default: auto

  • debug-log-path = <path> — the path where to store low-level IMAP debug logs (genuinely useful to debug interactions between aerc and IMAP servers 🔍). If this path is writable, aerc will create and log to one file per account, called imap_debug_ACCOUNTNAME.log.

By default, low-level IMAP debug logs are not generated.

🌈 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/.

and that's the whole page, bestie 🫶 this edition is dated 2026-09-07, from the File Formats Manual corner of the universe, filed under AERC-IMAP(5) — slay, go configure your mail ✨💜

📦 where this page comes from