--- trunk/Nos.pm 2005/08/22 20:24:04 72 +++ trunk/Nos.pm 2006/12/19 15:04:05 93 @@ -16,7 +16,7 @@ our @EXPORT = qw( ); -our $VERSION = '0.7'; +our $VERSION = '0.9'; 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. @@ -89,16 +90,21 @@ debug => 1, verbose => 1, hash_len => 8, + full_hostname_in_aliases => 0, ); Parametar C defines length of hash which will be added to each outgoing e-mail message to ensure that replies can be linked with sent e-mails. +C will turn on old behaviour (not supported by Postfix +postalias) to include full hostname in aliases file. + + =cut sub new { - my $class = shift; - my $self = {@_}; + my $class = shift; + my $self = {@_}; bless($self, $class); croak "need at least dsn" unless ($self->{'dsn'}); @@ -267,7 +273,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', @@ -420,10 +426,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'); @@ -460,6 +463,7 @@ list => 'My list', driver => 'smtp', sleep => 3, + verbose => 1, ); Second option is driver which will be used for e-mail delivery. If not @@ -473,10 +477,18 @@ Send e-mail using SMTP server at 127.0.0.1 +=item verbose + +Display diagnostic output to C and C. + =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 { @@ -487,16 +499,22 @@ my $list_name = lc($arg->{'list'}) || ''; my $driver = $arg->{'driver'} || ''; my $sleep = $arg->{'sleep'}; + my $verbose = $arg->{verbose}; $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"; + warn "dumping all messages to STDERR\n" if ($verbose); } my $lists = $self->{'loader'}->find_class('lists'); @@ -517,7 +535,7 @@ while (my $m = $my_q->next) { next if ($m->all_sent); - print "sending message ",$m->message_id," enqueued on ",$m->date," to list ",$m->list_id->name,"\n"; + print "sending message ",$m->message_id," enqueued on ",$m->date," to list ",$m->list_id->name,"\n" if ($verbose); my $msg = $m->message_id->message; foreach my $u ($user_list->search(list_id => $m->list_id)) { @@ -527,9 +545,9 @@ my ($from,$domain) = split(/@/, $u->list_id->email, 2); if ($sent->search( message_id => $m->message_id, user_id => $u->user_id )) { - print "SKIP $to_email message allready sent\n"; + print "SKIP $to_email message allready sent\n" if ($verbose); } else { - print "=> $to_email "; + print "=> $to_email " if ($verbose); my $secret = $m->list_id->name . " " . $u->user_id->email . " " . $m->message_id; my $auth = Email::Auth::AddressHash->new( $secret, $self->{'hash_len'} ); @@ -546,7 +564,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"; @@ -564,7 +582,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) { @@ -576,14 +595,15 @@ }); $sent->dbi_commit; - print " - $sent_status\n"; + print " - $sent_status\n" if ($verbose); + $ok++; } else { - warn "ERROR: $sent_status\n"; + warn "ERROR: $sent_status\n" if ($verbose); } if ($sleep) { - warn "sleeping $sleep seconds\n"; + warn "sleeping $sleep seconds\n" if ($verbose); sleep($sleep); } } @@ -593,6 +613,8 @@ $m->dbi_commit; } + return $ok; + } =head2 inbox_message @@ -691,6 +713,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 @@ -758,7 +874,10 @@ $self_path =~ s#/[^/]+$##; $self_path =~ s#/t/*$#/#; - $target .= qq#| cd $self_path && ./sender.pl --inbox="$list"#; + $target .= qq#"| cd $self_path && ./sender.pl --inbox='$list'"#; + + # remove hostname from email to make Postfix's postalias happy + $email =~ s/@.+// if (not $self->{full_hostname_in_aliases}); if ($a->exists($email)) { $a->update($email, $target) or croak "can't update alias ".$a->error_check; @@ -766,7 +885,7 @@ $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; +# $a->write($aliases) or croak "can't save aliases $aliases ".$a->error_check; return 1; } @@ -923,11 +1042,15 @@ 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 { - my $class = shift; - my $self = {@_}; + my $class = shift; + my $self = {@_}; croak "need aliases parametar" unless ($self->{'aliases'}); @@ -1004,7 +1127,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 @_ } ); @@ -1020,10 +1143,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 { @@ -1084,9 +1203,84 @@ } } +=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 } ) }; + } +} + +=head2 SendTest + +Internal function which does e-mail sending using C driver. + + my $sent = SendTest( list => 'My list' ); + +Returns number of messages sent + +=cut + +sub SendTest { + my $self = shift; + my $args = shift; + die "list name required" unless ($args->{list}); + + require Email::Send::Test; + + my $nr_sent = $nos->send_queued_messages( + list => $args->{list}, + driver => 'Test', + sleep => 0, + verbose => 0, + ); + + my @emails = Email::Send::Test->emails; + + open(my $tmp, ">/tmp/soap-debug"); + use Data::Dump qw/dump/; + print $tmp "sent $nr_sent emails\n", dump(@emails); + close($tmp); + + return $nr_sent; +} ### +=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.