asmail(1)

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

💌 asmail(1) 💌

general commands manual energy, but make it cute. this is the AfterStep e-mail monitor and she SERVES. 💅

✨ NAME ✨

asmail — the AfterStep e-mail monitor 🌸

🦋 SYNOPSIS 🦋

asmail [-h] [-V] [-v] [-nox]
        [-insecure]
        [-noconfig]
        [-f resource file]
        [-geometry X geometry specification]
        [-iconic]
        [-withdrawn]

🎀 DESCRIPTION 🎀

okay so asmail is a X11 application that acts as an e-mail monitor for a whole bunch of different format mailboxes. bestie, it gives you that distinctive Afterstep window manager look and feel, and it comes with multiple options so you can customize literally everything. main character customization energy, no cap. 💖

basically, the tool shows you the following:

  • the background image changes depending on whether there is e-mail in your mailboxes or not. custom images can be loaded and used for animation sequences. it's giving ✨*animated*✨
  • the tool will display the number of e-mails waiting in each mailbox and/or the total numbers for all mailboxes together
  • for each mailbox there's a status indicator that shows whether the update is running at this very moment, and it also tells you if there's an error. the same indicator shows up next to the summary line too 🫶

💫 the status indicators 💫

the following indicators are used for the status display:

  • R — an update on the mailbox is running right now. for small mailboxes with fast access you may never actually see it — it's so fast it just disappears, gone, evaporated, iconic behavior honestly 😭
  • L — an error occurred that has to do with the login procedure. most probably your name/password combination was not accepted by the server. rude of them, but okay 💀
  • C — a connection problem. asmail could not connect to the server for some reason. the reasons may be many — server down, network unreachable, service not available, and so on.
  • T — a time-out occurred while asmail was waiting for the server's answer. if you have a frequent problem with this but the server seems to be available in other applications, try increasing the "timeout" setting for the mailbox.
  • F — this is an indicator of a general error condition. something is wrong, maybe the configuration is not correct, or the mailbox is not readable. check the output of asmail by running from the terminal — this should give you an idea of what is wrong. detective mode activated 🔍

so the resource files may be specified with a command line option. the logic of asmail is simple: first it parses the resource file that you specified on the command line. if you do not specify the resource file on the command line, asmail will look in the default location (~/.asmailrc). if it exists, asmail will parse that one. if no configuration file was given on the command line and there is no configuration file in the default location, asmail will attempt to monitor the mailbox specified by the $MAILBOX environment variable. 🐚

🕵️ how asmail distinguishes between old and new mail 👑

the UNIX mailbox format does not contain any indication on the outside. the mailbox must be parsed to check if some e-mail is new. parsing the mailbox is an expensive operation, especially if the mailbox is large. 😮‍💨 asmail checks the mailbox file modification time with the stat(2) system call. when the file modification time changes, the mailbox is parsed. the lines "From " are counted and taken to be the number of e-mails in the box. after each "From " line, asmail looks for the "Status:" header. this header contains flags for when the message was seen and read. messages without this header line (or with an empty header) are considered to be new.

the Maildir format is very well-behaved. 💅 there are separate folders for old and new e-mails, so we just count the number of files in "cur" and "new" subdirectories. the "tmp" subdirectory is ignored since this is the temporary storage and is not supposed to be taken into account. she minds her business.

the mH format is somewhere between Maildir and the UNIX mailbox formats. it is used by mh, nmh, balsa and xfmail among others. the messages are all stored in separate files, one message per file, and all of the messages in a single directory. each message file is named with an increasing number, so the first message received in the mailbox is stored as "1" and the 39th message is stored as "39". there are two ways that the status of the messages are kept track of. traditionally, the mH tools used a file called .mh_sequences, which is stored in the mH directory, to keep track of status. this file contains a series of sequences, each one starting with a token followed by a colon and then by a series of message numbers, representing the messages that belong to that sequence. it looks something like this:

unseen: 1 2 3-5 19 25-31

although there are many sequences, some standard and some user-defined, if the use-mh-sequences configuration option is set to "yes" for that mailbox, then asmail will parse this file, looking for the "unseen" sequence to determine how many messages are new. some mail clients don't use the .mh_sequences file and instead treat the files in the mH mailbox just like a collection of separate messages from a UNIX mailbox. so, if the use-mh-sequences configuration option is set to "no", or is not specified at all, then asmail will parse all of the files in the mH directory, searching for the Status header. therefore, this mode is definitely the most "processor hungry" format from the point of view of asmail. 🔥 mh, nmh, and newer versions of balsa utilize the .mh_sequences file, while older versions of balsa and xfmail do not. it is not known how other clients treat mH mailboxes.

the POP3 protocol does not support the notion of new or old e-mail. your e-mail client keeps a list of messages and can tell whether you read one of them or not. since asmail does not keep a list of messages there is no way to tell a new message from the old one. ok, so what we do is assume that all e-mail is new at start-up. this is a logical assumption for most of the people because they store the e-mail locally and remove it from the server. others are out of luck. 😭 now, when the number of messages decreases, we assume that you read all your e-mail and deleted some, so all messages are marked as old. when the number of messages increases, we assume that the new mail arrived and we report the additional mail as new.

