1AERC-TEMPLATES(7) Miscellaneous Information Manual AERC-TEMPLATES(7)
2
6 aerc-templates - template file specification for aerc(1)
7
9 aerc uses the go text/template package for the template parsing. Refer
10 to the go text/template documentation for the general syntax. The tem‐
11 plate syntax described below can be used for message template files and
12 for dynamic formatting of some UI widgets.
13 Template files are composed of headers, followed by a newline, followed
15 by the body text.
16 Example:
18 X-Clacks-Overhead: GNU Terry Pratchett
20 Hello,
22 Greetings,
24 Chuck
25 If you have a template that doesn't add any header, it must be preceded
27 by a newline, to avoid parsing parts of the body as header text.
28 All headers defined in the template will have precedence over any head‐
30 ers that are initialized by aerc (e.g. Subject, To, From, Cc) when com‐
31 posing a new message, forwarding or replying.
32
34 The following data can be used in templates. Though they are not all
35 available always.
36 Addresses
38 An array of mail.Address. That can be used to add sender or recipi‐
39 ent names to the template.
40 • {{.From}}: List of senders.
42 • {{.Peer}}: List of senders or To recipients if the message is
43 from you.
44 • {{.To}}: List of To recipients. Not always Available.
45 • {{.ReplyTo}}: List of ReplyTo recipients. Not always Available.
46 • {{.Cc}}: List of Cc recipients. Not always Available.
47 • {{.Bcc}}: List of Cc recipients. Not always Available.
48 • {{.OriginalFrom}}: List of senders of the original message.
49 Available for quoted reply and forward.
50 Example:
53 Get the name of the first sender.
55 {{(index .From 0).Name}}
56 {{index (.From | names) 0}}
57 Get the email address of the first sender.
59 {{(index .From 0).Address}}
60 Date and Time
62 The date and time information is always available and can be easily
63 formatted.
64 • {{.Date}}: Date and time information when the compose window is
66 opened.
67 • {{.OriginalDate}}: Date and time when the original message of
68 received. Available for quoted reply and forward.
69 To format the date fields, dateFormat and .Local are provided. Re‐
72 fer to the TEMPLATE FUNCTIONS section for details.
73 Subject
75 The subject of the email (ThreadPrefix will be empty unless thread‐
76 ing is enabled).
77 {{.ThreadPrefix}}{{.Subject}}
79 The subject of the email stripped of any Re: and Fwd: prefixes.
81 {{.SubjectBase}}
83 Flags
85 List of message flags, not available when composing, replying nor
86 forwarding. This is a list of strings that may be converted to a
87 single string with join.
88 {{.Flags | join ""}}
90 Labels
92 Message labels (for example notmuch tags). Not available when com‐
93 posing, replying nor forwarding. This is a list of strings that may
94 be converted to a single string with join.
95 {{.Labels | join " "}}
97 Size
99 The size of the message in bytes. Not available when composing, re‐
100 plying nor forwarding. It can be formatted with humanReadable.
101 {{.Size | humanReadable}}
103 Any header value
105 Any header value of the email.
106 {{.Header "x-foo-bar"}}
108 Any header values of the original forwared or replied message:
110 {{.OriginalHeader "x-foo-bar"}}
112 MIME Type
114 MIME Type is available for quoted reply and forward.
115 • {{.OriginalMIMEType}}: MIME type info of quoted mail part. Usu‐
117 ally text/plain or text/html.
118 Original Message
121 When using quoted reply or forward, the original message is avail‐
122 able in a field called OriginalText.
123 {{.OriginalText}}
125 Account info
127 The current account name:
128 {{.Account}}
130 Currently selected mailbox folder:
132 {{.Folder}}
134 Current message counts for all folders:
136 {{.Recent}} {{.Unread}} {{.Exists}}
138 {{.RUE}}
139 IANA role of the mailbox, converted to lowercase. aerc uses one
141 custom role: 'query', which is given to mailboxes from a notmuch
142 query-map
143 {{if eq .Role "query"}}{{...}}{{else}}{{...}}{{end}}
144 Current message counts for specific folders:
146 {{.Recent "inbox"}}
148 {{.Unread "inbox" "aerc/pending"}}
149 {{.Exists "archive" "spam" "foo/baz" "foo/bar"}}
150 {{.RUE "inbox"}}
151 Status line
153 The following data will only be available in the status line tem‐
155 plates:
156 Connection state.
158 {{.Connected}}
160 {{.ConnectionInfo}}
161 General status information (e.g. filter, search) separated with
163 [statusline].separator.
164 {{.ContentInfo}}
166 Combination of {{.ConnectionInfo}} and {{.StatusInfo}} separated
168 with [statusline].separator.
169 {{.StatusInfo}}
171 General on/off information (e.g. passthrough, threading, sorting),
173 separated with [statusline].separator.
174 {{.TrayInfo}}
176 Currently pressed key sequence that does not match any key binding
178 and/or is incomplete.
179 {{.PendingKeys}}
181
183 Besides the standard functions described in go's text/template documen‐
184 tation, aerc provides the following additional functions:
185 wrap
187 Wrap the original text to the specified number of characters per
188 line.
189 {{wrap 72 .OriginalText}}
191 quote
193 Prepends each line with "> ".
194 {{quote .OriginalText}}
196 trimSignature
198 Removes the signature froma passed in mail. Quoted signatures are
199 kept as they are.
200 {{trimSignature .OriginalText}}
202 join
204 Join the provided list of strings with a separator:
205 {{.To | names | join ", "}}
207 names
209 Extracts the names part from a mail.Address list. If there is no
210 name available, the mbox (email address without @domain) is re‐
211 turned instead.
212 {{.To | names | join ", "}}
214 {{index (.To | names) 0}}
215 firstnames
217 Extracts the first names part from a mail.Address list. If there is
218 no name available, the short mbox (start of email address without
219 @domain) is returned instead.
220 {{.To | firstnames | join ", "}}
222 {{index (.To | firstnames) 0}}
223 initials
225 Extracts the initials from the names part from a mail.Address list.
226 If there is no name available, the first letter of the email ad‐
227 dress is returned instead.
228 {{.To | initials | join ", "}}
230 {{index (.To | initials) 0}}
231 emails
233 Extracts the addresses part from a mail.Address list.
234 {{.To | emails | join ", "}}
236 {{index (.To | emails) 0}}
237 mboxes
239 Extracts the mbox part from a mail.Address list (i.e. smith from
240 smith@example.com).
241 {{.To | mboxes | join ", "}}
243 {{index (.To | mboxes) 0}}
244 shortmboxes
246 Extracts the short mbox part from a mail.Address list (i.e. smith
247 from smith.and.wesson@example.com).
248 {{.To | shortmboxes | join ", "}}
250 {{index (.To | shortmboxes) 0}}
251 persons
253 Formats a list of mail.Address into a list of strings containing
254 the human readable form of RFC5322 (e.g. Firstname Lastname
255 <email@address.tld>).
256 {{.To | persons | join ", "}}
258 {{index (.To | persons) 0}}
259 exec
261 Execute external command, provide the second argument to its stdin.
262 {{exec `/usr/libexec/aerc/filters/html` .OriginalText}}
264 .Local
266 Convert the date to the local timezone as specified by the locale.
267 {{.Date.Local}}
269 dateFormat
271 Format date and time according to the format passed as the second
272 argument. The format must be specified according to go's time pack‐
273 age format.
274 {{dateFormat .Date "Mon Jan 2 15:04:05 -0700 MST 2006"}}
276 You can also use the .DateAutoFormat method to format the date ac‐
278 cording to *-time*format settings:
279 {{.DateAutoFormat .OriginalDate.Local}}
281 now
283 Return the current date as a golang time.Time object that can be
284 formated with dateFormat.
285 {{dateFormat now "Mon Jan 2 15:04:05 -0700 MST 2006"}}
287 humanReadable
289 Return the human readable form of an integer value.
290 {{humanReadable 3217653721}}
292 cwd
294 Return the current working directory with the user home dir re‐
295 placed by ~.
296 {{cwd}}
298 compactDir
300 Reduce a directory path into a compact form. The directory name
301 will be split with / and each part will be reduced to the first
302 letter in its name: INBOX/01_WORK/PROJECT will become I/W/PROJECT.
303 {{compactPath .Folder}}
305 .Style
307 Apply a user-defined style (see aerc-stylesets(7)) to a string.
308 {{.Style .Account "red"}}
310 {{.Style .ThreadPrefix "thread"}}{{.Subject}}
311 .StyleSwitch
313 Apply a user-defined style (see aerc-stylesets(7)) to a string if
314 it matches one of the associated regular expressions. If the string
315 does not match any of the expressions, leave it unstyled.
316 {{.StyleSwitch .Subject (`^([[w-]+]s*)?[(RFC )?PATCH` "cyan")}}
318 {{.StyleSwitch (.From | names | join ", ") (case `Tim` "cyan") (case `Robin` "pink-blink") (default "blue")}}
319 version
321 Returns the version of aerc, which can be useful for things like X-
322 Mailer.
323 X-Mailer: aerc {{version}}
325 match
327 Check if a string matches a regular expression. This is intended
328 for use in conditional control flow:
329 {{if match .Folder `.*/Archive-[0-9]+`}}{{humanReadable .Unread}}{{end}}
331 switch
333 Do swich/case/default control flows. The switch value is compared
334 with regular expressions. If none of the case/default arms match,
335 an empty string is returned.
336 {{switch .Folder (case `^INBOX$` "📥") (case `^Archive/.*` "🗃") (default "📁")}}
338 Function chaining
340 All of the template functions can be chained together if needed.
341 Example: Automatic HTML parsing for text/html mime type messages
343 {{if eq .OriginalMIMEType "text/html"}}
345 {{exec `/usr/libexec/aerc/filters/html` .OriginalText | wrap 72 | quote}}
346 {{else}}
347 {{wrap 72 .OriginalText | trimSignature | quote}}
348 {{end}}
349
351 aerc(1) aerc-config(5)
352
354 Originally created by Drew DeVault <sir@cmpwn.com> and maintained by
355 Robin Jarry <robin@jarry.cc> who is assisted by other open source con‐
356 tributors. For more information about aerc development, see
357 https://sr.ht/~rjarry/aerc/.
358 2023-07-16 AERC-TEMPLATES(7)