AERC-TEMPLATES(7)

💌 AERC-TEMPLATES(7) — template file specification for aerc(1) 💌

okay bestie, welcome to the aerc-templates page 💖 it lives in the Miscellaneous Information Manual, and it's literally the template file specification for aerc(1). Buckle up, because this is giving “spec sheet but make it cute” energy ✨

---

🌸 NAME 🌸

aerc-templates - template file specification for aerc(1)

---

✨ SYNOPSIS ✨

aerc uses the go text/template package for the template parsing. Refer to the go text/template documentation for the general syntax. The template syntax described below can be used for message template files and for dynamic formatting of some UI app 🫶

Template files are composed of headers, followed by a newline, followed by the body text.

Example:

X-Clacks-Overhead: GNU Terry Pratchett

Hello,

Greetings,
Chuck

⚠️ If you have a template that doesn't add any header, it must be preceded by a newline, to avoid parsing parts of the body as header text. no cap, this one matters 😭

👑 All headers defined in the template will have precedence over any headers that are initialized by aerc (e.g. Subject, To, From, Cc) when composing a new message, forwarding or replying.

---

🌈 MESSAGE DATA 🌈

The following data can be used in templates. Though they are not all available always.

🎀 Addresses 🎀

An array of mail.Address. That can be used to add sender or recipient names to the template.

• {{.From}} — List of senders.
• {{.Peer}} — List of senders or To recipients if the message is from you.
• {{.To}} — List of To recipients. Not always Available.
• {{.ReplyTo}} — List of ReplyTo recipients. Not always Available.
• {{.Cc}} — List of Cc recipients. Not always Available.
• {{.Bcc}} — List of Cc recipients. Not always Available.
• {{.OriginalFrom}} — List of senders of the original message. Available for quoted reply and forward.

Example:

Get the name of the first sender.

{{(index .From 0).Name}}
{{index (.From | names) 0}}

Get the email address of the first sender.

{{(index .From 0).Address}}

🦋 Date and Time 🦋

The date and time information is always available and can be easily formatted.

• {{.Date}} — Date and time information when the compose window is opened.
• {{.OriginalDate}} — Date and time when the original message was received. Available for quoted reply and forward.

To format the date fields, dateFormat and .Local are provided. Refer to the TEMPLATE FUNCTIONS section for details.

🌸 Subject 🌸

The subject of the email (ThreadPrefix will be empty unless threading is enabled).

{{.ThreadPrefix}}{{if .ThreadFolded}}{{printf "{%d}" .ThreadCount}}{{end}}{{.Subject}}

The subject of the email stripped of any Re: and Fwd: prefixes.

{{.SubjectBase}}

🔥 Number 🔥

The message number in the message list (starting from 1).

{{.Number}}

🧚 Threading 🧚

When threading is enabled, these attributes are available in the message list:

• ThreadPrefix — If the message is part of a thread, this will contain arrows that represent the message tree based on In-Reply-To and References headers.
• ThreadFolded — Will be true if the message has thread children which are hidden by :fold.
• ThreadCount — The number of messages in the thread.
• ThreadUnread — The number of unread messages in the thread.
• ThreadContext — Will be true if the message is shown for display context only.
• ThreadOrphan — Will be true if the message has missing ancestors.

💅 Flags 💅

List of message flags, not available when composing, replying nor forwarding. This is a list of strings that may be converted to a single string with join.

{{.Flags | join ""}}

⭐ IsReplied, IsForwarded, HasAttachment, IsFlagged, IsRecent, IsUnread, IsMarked, IsDraft ⭐

Individual boolean flags. Not available when composing, replying nor forwarding.

{{if .IsFlagged}}★{{end}}

🍓 Labels 🍓

Message labels (for example notmuch tags). Not available when composing, replying nor forwarding. This is a list of strings that may be converted to a single string with join.

{{.Labels | join " "}}

💜 Size 💜

The size of the message in bytes. Not available when composing, replying nor forwarding. It can be formatted with humanReadable.

{{.Size | humanReadable}}

🎀 Filename 🎀

The full path of the message file. Not available when composing, replying nor forwarding. For the notmuch backend, it returns a random filename if there are multiple files associated with the message.

🦋 Filenames 🦋

A list of the full paths of the files associated with the message. For maildir this is always a list with a single element. Not available when composing, replying nor forwarding.

🌈 Any header value 🌈

Any header value of the email.

{{.Header "x-foo-bar"}}

Any header values of the original forwarded or replied message:

{{.OriginalHeader "x-foo-bar"}}

📨 Message-ID 📨

The message-ID of the message.

:term b4 am {{.MessageId}}

🧚 MIME Type 🧚

MIME type is available for quoted reply and forward.

• {{.OriginalMIMEType}} — MIME type info of quoted mail part. Usually text/plain or text/html.

💌 Original Message 💌

