--- trunk/Nos.pm 2005/07/08 17:00:20 67 +++ trunk/Nos.pm 2006/09/21 10:49:00 87 @@ -16,7 +16,7 @@ our @EXPORT = qw( ); -our $VERSION = '0.6'; +our $VERSION = '0.8'; use Class::DBI::Loader; use Email::Valid; @@ -27,6 +27,7 @@ use Email::Address; use Mail::DeliveryStatus::BounceParser; use Class::DBI::AbstractSearch; +use SQL::Abstract; use Mail::Alias; use Cwd qw(abs_path); @@ -62,9 +63,9 @@ It will just queue your e-mail message to particular list (sending it to possibly remote Notice Sender SOAP server just once), send it out at reasonable rate (so that it doesn't flood your e-mail infrastructure) and -track replies. +keep track replies. -It is best used to send smaller number of messages to more-or-less fixed +It is best used to send small number of messages to more-or-less fixed list of recipients while allowing individual responses to be examined. Tipical use include replacing php e-mail sending code with SOAP call to Notice Sender. It does support additional C field for each member @@ -72,7 +73,7 @@ particular user. It comes with command-line utility C which can be used to perform -all available operation from scripts (see C). +all available operation from scripts (see C). This command is also useful for debugging while writing client SOAP application. @@ -120,12 +121,12 @@ } -=head2 new_list +=head2 create_list Create new list. Required arguments are name of C, C address and path to C file. - $nos->new_list( + $nos->create_list( list => 'My list', from => 'Outgoing from comment', email => 'my-list@example.com', @@ -139,7 +140,7 @@ =cut -sub new_list { +sub create_list { my $self = shift; my $arg = {@_}; @@ -158,19 +159,20 @@ } -=head2 delete_list +=head2 drop_list Delete list from database. - my $ok = delete_list( + my $ok = drop_list( list => 'My list' + aliases => '/etc/mail/mylist', ); Returns false if list doesn't exist. =cut -sub delete_list { +sub drop_list { my $self = shift; my $args = {@_}; @@ -179,10 +181,14 @@ $args->{'list'} = lc($args->{'list'}); + my $aliases = $args->{'aliases'} || croak "need path to aliases file"; + my $lists = $self->{'loader'}->find_class('lists'); my $this_list = $lists->search( name => $args->{'list'} )->first || return; + $self->_remove_alias( email => $this_list->email, aliases => $aliases); + $this_list->delete || croak "can't delete list\n"; return $lists->dbi_commit || croak "can't commit"; @@ -262,7 +268,7 @@ list => 'My list', ); -Returns array of hashes with user informations like this: +Returns array of hashes with user information like this: $member = { name => 'Dobrica Pavlinusic', @@ -415,10 +421,7 @@ my $m = Email::Simple->new($message_text) || croak "can't parse message"; - unless( $m->header('Subject') ) { - warn "message doesn't have Subject header\n"; - return; - } + warn "message doesn't have Subject header\n" unless( $m->header('Subject') ); my $lists = $self->{'loader'}->find_class('lists'); @@ -470,8 +473,12 @@ =back +Any other driver name will try to use C module. + Default sleep wait between two messages is 3 seconds. +This method will return number of succesfully sent messages. + =cut sub send_queued_messages { @@ -484,12 +491,17 @@ my $sleep = $arg->{'sleep'}; $sleep ||= 3 unless defined($sleep); + # number of messages sent o.k. + my $ok = 0; + my $email_send_driver = 'Email::Send::IO'; my @email_send_options; if (lc($driver) eq 'smtp') { $email_send_driver = 'Email::Send::SMTP'; @email_send_options = ['127.0.0.1']; + } elsif ($driver && $driver ne '') { + $email_send_driver = 'Email::Send::' . $driver; } else { warn "dumping all messages to STDERR\n"; } @@ -541,7 +553,7 @@ my $m_obj = Email::Simple->new($msg) || croak "can't parse message"; $m_obj->header_set('Return-Path', $from_email_only) || croak "can't set Return-Path: header"; - $m_obj->header_set('Sender', $from_email_only) || croak "can't set Sender: header"; + #$m_obj->header_set('Sender', $from_email_only) || croak "can't set Sender: header"; $m_obj->header_set('Errors-To', $from_email_only) || croak "can't set Errors-To: header"; $m_obj->header_set('From', $from_addr) || croak "can't set From: header"; $m_obj->header_set('To', $to) || croak "can't set To: header"; @@ -559,7 +571,8 @@ } croak "can't send e-mail: $sent_status\n\nOriginal e-mail follows:\n".$m_obj->as_string unless ($sent_status); - my @bad = @{ $sent_status->prop('bad') }; + my @bad; + @bad = @{ $sent_status->prop('bad') } if (eval { $sent_status->can('prop') }); croak "failed sending to ",join(",",@bad) if (@bad); if ($sent_status) { @@ -573,6 +586,7 @@ print " - $sent_status\n"; + $ok++; } else { warn "ERROR: $sent_status\n"; } @@ -588,6 +602,8 @@ $m->dbi_commit; } + return $ok; + } =head2 inbox_message @@ -686,6 +702,100 @@ # print "message_id: ",($message_id || "not found")," -- $is_bounce\n"; } +=head2 received_messages + +Returns all received messages for given list or user. + + my @received = $nos->received_messages( + list => 'My list', + email => "john.doe@example.com", + from_date => '2005-01-01 10:15:00', + to_date => '2005-01-01 12:00:00', + message => 0, + ); + +If don't specify C or C it will return all received messages. +Results will be sorted by received date, oldest first. + +Other optional parametars include: + +=over 10 + +=item from_date + +Date (in ISO format) for lower limit of dates received + +=item to_date + +Return just messages older than this date + +=item message + +Include whole received message in result. This will probably make result +array very large. Use with care. + +=back + +Date ranges are inclusive, so results will include messages sent on +particular date specified with C or C. + +Each element in returned array will have following structure: + + my $row = { + id => 42, # unique ID of received message + list => 'My list', # useful if filtering by email + ext_id => 9999, # ext_id from message sender + email => 'jdoe@example.com', # e-mail of message sender + bounced => 0, # true if message is bounce + date => '2005-08-24 18:57:24', # date of receival in ISO format + } + +If you specified C option, this hash will also have C key +which will contain whole received message. + +=cut + +sub received_messages { + my $self = shift; + + my $arg = {@_} if (@_); + +# croak "need list name or email" unless ($arg->{'list'} || $arg->{'email'}); + + my $sql = qq{ + select + received.id as id, + lists.name as list, + users.ext_id as ext_id, + users.email as email, + }; + $sql .= qq{ message,} if ($arg->{'message'}); + $sql .= qq{ + bounced,received.date as date + from received + join lists on lists.id = list_id + join users on users.id = user_id + }; + + my $order = qq{ order by date asc }; + + my $where; + + $where->{'lists.name'} = lc($arg->{'list'}) if ($arg->{'list'}); + $where->{'users.email'} = lc($arg->{'email'}) if ($arg->{'email'}); + $where->{'received.date'} = { '>=', $arg->{'date_from'} } if ($arg->{'date_from'}); + $where->{'received.date'} = { '<=', $arg->{'date_to'} } if ($arg->{'date_to'}); + + # hum, yammy one-liner + my($stmt, @bind) = SQL::Abstract->new->where($where); + + my $dbh = $self->{'loader'}->find_class('received')->db_Main; + + my $sth = $dbh->prepare($sql . $stmt . $order); + $sth->execute(@bind); + return $sth->fetchall_hash; +} + =head1 INTERNAL METHODS @@ -694,7 +804,7 @@ =head2 _add_aliases -Add new list to C (or equivavlent) file +Add or update alias in C (or equivalent) file for selected list my $ok = $nos->add_aliases( list => 'My list', @@ -715,9 +825,13 @@ my $arg = {@_}; - croak "need list and email options" unless ($arg->{'list'} && $arg->{'email'}); + foreach my $o (qw/list email aliases/) { + croak "need $o option" unless ($arg->{$o}); + } - my $aliases = $arg->{'aliases'} || croak "need aliases"; + my $aliases = $arg->{'aliases'}; + my $email = $arg->{'email'}; + my $list = $arg->{'list'}; unless (-e $aliases) { warn "aliases file $aliases doesn't exist, creating empty\n"; @@ -726,6 +840,8 @@ chmod 0777, $aliases || warn "can't change permission to 0777"; } + die "FATAL: aliases file $aliases is not writable\n" unless (-w $aliases); + my $a = new Mail::Alias($aliases) || croak "can't open aliases file $aliases: $!"; my $target = ''; @@ -747,12 +863,19 @@ $self_path =~ s#/[^/]+$##; $self_path =~ s#/t/*$#/#; - $target .= qq#| cd $self_path && ./sender.pl --inbox="$arg->{'list'}"#; + $target .= qq#"| cd $self_path && ./sender.pl --inbox='$list'"#; + + # remove hostname from email to make Postfix's postalias happy + $email =~ s/@.+//; - unless ($a->append($arg->{'email'}, $target)) { - croak "can't add alias ".$a->error_check; + if ($a->exists($email)) { + $a->update($email, $target) or croak "can't update alias ".$a->error_check; + } else { + $a->append($email, $target) or croak "can't add alias ".$a->error_check; } + #$a->write($aliases) or croak "can't save aliases $aliases ".$a->error_check; + return 1; } @@ -793,7 +916,7 @@ list => $name, email => $email, aliases => $aliases, - ) || croak "can't add alias $email for list $name"; + ) || warn "can't add alias $email for list $name"; my $l = $lists->find_or_create({ name => $name, @@ -835,6 +958,40 @@ return $lists->search({ name => lc($name) })->first; } + +=head2 _remove_alias + +Remove list alias + + my $ok = $nos->_remove_alias( + email => 'mylist@example.com', + aliases => '/etc/mail/mylist', + ); + +Returns true if list is removed or false if list doesn't exist. Dies in case of error. + +=cut + +sub _remove_alias { + my $self = shift; + + my $arg = {@_}; + + my $email = lc($arg->{'email'}) || confess "can't remove alias without email"; + my $aliases = lc($arg->{'aliases'}) || confess "can't remove alias without list"; + + my $a = new Mail::Alias($aliases) || croak "can't open aliases file $aliases: $!"; + + if ($a->exists($email)) { + $a->delete($email) || croak "can't remove alias $email"; + } else { + return 0; + } + + return 1; + +} + ### ### SOAP ### @@ -874,6 +1031,10 @@ aliases => '/etc/aliases', ); +If you are writing SOAP server (like C example), you will need to +call this method once to make new instance of Nos::SOAP and specify C +and options for it. + =cut sub new { @@ -890,9 +1051,9 @@ } -=head2 NewList +=head2 CreateList - $message_id = NewList( + $message_id = CreateList( list => 'My list', from => 'Name of my list', email => 'my-list@example.com' @@ -900,41 +1061,42 @@ =cut -sub NewList { +sub CreateList { my $self = shift; - croak "self is not Nos::SOAP object" unless (ref($self) eq 'Nos::SOAP'); - - my $aliases = $self->{'aliases'} || croak "need 'aliases' argument to new constructor"; + my $aliases = $nos->{'aliases'} || croak "need 'aliases' argument to new constructor"; if ($_[0] !~ m/^HASH/) { - return $nos->new_list( + return $nos->create_list( list => $_[0], from => $_[1], email => $_[2], aliases => $aliases, ); } else { - return $nos->new_list( %{ shift @_ }, aliases => $aliases ); + return $nos->create_list( %{ shift @_ }, aliases => $aliases ); } } -=head2 DeleteList +=head2 DropList - $ok = DeleteList( + $ok = DropList( list => 'My list', ); =cut -sub DeleteList { +sub DropList { my $self = shift; + my $aliases = $nos->{'aliases'} || croak "need 'aliases' argument to new constructor"; + if ($_[0] !~ m/^HASH/) { - return $nos->delete_list( + return $nos->drop_list( list => $_[0], + aliases => $aliases, ); } else { - return $nos->delete_list( %{ shift @_ } ); + return $nos->drop_list( %{ shift @_ }, aliases => $aliases ); } } @@ -954,7 +1116,7 @@ if ($_[0] !~ m/^HASH/) { return $nos->add_member_to_list( - list => $_[0], email => $_[1], name => $_[2], ext_id => $_[4], + list => $_[0], email => $_[1], name => $_[2], ext_id => $_[3], ); } else { return $nos->add_member_to_list( %{ shift @_ } ); @@ -970,10 +1132,6 @@ Returns array of hashes with user informations, see C. -Returning arrays from SOAP calls is somewhat fuzzy (at least to me). It -seems that SOAP::Lite client thinks that it has array with one element which -is array of hashes with data. - =cut sub ListMembers { @@ -1034,9 +1192,50 @@ } } +=head2 MessagesReceived + +Return statistics about received messages. + + my @result = MessagesReceived( + list => 'My list', + email => 'jdoe@example.com', + from_date => '2005-01-01 10:15:00', + to_date => '2005-01-01 12:00:00', + message => 0, + ); + +You must specify C or C or any combination of those two. Other +parametars are optional. + +For format of returned array element see C. + +=cut + +sub MessagesReceived { + my $self = shift; + + if ($_[0] !~ m/^HASH/) { + die "need at least list or email" unless (scalar @_ < 2); + return \@{ $nos->received_messages( + list => $_[0], email => $_[1], + from_date => $_[2], to_date => $_[3], + message => $_[4] + ) }; + } else { + my $arg = shift; + die "need list or email argument" unless ($arg->{'list'} || $arg->{'email'}); + return \@{ $nos->received_messages( %{ $arg } ) }; + } +} ### +=head1 NOTE ON ARRAYS IN SOAP + +Returning arrays from SOAP calls is somewhat fuzzy (at least to me). It +seems that SOAP::Lite client thinks that it has array with one element which +is array of hashes with data. + =head1 EXPORT Nothing.