MAILBOX-PREVIEW(1)

✨ NAME ✨

mailbox-preview — list new email messages in an IMAP or local mailbox

(yeah this is the General Commands Manual page for it, version 4.6.11, and we'll get to that at the end bestie 💖)

---

🦋 SYNOPSIS 🦋

mailbox-preview [[server][:mailbox]] [ --option ... ]
mailbox-preview mail_spool_file_name [ --option ... ]
mailbox-preview [[server][:mailbox]] --check oldsize [ --option ... ]
mailbox-preview mail_spool_file_name --check oldsize [ --option ... ]

---

💅 DESCRIPTION 💅

so mailbox-preview peeks at your IMAP mailbox (respectful little glance, no touching) and then hands things off to scan(1) to show you a summary — one line per new message. cute, right?

and it's not just IMAP! it also does local mailboxes, fr fr:

• Maildir directories
• MH folders
• mbox files
• MMDF files

you can run mailbox-preview solo on the command line, or let it be the back-end of a graphical, literate new-mail notification program like xlbiff(1). main character energy either way 👑

so, the first argument? it's the optional name of an IMAP server (default is imap), and you can optionally slap a colon and a mailbox name after it (default is inbox). you're gonna need that argument unless the default name imap happens to resolve on your network to your mail provider's IMAP server name. lowkey, the default mailbox name inbox will probably just work for you ✨

your ~/.netrc file gets consulted for the login and password for that IMAP server. the format of that file lives in the FILES section below, don't worry 🫶

now, plot twist: if the first argument is instead the name of a file under a top-level directory that exists, it gets treated as the name of a local mail drop, and that file is used instead of doing IMAP. no IMAP, no problem 🎀

and when you bring --check into the mix, the program conforms to the checkCommand protocol of xlbiff(1). the output is the new mailbox size — the thing you pass next time as the argument to --check. (note: the contents of the mailbox are not output. we're just doing numbers here bestie 💀) and the exit value of the program describes how the mailbox size has changed, as documented under the -checkCommand option in xlbiff(1). go read that if you need the deets, iykyk.

---

🌸 OPTIONS 🌸

• --check old_size — check for mailbox change instead of scanning. see the description above and also xlbiff(1) 💖
• --width N — width in characters to pass to scan; the default is $COLUMNS (pulled from the environment, periodt).
• --max-messages N — display only the last N new messages (default 20). set it to 0 to display all of them, no cap.
• --form file — format file for scan; see mh-format(5). default is xlbiff.form.
• --scanproc program — filename of the program to pipe the messages through; default is /usr/bin/mh/scan. if you set it explicitly to an empty string, the messages will be output raw (which is probably useful only for debugging 🙈).
• --quiet — do not output the messages. this option is probably useful only for debugging 🫠
• --client-preview — do not request a short message preview from the IMAP server, and instead create our own short form of the message. use this option if you don't like the preview the IMAP server generates. it has no effect unless the IMAP server advertises a preview capability 💅
• --imap-debug level — set the imaplib debug level. level 4 displays the IMAP protocol messages, and level 5 also displays IMAP literal strings. nerdy and iconic 🔥

---

🎀 FILES 🎀

• ~/.netrc — login information for your mail provider's IMAP server. if the IMAP server requires a password, supply it on a machine line matching the IMAP server name, for example:

machine server_name login account_name password your_pw

if login account_name is omitted, account_name defaults to your user name 💜

---

😭 BUG REPORTS 😭

when you're reporting interoperability problems with an IMAP server, please include the output of this:

mailbox-preview srvr --imap-debug=4 --quiet 2>&1 | grep -v " LOGIN "

(there's the grep hiding your LOGIN line, because we are not leaking credentials in a bug report, bestie. protecting the vibe 🛡️)

---

🌈 EXAMPLE 🌈

example command lines, serve:

mailbox-preview imap.example.com
mailbox-preview imap.example.com --check 12

---

👑 AUTHOR 👑

Stephen Gildea, November 2021 🫶

---

⭐ SEE ALSO ⭐

xlbiff(1), scan(1)

---

and that's the whole thing, no notes 💖 this was the 4.6.11 version, dated 2026-05-08 — slay, bye bestie 🎀🦋✨