AERC-JMAP(5)

💌 aerc-jmap — the JMAP config glow-up for aerc(1)

ok so this is the manual page for aerc-jmap, aka the file-formats doc that tells you how to wire your JMAP account into aerc. yes bestie, this is a section 5 page — config file territory 🎀

✨ SYNOPSIS ✨

aerc implements the JMAP protocol as specified by RFCs 8620 and 8621. that's it, that's the synopsis, we love a short king 👑

---

💅 CONFIGURATION 💅

okay so the basic JMAP setup can be done interactively with the :new-account command — no cap, easiest path. 🫶

In accounts.conf (peep aerc-accounts(5) for that whole situation), the following JMAP-specific options are available:

• source = <scheme>://[<username>][:<password>@]<hostname>[:<port>]/<path> — the big one, your whole connection string. Remember that all fields must be URL encoded. The @ symbol, when URL encoded, is %40. ⚠️ so do not just yeet a raw @ in there.

<hostname>[:<port>]/<path> is the HTTPS JMAP session resource as specified in RFC 8620 section 2 without the leading https:// scheme. like, the scheme bit is handled by <scheme>, you don't double up.

Possible values of <scheme> are:

• jmap — JMAP over HTTPS using Basic authentication.
• jmap+oauthbearer — JMAP over HTTPS using OAUTHBEARER authentication.
  • The username is ignored and may be left empty. If specifying the password, make sure to prefix it with : to make it explicit that the username is empty. Or set the username to any random value. E.g.:

source = jmap+oauthbearer://:s3cr3t@example.com/jmap/session
source = jmap+oauthbearer://me:s3cr3t@example.com/jmap/session

Your source credentials must have the urn:ietf:params:jmap:mail capability. no capability, no mail, periodt. 💀

• source-cred-cmd = <command> — Specifies the command to run to get the password for the JMAP 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. so like, the inline one wins, ok?

Example:

source-cred-cmd = pass hostname/username

• outgoing = jmap:// — The JMAP connection can also be used to send emails. No need to repeat the URL nor any credentials. Just the URL scheme will be enough. slay, minimal effort, main character energy ⭐

Your source credentials must have the urn:ietf:params:jmap:submission capability. that's the sending one, different from the mail one above, don't mix them up bestie 🙈

• cache-state = true|false — Cache all email state (mailboxes, email headers, mailbox contents, email flags, etc.) on disk in a levelDB database located in folder ~/.cache/aerc/<account>/state.

The cached data should remain small, in the order of a few megabytes, even for very large email stores. Aerc will make its best to purge deleted/outdated information. It is safe to delete that folder when aerc is not running and it will be recreated from scratch on next startup. 🧚 lowkey self-healing.

Default: false

• cache-blobs = true|false — Cache all downloaded email bodies and attachments on disk as individual files in ~/.cache/aerc/<account>/blobs/<xx>/<blob_id> (where <xx> is a subfolder named after the last two characters of <blob_id>).

Aerc will not purge the cached blobs automatically. Even when their related emails are destroyed permanently from the server. 😭 that's on you to manage. If required, you may want to run some periodic cleanup based on file creation date in a crontab, e.g.:

@daily find ~/.cache/aerc/foo/blobs -type f -mtime +30 -delete

Default: false

• use-labels = true|false — If set to true, mailboxes with the archive role (usually Archive) will be hidden from the directory list and replaced by an all-mail virtual folder. The name of that folder can be configured via the all-mail setting.

:archive flat may still be used to effectively "tag" messages with the hidden Archive mailbox so that they appear in the all-mail virtual folder. When the all-mail virtual folder is selected, :archive flat should not be used and will have no effect. The messages will be grayed out but will never be refreshed until aerc is restarted. 🫠 yeah, grayed out and frozen, iconic behaviour honestly.

Also, this enables support for the :modify-labels (alias :tag) command. 🔥

Default: false

• all-mail = <name> — Name of the virtual folder that replaces the role=archive mailbox when use-labels = true.

Default: All mail

• server-ping = <duration> — Interval the server should ping the client at when monitoring for email changes. The server may choose to ignore this value. By default, no ping will be requested from the server.

See https://pkg.go.dev/time#ParseDuration.

---

🦋 NOTES 🦋

JMAP messages can be seen as "labels" or "tags". Every message must belong to one or more mailboxes (folders in aerc). Each mailbox has a "role" as described in https://www.iana.org/assignments/imap-mailbox-name-attributes/. iykyk, roles are the whole vibe here. 💜

When deleting messages that belong only to the selected mailbox, aerc will attempt to "move" these messages to a mailbox with the trash role. If it cannot find such mailbox or if the selected mailbox is the trash mailbox, it will effectively destroy the messages from the server. 💀 so like, be aware — destroy means destroy, fr fr.

• :delete removes messages from the selected mailbox and effectively does the same thing as :tag -<selected_folder>.
• :cp <foo> is an alias for :tag <foo> or :tag +<foo>.
• :mv <foo> is a compound of :delete and :cp and can be seen as an alias of :tag -<selected_folder> +<foo>.
• :archive flat is an alias for :tag -<selected_folder> +<archive>.

---

👀 SEE ALSO 👀

aerc(1) aerc-accounts(5) — go read those too bestie, they ate 💅

---

👑 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/. 🫶 legends only.

---

ok that's the whole page!! 🌈 this version is from 2026-09-07, and it's the AERC-JMAP(5) page — so like, section 5 of the aerc manual, dated and stamped and everything. go configure your JMAP account and slay ✨🎀💖