When using quoted reply or forward, the original message is available in a field called OriginalText.

{{.OriginalText}}

✨ Signature ✨

The signature of the currently selected account obtained from signature-file or signature-cmd.

{{.Signature}}

👑 Account info 👑

The current account name:

{{.Account}}

The current account's backend:

{{.AccountBackend}}

The current account's from address:

{{.AccountFrom}}
{{.AccountFrom.Address}}

Currently selected mailbox folder:

{{.Folder}}

Current message counts for all folders:

{{.Recent}} {{.Unread}} {{.Exists}}
{{.RUE}}

The new message status for the account. New messages are such that have arrived since the account tab last had focus. The flag is currently only set when aerc is running at the time of the arrival, i.e. messages that have arrived while aerc was not running will not be indicated.

{{.HasNew}}

IANA role of the mailbox, converted to lowercase:

{{.Role}}

aerc implements two additional custom roles: A 'query' role is given to folders from a notmuch query-map and 'virtual' indicates a virtual node in the directory tree listing:

{{if eq .Role "query"}}{{...}}{{else}}{{...}}{{end}}

Current message counts for specific folders:

{{.Recent "inbox"}}
{{.Unread "inbox" "aerc/pending"}}
{{.Exists "archive" "spam" "foo/baz" "foo/bar"}}
{{.RUE "inbox"}}

💻 Status line 💻

The following data will only be available in the status line templates:

Connection state.

{{.Connected}}
{{.ConnectionInfo}}

General status information (e.g. filter, search) separated with [statusline].separator.

{{.ContentInfo}}

Combination of {{.ConnectionInfo}} and {{.StatusInfo}} separated with [statusline].separator.

{{.StatusInfo}}

General on/off information (e.g. passthrough, threading, sorting, visual mode), separated with [statusline].separator.

{{.TrayInfo}}

Currently pressed key sequence that does not match any key binding and/or is incomplete.

{{.PendingKeys}}

🎀 Terminal 🎀

The following can only be used in the terminal tab title template:

Bell state indicating whether the bell was rung since the terminal tab last had focus.

{{.Bell}}

Title of the terminal. This is typically what the program running in the terminal requests it to be or the name of the command.

{{.Title}}

✨ TEMPLATE FUNCTIONS ✨

okay so besides the standard functions that live in go's text/template docs, aerc hands you these extra little icons 💅 use them, they're so good:

🎀 wrap

Wraps the original text to however many characters per line you tell it. slay.

{{wrap 72 .OriginalText}}

🎀 quote

Sticks "> " at the front of every single line. quoting icon behavior.

{{quote .OriginalText}}

🎀 trimSignature

Takes the signature off a mail you passed in. Quoted signatures stay exactly as they are — no touchy ✋

{{trimSignature .OriginalText}}

🎀 join

Joins your list of strings together with a separator, bestie:

{{.To | names | join ", "}}

🎀 split

Splits a string into a string slice, using a separator. the reverse vibe 💫

{{.To | names | join ", " | split ", "}}

🎀 names

Pulls the names part out of a mail.Address list. If there's literally no name available, you get the mbox back instead (that's the email address without the @domain part, iykyk).

{{.To | names | join ", "}}
{{index (.To | names) 0}}

🎀 firstnames

Pulls the first names part out of a mail.Address list. No name available? You get the short mbox instead (the start of the email address, no @domain).

{{.To | firstnames | join ", "}}
{{index (.To | firstnames) 0}}

🎀 initials

Grabs the initials from the names part of a mail.Address list. If there's no name, it gives you the first letter of the email address instead 🫶

{{.To | initials | join ", "}}
{{index (.To | initials) 0}}

🎀 emails

Pulls the addresses part out of a mail.Address list.

{{.To | emails | join ", "}}
{{index (.To | emails) 0}}

🎀 mboxes

Pulls the mbox part out of a mail.Address list — like smith from smith@example.com.

{{.To | mboxes | join ", "}}
{{index (.To | mboxes) 0}}

🎀 shortmboxes

Pulls the short mbox part out of a mail.Address list — like smith from smith.and.wesson@example.com.

{{.To | shortmboxes | join ", "}}
{{index (.To | shortmboxes) 0}}

🎀 persons

Formats a list of mail.Address into a list of strings holding the human readable form of RFC5322 — like Firstname Lastname <email@address.tld>. iconic.

{{.To | persons | join ", "}}
{{index (.To | persons) 0}}

🎀 .Attach

Attaches a file to the message you're composing. attaching things is main character energy fr.

{{.Attach '/usr/libexec/aerc/filters/html'}}

🎀 exec

Runs an external command, and feeds the second argument into its stdin. The command gets executed with the same search $PATH as aerc filters — check aerc-config(5), FILTERS section, for the deets.

{{exec `html` .OriginalText}}

🎀 .Local

