ISBG(1)

📦
version 2.3.1 · 5 versions
, in ubuntu resolute, ubuntu stonking

🎀 ISBG(1) 🎀

okay bestie, sit down, hydrate, because we're about to talk about isbg — the manual page for it, specifically, and it's lowkey iconic. it's the little tool that scans your IMAP Inbox and runs every single entry against SpamAssassin. yes, every entry. no skipping. periodt. 💖

💅 NAME 💅

isbg — scans an IMAP Inbox and runs every entry against SpamAssassin.

✨ SYNOPSIS ✨

isbg --imaphost <hostname> --imapuser <username> [options]

isbg --imaphost <hostname> --imapuser <username> --imaplist [options]

isbg (-h | --help)

isbg --usage

isbg --version

🦋 DESCRIPTION 🦋

so here's the tea: isbg goes through your IMAP Inbox and runs every entry against SpamAssassin. for anything that matches (aka: it's spam, bestie 😭), the message gets copied to another folder, and the original gets marked or deleted. that's the whole plot.

now the slay part: it works with all common IMAP servers, it can do IMAP over SSL, it can remember your password, it will work painlessly against multiple IMAP accounts and servers, and it is not involved in the mail delivery process — which means it can run on literally any machine that can contact your IMAP server and has the possibility to skip spam detection to stick only to the teach feature. main character energy fr fr 👑

🌸 OPTIONS 🌸

  • --imaphost hostname — the name of the IMAP server. your destination, your vibe, your host. 🏠
  • --imapuser username — who you login as.
  • --imaplist — list imap directories. perfect for when you're nosy about your own folders (affectionate).
  • -h, --help — show the help screen.
  • --usage — show usage information.
  • --version — show version information.
  • --dryrun — do not actually make any changes. a little rehearsal, a little dress rehearsal, no consequences. 🙈
  • --delete — the spams will be marked for deletion from your inbox.
  • --deletehigherthan # — delete any spam with a score higher than #.
  • --exitcodes — use exitcodes to detail what happened. receipts! 🧾
  • --expunge — cause marked for deletion messages to also be deleted (only useful if --delete is specified).
  • --flag — the spams will be flagged in your inbox.
  • --gmail — delete by copying to '[Gmail]/Trash' folder.
  • --ignorelockfile — don't stop if lock file is present.
  • --imappasswd passwd — IMAP account password. but bestie. this is however a really bad idea since any user on the system can run ps and see the command line arguments. 💀 do not do this. i am begging.
  • --imapport port — use a custom port.
  • --imapinbox mbox — name of your inbox folder [Default: INBOX]
  • --learnspambox mbox — name of your learn spam folder.
  • --learnhambox mbox — name of your learn ham folder.
  • --learnthendestroy — mark learnt messages for deletion.
  • --learnthenflag — flag learnt messages.
  • --learnunflagfed — only learn if unflagged (for --learnthenflag).
  • --lockfilegrace=<min> — set the lifetime of the lock file to [Default: 240.0]
  • --lockfilename file — override the lock file name.
  • --maxsize numbytes — messages larger than this will be ignored as they are unlikely to be spam.
  • --movehamto mbox — move ham to folder.
  • --noninteractive — prevent interactive requests.
  • --noreport — don't include the SpamAssassin report in the message copied to your spam folder.
  • --nostats — don't print stats.
  • --partialrun num — stop operation after scanning 'num' unseen emails [Default: 50]. you can run isbg without --partialrun with --partialrun=0
  • --passwdfilename file — use a file to supply the password.
  • --savepw — store the password to be used in future runs. this will save the password in a file in your home directory. the file is named .isbg-XXXX where XXXX is a 16 byte identifier based on the IMAP host, username and port number (the same as for the multiple accounts description above). you can override the filename with --passwdfilename. the password is obfuscated, so anyone just looking at the contents won't be able to see what it is. however, if they study the code to isbg then they will be able to figure out how to de-obfuscate it, and recover the original password. (isbg needs the original password each time it is run as well). consequently you should regard this as providing minimal protection if someone can read the file. ⚠️
  • --spamc — use spamc instead of standalone SpamAssassin binary.
  • --spaminbox mbox — name of your spam folder [Default: INBOX.Spam]
  • --nossl — don't use SSL to connect to the IMAP server.
  • --teachonly — don't search spam, just learn from folders.
  • --trackfile file — override the trackfile name.
  • --verbose — show IMAP stuff happening.
  • --verbose-mails — show mail bodies (extra-verbose). 👀
