NAME

       Sympa::Bulk - Spool for bulk sending

SYNOPSIS

         use Sympa::Bulk;
         my $bulk = Sympa::Bulk->new;

         $bulk->store($message, ['user@dom.ain', 'user@other.dom.ain']);

         my ($message, $handle) = $bulk->next;

DESCRIPTION

       Sympa::Bulk implements the spool for bulk sending.

   Methods
       new ( )
           Constructor.  Creates new instance of Sympa::Bulk.

       next ( [ no_filter => 1 ] )
           Instance method.  Gets next packet to process, order is controlled by message
           priority, then by packet priority, then by delivery date, then by reception date.
           Packets with future delivery date are ignored (if "no_filter" option is not set).
           Packet will be locked to prevent multiple proccessing of a single packet.

           Parameters:

           None.

           Returns:

           Two-elements list of Sympa::Message instance and filehandle locking a packet.

       quarantine ( $handle )
           Instance method.  Quarantines a packet.  Packet will be moved into bad/ subdirectory
           of the spool.

           Parameter:

           $handle
               Filehandle, Sympa::LockedFile instance, locking packet.

           Returns:

           True value if packet could be quarantined.  Otherwise false value.

       remove ( $handle )
           Instance method.  Removes a packet.  If the packet is the last one of bulk sending,
           corresponding message will also be removed from spool.

           Parameter:

           $handle
               Filehandle, Sympa::LockedFile instance, locking packet.

           Returns:

           True value if packet could be removed.  Otherwise false value.

       store ( $message, $rcpt, [ original => $original ], [ tag => $tag ] )
           Instance method.  Stores the message into message spool.  Recipients will be split
           into multiple packets and stored into packet spool.

           Parameters:

           $message
               Message to be stored.  Following attributes and metadata are referred:

               {envelope_sender}
                   SMTP "MAIL FROM:" field.

               {priority}
                   Message priority.

               {packet_priority}
                   Packet priority, assigned as "sympa_packet_priority" parameter by each robot.

               {date}
                   Unix time when the message would be delivered.

               {time}
                   Unix time in floating point number when the message was stored.

           $rcpt
               Scalar, scalarref or arrayref, for SMTP "RCPT TO:" field(s).

           original => $original
               If the message was decrypted, stores original encrypted form.

           tag => $tag
               TBD.

           Returns:

           If storing succeeded, marshalled metadata (file name) of the message.  Otherwise
           "undef".

       too_much_remaining_packets ( )
           Instance method.  Returns true value if the number of remaining packets exceeds the
           value of the "bulk_fork_threshold" config parameter.

SEE ALSO

       bulk(8), Sympa::Mailer, Sympa::Message.

HISTORY

       Bulk module initially written by Serge Aumont appeared on Sympa 6.0.  It used database
       tables to store and fetch packets and messages.

       Support for DKIM signing was added on Sympa 6.1.

       Rewritten Sympa::Bulk appeared on Sympa 6.2, using spools based on filesystem.