Converts the date to the local timezone, as specified by the locale 🌍

{{.Date.Local}}

🎀 dateFormat

Formats the date and time according to the format you pass as the second argument. Heads up: the format has to follow go's time package format, no cap.

{{dateFormat .Date "Mon Jan 2 15:04:05 -0700 MST 2006"}}

You can also use the .DateAutoFormat method to format the date according to the *-time*format settings:

{{.DateAutoFormat .OriginalDate.Local}}

🎀 now

Returns the current date as a golang time.Time object, which you can then format with dateFormat. time is fake but the timestamp is real ✨

{{dateFormat now "Mon Jan 2 15:04:05 -0700 MST 2006"}}

🎀 humanReadable

Returns the human readable form of an integer value. numbers but make them cute.

{{humanReadable 3217653721}}

🎀 cwd

Returns the current working directory, with your home dir swapped out for ~. very cozy.

{{cwd}}

🎀 compactDir

Squishes a directory path into a compact form. The directory name gets split on /, and each part gets reduced to the first letter of its name — so INBOX/01_WORK/PROJECT becomes I/W/PROJECT. obsessed.

{{compactDir .Folder}}

🎀 contains

Checks if a string contains a substring.

{{contains "<!DOCTYPE html>" .OriginalText}}

🎀 hasPrefix

Checks if a string has a prefix.

{{hasPrefix "Business" .Folder}}

🎀 toLower

Converts a string to lowercase.

{{toLower "SPECIAL OFFER!"}}

🎀 toUpper

Converts a string to uppercase. SCREAM IT 🔥

{{toUpper "important"}}

🎀 replace

Does a regular expression substitution on the string you pass in.

{{replace `(.+) - .+ at .+..+` `$1` ((index .OriginalFrom 0).Name)}}

🎀 head

Returns the first n characters from a string.

{{"hello" | head 2}}

🎀 tail

Returns the last n characters from a string.

{{"hello" | tail 2}}

🎀 .Style

Applies a user-defined style (peep aerc-stylesets(7)) to a string 💅

{{.Style .Account "red"}}
{{.Style .ThreadPrefix "thread"}}{{.Subject}}

🎀 .StyleSwitch

Applies a user-defined style (again, aerc-stylesets(7)) to a string if it matches one of the associated regular expressions. If it doesn't match any of them, it just stays unstyled. no notes.

{{.StyleSwitch .Subject (case `^([[w-]+]s*)?[(RFC )?PATCH` "cyan")}}
{{.StyleSwitch (.From | names | join ", ") (case `Tim` "cyan") (case `Robin` "pink-blink") (default "blue")}}

🎀 .StyleMap

Applies user-defined styles (yep, aerc-stylesets(7)) to elements of a string list. Same logic as .StyleSwitch, but it works on a list of elements. There's also an extra exclude option so you can remove matching elements from the list 🦋

{{.StyleMap .Labels (exclude .Folder) (exclude `^spam$`) (case `^inbox$` "red") (case `^Archive/.*` "green") (default "blue") | join " "}}

🎀 version

Returns the version of aerc — very useful for things like X-Mailer, iykyk.

X-Mailer: aerc {{version}}

🎀 match

Checks if a string matches a regular expression. This one's intended for conditional control flow:

{{if match .Folder `.*/Archive-[0-9]+`}}{{humanReadable .Unread}}{{end}}

🎀 switch

Does switch/case/default control flows. The switch value gets compared against regular expressions. If none of the case/default arms match, you get an empty string back. that's it, that's the vibe.

{{switch .Folder (case `^INBOX$` "📥") (case `^Archive/.*` "🗃") (default "📁")}}

🎀 map

Transforms a string list into another one. Same logic as switch, but it works on a list of elements. And an extra exclude option is available to remove the matching elements from the list 💫

{{map .Labels (exclude .Folder) (exclude `^spam$`) (case `^inbox$` "📥") (case `^Archive/.*` "🗃") | join " "}}

💫 Function chaining 💫

okay so literally all of the template functions can be chained together if you need to. go off.

Example: automatic HTML parsing for text/html mime type messages 🎀

{{if eq .OriginalMIMEType "text/html"}}
{{exec `/usr/libexec/aerc/filters/html` .OriginalText | wrap 72 | quote}}
{{else}}
{{wrap 72 .OriginalText | trimSignature | quote}}
{{end}}

---

🔍 SEE ALSO 🔍

• aerc(1)
• aerc-config(5)

👑 AUTHORS 👑

Originally created by Drew DeVault and maintained by Robin Jarry, who is assisted by other open source contributors. For more info about aerc development, go look at https://sr.ht/~rjarry/aerc/ — the source of truth bestie 🫶

---

and that's the whole page!! this one's from the AERC-TEMPLATES(7) manual, dated 2026-09-07 — go forth and template the house down boots 💅✨🌸