asmailrc(5)

📦 version 2.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 asmailrc(5) 💖

okay bestie, gather round, because we're about to read asmailrc(5) — the resource file for asmail(1). yes it's a file formats manual page. yes it's long. no we are not skimming. 💅

✨ NAME ✨

asmailrc — the asmail resource file. that's it. that's the name. iconic.

✨ SYNOPSIS ✨

$HOME/.asmailrc

✨ DESCRIPTION ✨

so asmailrc is a resource file and it describes the configuration of the asmail(1) program. that's literally its whole job. it holds the settings, it tells asmail how to act, and asmail listens. main character energy fr. 👑

🌸 RESOURCE FILE SYNTAX 🌸

the syntax is all about grouping relevant options with {} (curly braces, you know the ones). the keyword sitting right before the opening brace tells asmail what that section is about. and here's the tea: the keywords in one section might be invalid or might have different semantics in another section. so don't just copy-paste a keyword into a random block and expect it to behave. 🙈

all keywords are case-insensitive, so "mailbox" and "Mailbox" are giving the exact same thing, no difference, no drama. BUT — and this is important — the values you give for file names, user names, and so on are case-sensitive, as is usual on Unix systems. okay? okay. 💖

comments start with # (hash sign) and run until the end of the line. comments and blank lines are just ignored, they're not part of the vibe check.

there are two main sections within the resource file. each of them may be completely omitted, and other sections and settings may be omitted too. asmail will try to use default values for everything you do not specify. it's very forgiving like that. 🫶

the later values overwrite earlier values. it is perfectly acceptable to specify any option twice and the last value will be used. one exception from this is the animate{} section, where pixmap files are added to the list by multiple occurences of the keywords. so like, that one stacks instead of replacing. noted. 📝

section name must be followed by { (opening brace) on the same line. the end of a section is signalled by } (closing brace) alone on a line. do not fight this, it's just how it is.

  • x11 — the top-level section describing the GUI settings.
  • mailbox — the top-level section describing the mailboxes to be monitored.
  • stat — the section may appear within the x11{} section. this section describes what statistics should be shown on the screen.
  • animate — the section may appear within the x11{} section. this section describes the pixmaps that will be used instead of the default ones and the settings for the animation.

🌈 x11 section 🌈

the x11 section specifies how the application looks on the screen. there may be multiple x11{} sections — the settings from all of them are merged, and later settings overwrite earlier settings. so you can absolutely stack them and let the last one win. slay.

  • beep [yes|no] — when beep is on, the tool will signal arrival of new e-mail by the system beep via the system speaker. 🔔 Default is yes.
  • shape [yes|no] — specifies whether the Shape extensions of X11 will be used for drawing the pixmaps that are specified by frame, nomail, old and new keywords in the settings file. when the Shape extensions are used, the tool will use the transparency settings of the pixmaps. that is, when a pixmap contains transparent pixels, those pixels will become actually transparent on the screen. with the Shape extensions disabled, the transparent pixels will show up filled with the background color.
ngl the Shape extension is rather expensive on the CPU power and may slow down things a lot on a slow machine. consider yourself warned bestie 💀

Default is no.

  • on_mouse_left comand & — the command will be executed when the application window is clicked with the left mouse button. Default is none.
  • on_mouse_middle comand & — same as on_mouse_left for the middle mouse button.
  • on_mouse_right comand & — same as on_mouse_left for the right mouse button.
  • on_new_mail command & — the command will be executed once for each mailbox when the e-mail arrives to that mailbox. Default is none.

🎀 mailbox section 🎀

the resource file should contain as many mailbox{} sections as the number of mailboxes you want to monitor. each section will create a separate monitor for the given mailbox. one section, one monitor, that's the deal. 💖

  • type [ mbox | maildir | mh | pop3 | imap ] — the type of the mailbox. mbox is the standard UNIX mailbox file. maildir is the newer Maildir format. mh is the mH mail directory format. pop3 is for the mailboxes on POP3 servers. imap is a mailbox on the IMAP server. depending on the type of the mailbox, some settings may take effect while others will be silently ignored. so if a setting is doing nothing, this is probably why. 🙈

the following keywords are useful for the mbox:

file update unread-is-new

the following keywords are useful for the maildir:

file update

the following keywords are useful for the mh:

file update unread-is-new use-mh-sequences

the following keywords are useful for the pop3:

update auth server user password timeout

the following keywords are useful for the imap:

update server user password mailbox ssl trustedCaDir timeout
persistent
  • file file-name — for mbox, mh and maildir, specifies the location of the mailbox in the filesystem. Default: none.
note: if no mailbox section is present in the configuration file or no configuration file is found, the value of the environment variable $MAIL will be used as the location of the UNIX mailbox format mail file.
  • update period — specifies the period between two updates of this mailbox. the mailbox will be updated period seconds after the previous update is finished. ⏰ Default: 10.
  • unread-is-new [ yes | no ] — for mbox and mh, specifies whether the messages which are flagged as unread are counted as new messages. Default: no.
  • use-mh-sequences [ yes | no ] — for mh, specifies whether asmail should parse the .mh_sequences file in this mH mail directory to count new messages. if this option is set to "no", then asmail will parse every message in the mH directory searching for "Status" headers. Default: no.
  • auth plain md5 — specifies the type of authentication allowed for the POP3 service. plain stands for the cleartext password authentication, md5 stands for the APOP authentication using MD5 hashes. you can specify either of them or both. if both are allowed and the server supports APOP, first APOP will be tried. Default: plain md5.
  • server server-name — the server name to connect to. Default: none.
  • user user-name — your user name on the server. Default: none.
  • password your-password — your password on the server. Default: none.
  • mailbox mailbox-name — your mailbox on the server. this is only useful with IMAP servers, you can specify an alternative to the standard "INBOX" value. Default: INBOX for IMAP, none for the rest.
  • timeout server-timeout — the connection to the server will time out after server-timeout seconds waiting for the answer. Default: 60.
  • ssl [ yes | no ] — use an encrypted connection to the IMAP server. 🔒 Default: no.
  • trustedCaDir directory — a directory that contains trusted certificate authorities. this is used to verify a server's certificate when negotiating an encrypted connection. Default: none.
  • persistent [ yes | no ] — the connection to the server can be either opened once and kept open, or the connection can be opened and closed every time we need to check for the e-mail status, i.e. every update period seconds. if you do not want the connection set-up and login procedure to execute every time, set this to yes. Default: no.

🦋 stat section 🦋

this section relates to the representation on the screen of mailbox status and counters. there are the following elements in this representation:

  • mailbox state — a letter R appears whenever the mailbox is being updated.
  • error state — a letter appears that shows the error state of the mailbox. the letters may be folowing:
    • L — login procedure failed
    • T — timeout while waiting for server response
    • C — connection problem
    • F — general fault indication

when an error is indicated, asmail prints a descriptive message on the standard output.

  • number of messages — the number of messages is represented by two numbers, for the number of new messages and the total number of messages.

the statistics may be displayed for each of the mailboxes separately as well as for the total of all mailboxes. when the total is displayed, the indicators of the mailbox state and the error state will report if any of mailboxes are updated or have errors.

  • each [ yes | no ] — whether the tool should display a line of statistics for each of the mailboxes separately. Default: no.
  • total [ yes | no ] — whether the tool should display the summary line for the total number of messages in all mailboxes. Default: yes.
  • status [ yes | no ] — whether the status indicator should preceed every line describing the number of messages in a mailbox and the total. Default: yes.
  • old [ yes | no ] — whether the status indicator should display the number of old (read) messages in the mailbox. Default: yes.
  • new [ yes | no ] — whether the status indicator should display the number of new (unread) messages in the mailbox. Default: yes.
  • delimiter characters — the characters are used to separate the number of new messages from the number of old messages in the display. Default: "/".
  • x pixels — start the status indicator at pixels offset horizontally from the top left corner. Default: 0.
  • y pixels — start the status indicator at pixels offset vertically from the top left corner. Default: 52.
  • font font-specification — use the font-specification for the status indicator. Default: -*-*-medium-r-normal--10-*-*-*-*-*-*-*.
  • color name — use the specified color for the status indicator. the color may be a single word or multiple words surrounded by quotes. Default: black.

🦋 animate section 🦋

okay so this section is literally the glow-up zone for your applet. You drop a bunch of XPM files in here and asmail cycles through them like it's running a tiny slideshow. There are three states: nomail, old, new. For each state you can add as many XPM files as you want. If there's only one file, asmail won't really cycle through it — it'll just display once, which saves system resources. periodt.

  • refresh refresh-rate — the supplied XPM files get cycled through every refresh-rate number of 1/100th of a second. Default: 10. 💅
  • nomail xpm-file — add this xpm-file to the animation of display to represent the state of an empty mailbox. 💌
  • old xpm-file — add this xpm-file to the animation of display to represent the state of a mailbox with only read mail. 📭
  • new xpm-file — add this xpm-file to the animation of display to represent the state of a mailbox when there is new e-mail in it. 📬
  • frame xpm-file — use this xpm-file as the background image. The background image may use transparency. You can specify more than one, but only the first one will be used. You can also specify the keyword none instead of the name of the file to be used for the frame. The result will be no frame at all around the applet window. iconic. ✨

