Mail::...drList(3pm)

💖 Mail::SpamAssassin::SQLBasedAddrList 💖

okay bestie, so this is a page from the User Contributed Perl Documentation (section 3pm), and it's literally all about Mail::SpamAssassin::SQLBasedAddrList — SpamAssassin's SQL Based Auto Welcomelist. pull up a chair, grab a boba, we're doing this 🧋✨

---

✨ NAME ✨

Mail::SpamAssassin::SQLBasedAddrList — SpamAssassin SQL Based Auto Welcomelist. no cap, that's the whole name, that's the vibe 💅

---

🦋 SYNOPSIS 🦋

okay so you'd set it up kinda like this:

    my $factory = Mail::SpamAssassin::SQLBasedAddrList->new()
    $spamtest->set_persistent_addr_list_factory ($factory);
  ... call into SpamAssassin classes...

and then SpamAssassin itself will call in, like:

    my $addrlist = $factory->new_checker($spamtest);
    $entry = $addrlist->get_addr_entry ($addr, $origip);
  ...

see how it's giving delegation? the framework does the dialing, you just build the factory 🏭✨

---

🌸 DESCRIPTION 🌸

A SQL based persistent address list implementation. periodt.

go read "Mail::SpamAssassin::PersistentAddrList" if you want the full tea ☕ — that's where the more-information lives.

so the way this works: it uses DBI::DBD module access to your favorite database — and yes it's been tested with MySQL, SQLite and PostgreSQL 🔥 — to store user auto-welcomelists.

the default table structure looks like this, bestie, copy it if you need it:

CREATE TABLE awl (
  username varchar(100) NOT NULL default '',
  email varchar(255) NOT NULL default '',
  ip varchar(40) NOT NULL default '',
  msgcount int(11) NOT NULL default '0',
  totscore float NOT NULL default '0',
  signedby varchar(255) NOT NULL default '',
  last_hit timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (username,email,signedby,ip) ) TYPE=MyISAM;

ngl your table definition may change depending on which database driver you choose — that's not a bug, that's just how it is 🙈. and there's a config option to override the table name, so you're not locked in.

this module also introduces several new config variables, and here they are, in order, no skips:

• user_awl_dsn
• user_awl_sql_username
• user_awl_sql_password
• user_awl_sql_table
• user_awl_sql_override_username

see "Mail::SpamAssassin::Conf" for more information. iykyk 💜

---

🎀 new 🎀

public class (Mail::SpamAssassin::SQLBasedAddrList) new ()

Description: This method creates a new instance of the SQLBasedAddrList factory and calls the parent's (PersistentAddrList) new method. it's literally nepotism but make it architecture 🫶

---

🌈 new_checker 🌈

public instance (Mail::SpamAssassin::SQLBasedAddrList) new_checker (\% $main)

Description: This method is called to setup a new checker interface and return a blessed copy of itself. and here is where we set up the SQL database connection based on the config values. so like, this is the moment. the main character moment. the connection moment 🔥

---

👑 get_addr_entry 👑

public instance (\%) get_addr_entry (String $addr, String $signedby)

Description: This method takes a given $addr and splits it between the email address component and the ip component, then performs a lookup in the database.

if nothing is found in the database, then a blank entry hash is created and returned — otherwise, an entry containing the found information is returned. either way you get something back, she's reliable like that 💅

and here's the important bit: if a with_awl_signer configuration option is enabled, only addresses signed by the given signing identity are taken into account. or, if $signedby is undefined (or empty), only unsigned entries are considered. so pick a lane, bestie ✨

A key, "exists_p", is set to 1 if an entry already exists in the database, otherwise it is set to 0. very much a vibe check in boolean form.

---

🍓 add_score 🍓

public instance (\%) add_score (\% $entry, Integer $score)

Description: This method adds a given $score to a given $entry. If the entry was marked as not existing in the database then an entry will be inserted, otherwise a simple update will be performed. insert-or-update, we love a flexible queen 👑

NOTE: This code uses a self referential SQL call (ie set foo = foo + 1) which is supported by most modern database backends, but not everything calling itself a SQL database. so like. be careful. some of these "databases" are lying to you 😭💀

---

💜 remove_entry 💜

public instance () remove_entry (\% $entry)

Description: This method removes a given $entry from the database. and heads up: if the ip portion of the entry address is equal to "none", then remove any perl-IP entries for this address as well. it's giving thorough. it's giving cleanup. we stan 🌸

---

✨ finish ✨

public instance () finish ()

Description: This method provides the necessary cleanup for the address list. say goodbye properly, bestie, closure is important 🫶

---

🦋 _unpack_addr 🦋

private instance (String, String) _unpack_addr(string $addr)

Description: This method splits an autowelcomelist address into it's two components, email and ip address. it's a private method so don't @ her, she's internal 🌈

---

that's the whole page, no notes, ate and left no crumbs 👑💖

signing off with the boring-but-required bits: this was perl v5.40.1, dated 2026-07-23, and the page title was Mail::...drList(3pm). slay, bye bestie 💅✨🎀