the IMAP protocol is very well behaved, it reports the number of new e-mails and the number of old e-mails if you ask politely :) since we open the mailbox in read-only mode, we do not cause any status changes for the mailbox on the server. the IMAP server will store a special e-mail into your mailbox if it is in UNIX format. this e-mail allows the server to keep track of the new and old e-mails. the server will not report this e-mail into the number of e-mails, so that if you check your UNIX mailbox directly the number of messages will be one more. ⭐

🌈 CONFIGURATION OPTIONS 🌈

  • -h — prints a short description and usage message. your lil help menu bestie.
  • -V — Version control. prints out the version of the program.
  • -v — Verbose mode. in this mode, asmail will print the information about mailboxes onto the controlling terminal. the information includes: number of updates requested, per mailbox: thread PID, [R]unning or idle, any errors are signalled with letters (see above) and the number of e-mails in the format new/old. this mode is useful for debugging or could be used to monitor mailboxes without the X Windows interface (give the -nox option). 💅
  • -f resource file — specifies the alternative location for the resource file. the default location is ~/.asmailrc. if the alternative file is specified, the default location is ignored.
  • -geometry X geometry specification — specifies the size and position of the application on the screen in the standard X11 format (see XParseGeometry (3x) for details):
[=][<width>{xX}<height>][{+-}<xoffset>{+-}<yoffset>]
  • -noconfig — forces asmail to ignore the resource file even if one is present. asmail will run with all default settings and check the Unix mailbox specified by the $MAIL environment variable. 🙈
  • -nox — starts the asmail application in the terminal-only mode. the X Windows interface is not started. the configuration file is still parsed as usual though.
this option implies the -v option. 👀
  • -insecure — usually, asmail will check that the resource file has the 600 mode, that is there are no access rights for "group" and "others". if such access rights are granted, asmail will complain and exit. this is done to make you remember the passwords you put into the resource file. if there are no passwords stored in the file (e.g. you are using UNIX mailbox on the local machine) the check is not applied.
this option forces asmail to continue operation even if the resource file has insecure permissions and passwords are stored in that file. 🚨 bestie please be careful with this one, fr fr.
  • -iconic — this option will cause asmail to start up as an icon rather than as a normal window. the application can still be de-iconized and iconized as usual. tiny mode. smol. 🎀
  • -withdrawn — this option will cause asmail to start up in a so-called "withdrawn" mode. this mode is used by WindowMaker window manager to dock the application into their version of the Wharf.

🧚 RESOURCE FILE SYNTAX 🧚

the syntax of the resource file is described in a separate man page under asmailrc (5). go read her, she's got the lore. 💜

🌸 INVOCATION 🌸

asmail can be called in different ways. the most common invocation is the command line:

user@host[1]% asmail &

another way to call asmail is from the window manager:

*Wharf "asmail" nil Swallow "asmail" /usr/local/bin/asmail &

this line, when placed in the wharf file in the users Afterstep configuration directory, will cause asmail to become a button on the Wharf (1) button bar under the afterstep (1) window manager. 👑

💀 BUGS 💀

okay so first of all, the original author would like you to know, and I quote: "My programs do not have bugs, they just develop random features ;-)" — and honestly? iconic. no notes. slay 💅

But bestie, real talk, there are some limitations and we're gonna go through every single one because I would never gatekeep 🫶

  • All the strings — like color names, file names, and literally every other string — are capped at 256 characters (terminating zero included, so technically 255 + the null). If you write a name in the config file that's way too long, the program will complain about it. it's giving boundaries ✨
  • The number of mailboxes is not limited by the space on the icon, but the stats will get chopped (aka not shown at all 😭) if you have too many and they don't fit inside the icon. So if you're a mailbox collector with a million accounts, pick up a tall icon if you want to actually see info on each of them. Why? Because they're shown from the top down and there is genuinely no way to change this. periodt.
  • The mailbox info will not show up when you use "shaped" windows with transparency if it gets printed in the transparent area. so basically it's there but you can't see it, which is the most ghosting behavior ever 🙈
  • ⚠️ asmail may interfere with your mail client program when you use the POP3 server. There is no way to login to the POP3 server twice (from the mail client and from asmail), so there's an inherent race condition between the two. Whoever tries to log in second will fail. The good news: asmail logs out immediately after checking, so your mail client has a much higher chance of precluding asmail from logging in than the other way around. still messy tho 💀
  • If the program is not satisfied with the specification of one of the mailboxes, it will print an error message, set the status for that mailbox to F (Failed), and exit the thread — and by "the thread" I mean only the thread responsible for handling that particular mailbox, not the whole thing. Other mailboxes will be checked normally, like nothing happened. So if something's acting up, check the standard output of the tool to see what the problem is 🔍

📁 FILES 📁

  • ~/.asmailrc

that's it. that's the file. your whole vibe lives in there 🎀

👀 SEE ALSO 👀

go read them, iykyk 💜

©️ COPYRIGHTS ©️

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

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

(keeping that original spelling of "informations" because I respect the source, no cap ✨)

👑 AUTHORS 👑

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

See the README file for credits. 🫶

and that's the whole page bestie!! this one came from the 3rd Berkeley Distribution, dated 09 Apr 2007, and it's the manual page for asmail(1) 💖 go forth and check your mail, you absolute main character 🌈⭐

📦 where this page comes from