🌈 EXAMPLE 🌈

here's the whole vibe in one config. Copy it, remix it, make it yours bestie:

        x11 {
           beep no
           on_mouse_left aterm -e bash -c pine &
           on_new_mail cat /usr/local/share/asmail/sounds/drip.au > /dev/audio
       &
           shape yes
           stat {
             each yes
             total yes
             delimiter " "
             x 5
             y 2
             font -*-helvetica-bold-r-*-*-10-*-*-*-*-*-*-*
             color black
           }
           animate {
             refresh 10
             nomail /usr/local/share/asmail/pixmaps/e-no.xpm
             old /usr/local/share/asmail/pixmaps/e0.xpm
             new /usr/local/share/asmail/pixmaps/e1.xpm
             new /usr/local/share/asmail/pixmaps/e2.xpm
             new /usr/local/share/asmail/pixmaps/e3.xpm
             new /usr/local/share/asmail/pixmaps/e4.xpm
             new /usr/local/share/asmail/pixmaps/e5.xpm
             new /usr/local/share/asmail/pixmaps/e6.xpm
             new /usr/local/share/asmail/pixmaps/e7.xpm
             new /usr/local/share/asmail/pixmaps/e8.xpm
             new /usr/local/share/asmail/pixmaps/e9.xpm
             new /usr/local/share/asmail/pixmaps/e10.xpm
             new /usr/local/share/asmail/pixmaps/e11.xpm
             new /usr/local/share/asmail/pixmaps/e12.xpm
             new /usr/local/share/asmail/pixmaps/e13.xpm
             new /usr/local/share/asmail/pixmaps/e14.xpm
             new /usr/local/share/asmail/pixmaps/e15.xpm
             new /usr/local/share/asmail/pixmaps/e16.xpm
             new /usr/local/share/asmail/pixmaps/e17.xpm
             new /usr/local/share/asmail/pixmaps/e18.xpm
             new /usr/local/share/asmail/pixmaps/e19.xpm
             new /usr/local/share/asmail/pixmaps/e20.xpm
             new /usr/local/share/asmail/pixmaps/e21.xpm
             new /usr/local/share/asmail/pixmaps/e22.xpm
             new /usr/local/share/asmail/pixmaps/e23.xpm
             new /usr/local/share/asmail/pixmaps/e24.xpm
             new /usr/local/share/asmail/pixmaps/e25.xpm
             new /usr/local/share/asmail/pixmaps/e26.xpm
             new /usr/local/share/asmail/pixmaps/e27.xpm
             new /usr/local/share/asmail/pixmaps/e28.xpm
             new /usr/local/share/asmail/pixmaps/e29.xpm
             new /usr/local/share/asmail/pixmaps/e30.xpm
           }
        }

        mailbox {
           type mbox
           file /var/spool/mail/albert
           update 5
           unread-is-new no
        }

        mailbox {
           type maildir
           file /home/albert/MailDir
           update 5
        }

        mailbox {
           type mh
           file /home/albert/mhmail
           update 5
           unread-is-new yes
           use-mh-sequences yes
        }

        mailbox {
           type pop3
           auth plain md5
           server example.com
           user yourname
           password yourpassword
           update 120
           timeout 30
        }

        mailbox {
           type imap
           server example.org
           user yourname
           password yourpassword
           update 60
           timeout 30
           ssl yes
           trustedCaDir /etc/openssl/certs/myCa/
        }

🎀 FILES 🎀

  • ~/.asmailrc

👑 SEE ALSO 👑

📜 COPYRIGHTS 📜

Copyright (c) 2002-2007 Albert Dorofeev <albert@tigr.net>

Distributed under GNU General Public License v2 ; see LICENSE file for more informations.

💖 AUTHORS 💖

Albert "Tigr" Dorofeev <albert@tigr.net>

See the README file for credits.

okay bestie that's the whole page 💅 this one came from the 3rd Berkeley Distribution, dated 09 Apr 2007, and it's the asmailrc(5) manual. slay, go make your mailbox cute 💖🦋✨

📦 where this page comes from