- NAME
- SYNOPSIS
- DESCRIPTION
- REQUIREMENTS

- METHODS

# NAME

GT::Mail::BulkMail - A (perhaps overly) simplified interface to sending bulk emails

# SYNOPSIS

        $mailer = new GT::Mail::BulkMail;
        $mailer->option("setting");
        $mailer->otheroption("othersetting");
        ...

        -- or --

        $mailer = new GT::Mail::BulkMail(
            -option      => "setting",
            -otheroption => "othersetting",
            ...
        );

        -- then --

        sub subroutine {
            # Code to generate the next e-mail address
        }
        open FILE, "email_list.txt";
        %hash = ( 1 => 'some@fictional.address',
                  2 => 'who@knows.where'
                );
        @array = ('yet@another.fictional.address','and@one.more');
        $mailer->send(\&subroutine,\*FILE,\%hash,\@array);
        close FILE;

# DESCRIPTION

GT::Mail::BulkMail is a module to handle mass mailings. It is capable of using either sendmail, or an SMTP server. It has the advantage of not requiring multiple connections to the SMTP server.

# REQUIREMENTS

Perl 5.004

## METHODS

All methods can be specified at object creation time as an option with the: -option => value syntax. For example, `$mailer = new GT::Mail::BulkMail(-from => "foo@bar.com")` would have the same effect as: `$mailer = new GT::Mail::BulkMail(); $mailer->from("foo@bar.com")`

smtp
  Sets the SMTP server to use, and sets the object mail sending method to use SMTP. Takes SMTP server as argument.

sendmail
  Sets the sendmail executable to use. Takes the path to sendmail as the argument.

text
  Specifies that the mail format is text. This translates into Content-type: text/plain. This is the default format.

html
  Specifies that the mail format is HTML. (Content-type: text/html)

headers
  Returns any custom headers set as a hash reference in scalar context, or a hash in list context.

add_header
  Adds a single header. This can be any header starting with ``X-'' (Note that X-Mailer headers will be prepended with the GT::Mail::BulkMail X-Mailer header (which includes the perl version, OS name, GT::Mail::BulkMail module and CVS versions, and the Gossamer Threads homepage)). Pass two arguments: A key (header name) and a value (header value). For example, for `X-Foo: blah blah blah` you would use: $mailer->add_header(``X-Foo'' => ``blah blah blah'')

add_headers
  Same as above, except it adds multiple headers. Has the same argument format. You would use: $mailer->add_headers(``X-Foo1'' => ``blah'', ``X-Foo2'' => ``blah blah'');

delete_header
  Deletes a single header. Pass the name of the header to delete.

delete_headers
  Delete multiple headers. Pass a list of names of headers to delete.

from
  Sets the ``from'' field of the e-mail. Must be set before $mailer->`send()` can be called. Must be set to an e-mail address. If this e-mail address is rejected by the SMTP server, no e-mails will be sent.

name
  Sets the ``name'' field of the e-mail. This affects what is displayed in the ``From'' field. When sending the email, the actual field will be set to: `"This name" <some@name.net>`. Optional.

subject
  Sets the subject of the message. If not specified, it will default to ``(no subject)''

message
  The body of the message. Can be left blank, but that seems rather pointless... The message will be encoded using the quoted-printable format if it contains characters outside the 7-bit range.

success
  A code reference to be run for each and every successful e-mail sending. Each call to this code reference will be given the e-mail address as the only argument (unless using a message ID, which is discussed below). Optional.

failure
  A code reference that will be run for any email addresses that cannot be sent. Each call to this code reference will be given the ID or e-mail address as the argument (message IDs are discussed below). Optional.

frompresend
namepresend
subjectpresend
messagepresend
  A code reference that will be run before sending an e-mail. The 'from', 'name', 'subject', or 'message' field will be sent to the code references (depending on which method called) and whatever is returned will be used as the actual field for the email sent. This can be used to parse fields to customize them for each recipient. The subroutine is called with two arguments: (ID_OR_EMAIL, FIELD). If an ID is provided, it will be passed as the first argument, otherwise the email address will be passed. The second argument is the field itself. The field used in the actual email to the user will be the value returned by the subroutine.

  The default field (for the rest of the mailing) can be changed by directly modifying $_[1] itself.

  If the subroutine reference returns an undefined value, the mailer will use the actual field instead. You can use this technique to only modify some messages, but not others.

  Optional.

show_errors
  If set to something true it will `warn()` on all errors. Optional. The default is turned on, but can easily be changed by modifying the line '

error_code
  Takes a code reference - the code reference will be called with the error as the argument when an error occurs. Optional.

send
  Takes any number of the following arguments:

array reference
  An array reference of a list of e-mail addresses to send to. After each message, either the success or failure callback will be called with the e-mail address as the argument, and possibly a message as the second argument.

hash reference
  A hash reference of ID => email pairs. For example, 123 => 'someone@whoknows.com'. The value will be used as the e-mail address to send to, and the key will be an identifier to pass into the success or failure callbacks.

glob reference
  A glob reference to an open file. Make sure the file is opened before passing this! The file should contain one e-mail address per line.

subroutine or code reference
  You may pass a code reference, and it will be called for each e-mail address. It is assumed that the subroutine will return one e-mail address each time called, and that a return value of ``undef'' indicates that there are no more e-mail addresses. The code reference could alternatively return two items - if it does, it is assumed that the first is an ID code, and that the second is the email address. When a call to either or the success or failure callbacks, the ID will be provided as the first argument instead of the e-mail address itself.

  One cool feature to note about using code refs is that you can call `next()` from within the code reference and it will then recall the code reference for the next value.