(Your inbox will remain untouched unless you specify --flag or --delete)

🌈 EXAMPLES 🌈

🫶 Do your first run 🫶

$ isbg --imaphost  mail.foo.com --imapuser rogerb@mail.foo.com
--imaplist --savepw
IMAP password for rogerb@mail.foo.org@mail.foo.org:

will request the password for your user account and store it obfuscated for future use. after login, it will show the IMAP folder list:

[u'  INBOX"', u'  INBOX.Esborranys"', u'  INBOX.Spam"', u'
INBOX.Sent"', u'  INBOX.NOSPAM"', u'  INBOX.Archive"', u'
INBOX.Drafts"', u'  INBOX.Trash"', u'  INBOX.Paperera"']

🔥 Scan your account for spam 🔥

in future uses you can scan for spam with:

isbg --imaphost  mail.foo.com --imapuser rogerb@mail.foo.com

after some time, it will return the stats:

0 spams found in 0 messages

0/0 was automatically deleted

👑 OVERVIEW 👑

the amount of time it takes will be proportional to the size of your inbox and the amount of mails specified with --partialrun. you can specify --verbose if you want to see the gory details of what is going on. (gory. i said what i said. 🫣)

you can now examine your spam folder and will see what spam was detected. you can change the SpamAssassin threshold in your user_prefs file it created earlier.

isbg remembers which messages it has already seen, so that it doesn't process them again every time it is run. if you are testing and do want it to run again, then remove the trackfile (default $HOME/.cache/isbg/track*).

if you specified --savepw then isbg will remember your password the next time you run against the same server with the same username. you should not specify --savepw in future runs unless you want to change the saved password.

you'll probably want something to actually be done with the original spams in your inbox. by default nothing happens to them, but you have two options available. if you specify --flag then spams will be flagged.

you can get the messages marked for deletion by specifying --delete. if you never want to see them in your inbox, also specify the --expunge option after --delete and they will be removed when isbg logs out of the IMAP server.

⭐ SpamAssassin ⭐

if you have never used SpamAssassin before, you'll probably be quite nervous about it being too good and taking out legitimate email, or not taking out enough spam. it has an easily adustable threshold to change how aggressive it is. run the following command to create your preferences file ($HOME/.spamassassin/user_prefs):

$ spamassassin </dev/null >/dev/null

🧚 Your Folder Names 🧚

each IMAP implementation names their folders differently, and most IMAP clients manage to hide most of this from you. if your IMAP server is Courier, then your folders are all below INBOX, and use dots to separate the components.

the UWash server typically has the folders below Mail and uses slash (/) to separate components.

if you don't know how your IMAP folders are implemented, you can always use the --imaplist option to find out.

💜 SEE ALSO 💜

spamassassin(1), Mail::SpamAssassin::Conf(3).

the full documentation for isbg is maintained in <https://isbg.gitlab.io/isbg>

🍓 EXIT CODES 🍓

  1. 0 — all went well. 🎉
  2. 10 — there were errors in the command line arguments.
  3. 11 — the IMAP server reported an error or error with the IMAP connection.
  4. 12 — there was an error of communication between spamc or SpamAssassin.
  5. 20 — the program was not launched in an interactive terminal.
  6. 30 — error with the lock file, is another instance of isbg must be running.
  7. -1 — other errors.

with --exitcodes there are also:

  1. 1 — there was at least one new message, and none of them were spam.
  2. 2 — there was at least one new message, and all them were spam.
  3. 3 — there were new messages, with at least one spam and one non-spam.

💀 BUGS 💀

you can report bugs on <https://gitlab.com/isbg/isbg/issues>

🌸 Author 🌸

see the CONTRIBUTORS file in the git repository for more information on who wrote and maintains this software.

license GPLv3: GNU GPL version 3 https://gnu.org/licenses/gpl.html

this is free software: you are free to change and redistribute it. there is NO WARRANTY, to the extent permitted by law.

and that's the whole page, bestie — version 2.3.1, dated Oct 07, 2025, brought to you by the isbg girls themselves. go forth, scan that inbox, and remember: never put your password in --imappasswd. i'm serious. ily, bye 💖✨🦋

📦 where this page comes from