NAME
MySpam - Database operations for the MySpam application
SYNOPSIS
use MySpam;
my $m = MySpam->new;
$m->deploy;
$m->quarantine($recipient, $text);
$m->get_quarantined_mails($address);
$m->release($address, $id);
$m->add_to_whitelist($address, $sender);
$m->remove_from_whitelist($address, $sender);
# and other methods as below ...DESCRIPTION
MySpam is the database interface for the myspam application. The API enables the programmer to quarantine mails, retrieve them, set user whitelists, subscribe emails, etc.
The SQL used is fairly standard, known to work on at least SQLite and MySQL databases.
METHODS
new($file)
Create a new MySpam object. Takes an optional $file parameter to specify a config file location. If $file is not given the default /etc/myspam/myspam.conf is used. This method connects to the database as defined in the config file. Returns undef upon failure.
db
Return the underlying database connection (an SQL::DB object)
log($msg)
Write to the syslog with level 'info'.
error($msg)
Write to the syslog with level 'error'.
deploy
Create the needed tables in the database.
quarantine_file($file)
Save the file $file containing an email to the database. Returns true if successful, undefined otherwise. Expects the filename to be <epoch>_.* where <epoch> is the number of seconds since 1 January 1970. (The same format that sa-exim uses).
quarantine($epoch, $text)
Save the email contained in $text to the database with an epoch of $epoch. Returns true if successful, undefined otherwise.
get_quarantined_mails($address)
Returns the list of recipient objects that have the email address $address. See DATABASE SCHEMA below for the methods of the recipient objects.
raw($email, $id)
Return a tuple of ($recipient, $raw_text) for mail identified by ($id,$email). See DATABASE SCHEMA below for the methods of the $recipient object.
release($email, $id)
Forwards the mail identified by ($email,$id) to address $email. Returns the matching Recipient object.
remove($email, $id)
Removes the mail identified by $email,$id from the database. Returns true if the mail was deleted or did not exist, false otherwise.
sendmail($to, $text)
Internal method. Calls /usr/sbin/sendmail to deliver $text to $to.
add_to_whitelist($recipient, $sender)
Adds email address $sender to the whitelist for $recipient (where $recipient is an email address). Be aware that the arguments here are in the reverse order to what you would expect.
remove_from_whitelist($recipient, $sender)
Removes email address $sender from the whitelist of $recipient (where $recipient is an email address). Be aware that the arguments here are in the reverse order to what you would expect.
get_whitelist($recipient)
Returns the list of Whitelist objects for address $recipient. See DATABASE SCHEMA below for the methods of the returned objects.
get_whitelist_all
Returns all Whitelist objects. See DATABASE SCHEMA below for the methods of the returned objects.
generate_whitelist_dbm($file)
Creates a Berkeley DBM file with a list of <sender> <recipient> pairs separated by a '|' as the key values. If $file is not given then the the 'whitelist' configuration item is used. If neither exist/defined then this method croaks.
subscribe($email, $days)
Subscribes $email to the newsletter, to be received every $days days. Automatically unsubscribes from all other lists if subscribed elsewhere.
get_subscriber($email)
Return the Subscriber object (if it exists) for $email. See DATABASE SCHEMA below for the methods of the returned objects.
subscriber_sent($subscriber)
Updates the time sent value to the current time for subscriber $subscriber.
subscriber_newsletter_list
Returns the list of subscriber objects that are due for a newsletter as of the current time.
unsubscribe($email)
Unsubscribes $email from all subscription lists.
expire($age)
Deletes all quarantined objects that are older than $age. Returns a tuple of ($number_messages_deleted, $number_recipients_deleted). If the optional $age is not specified then the 'expire' configuration option is used instead.
DATABASE SCHEMA
CREATE TABLE messages (
id INTEGER NOT NULL,
epoch INTEGER NOT NULL,
sa_score FLOAT NOT NULL,
ip VARCHAR(32) NOT NULL,
mx_host VARCHAR(255) NOT NULL,
raw MEDIUMBLOB NOT NULL,
PRIMARY KEY(id)
);
CREATE INDEX messages_epoch ON messages (epoch);
CREATE TABLE recipients (
id INTEGER NOT NULL,
epoch INTEGER NOT NULL,
sender VARCHAR(255) NOT NULL,
email VARCHAR(255) NOT NULL,
h_from VARCHAR(255) NOT NULL,
h_subject VARCHAR(1024) NOT NULL,
sa_score FLOAT NOT NULL,
released INTEGER NOT NULL DEFAULT 0,
message INTEGER NOT NULL REFERENCES messages(id),
PRIMARY KEY(id),
UNIQUE (email, message)
);
CREATE INDEX recipients_email ON recipients (email);
CREATE INDEX recipients_message ON recipients (message);
CREATE TABLE whitelist (
epoch INTEGER NOT NULL,
sender VARCHAR(255) NOT NULL,
recipient VARCHAR(255) NOT NULL,
UNIQUE (sender, recipient)
);
CREATE INDEX whitelist_recipient ON whitelist (recipient);
CREATE INDEX whitelist_sender_recipient ON whitelist (sender,recipient);
CREATE TABLE subscribers (
subscriber VARCHAR(255) NOT NULL,
period INTEGER NOT NULL DEFAULT 1,
last_sent INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY(subscriber)
);
CREATE TABLE sqldb (
name VARCHAR(32) NOT NULL UNIQUE,
val INTEGER NOT NULL
);FILES
/etc/myspam/myspam.conf - database connection information
/var/log/mail.* - syslog(8) reporting of success or failure
SEE ALSO
myspam, MySpam::Email, SQL::DB
AUTHOR
Mark Lawrence <nomad@null.net>
COPYRIGHT AND LICENSE
Copyright 2006-2009 Mark Lawrence <nomad@null.net>
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.