DADA::Mail::Send

- NAME
- SYNOPSIS
- DESCRIPTION

- Warning: Thar Be Dragons

- Public Methods

- new
- send
- mass_send
- test
- test_send_file

- Private Methods

- _make_general_headers
- _make_list_headers
- clean_headers
- return_headers

- See Also
- COPYRIGHT

# NAME

DADA::Mail::Send

# SYNOPSIS

     # Initialize:
     my $mh = DADA::Mail::Send->new(
                             {
                                    -list => 'mylist',
                            }
                    );

     # Send something out:
     $mh->send(
            From    => 'me@example.com',
            To      => 'you@example.com',
            Subject => "this is the subject',
            Body    => "This is the body of the message',
      );

     # Send a whole lot of things out:
     $mh->mass_send(
            Subject => "this is the subject',
            Body    => "This is the body of the message',
     );

# DESCRIPTION

`DADA::Mail::Send` is in charge of sending messages, via email.

There's two ways this is done -

The first is using the `send` method. This is used to send one message to one person.

The second way is using the `mass_send` method. This sends one message to a whole lot of people - in this case, the entire mailing list.

## Warning: Thar Be Dragons

This module is probably one of the oldest in Dada Mail and has a lot of Dragons in the code. It has to be sad that I used to be much less adept at Perl coding. Now, I'm just slightly awful :)

Much work has been done to keep the code maintainable and clean, but there is still some nasty bits that are too complex, bits that don't do anything anymore and other bits that are just freaky in weirdness. We've attempted to keep those to a minimum, but be warned that hackability of this code in here is somewhat not for the faint of heart.

One of the most ridiculously complex parts is the entire `mass_send` method. It's seen many revisions and quite a bit of its functionality has been taking over by the `DADA::Mail::MailOut` module, but traces of what was once cobbled there still remains.

Both the `send` and `mass_send` methods are quite long - which isn't the best thing in the world.

# Public Methods

## new

     my $mh = DADA::Mail::Send->new(
                             {
                                    -list   => 'mylist',
                                    -ls_obj => $ls,
                            }
                    );

Creates a new `DADA::Mail::Send` object.

`new` requires one argument, `-list`, which should hold a valid `listshortname`.

`new` has one option argument, `-ls_obj`, which should hold a valid `DADA::MailingList::Settings` object, like so:

     use DADA::MailingList::Settings;
     use DADA::Mail::Send;

     my $list = 'mylist';

     my $ls = DADA::MailingList::Settings->new({-list => $list});

     my $mh = DADA::Mail::Send->new(
                            {
                                    -list   => $list,
                                    -ls_obj => $ls,
                            }
                      );

Passing a `DADA::MailingList::Settings` object is just an optimization step and is not required. With the SQL backend, it does mean one less SQL query, which is nice.

## send

     # Send something out:
     $mh->send(
            To      => 'you@example.com',
            Subject => 'this is the subject',
            Body    => 'This is the body of the message',
      );

Sends a message, via email.

Takes a variety of arguments. The arguments should be various Email Headers and the body of the email message, passed in `Body`

For example, if you have an email message that looks like this:

     From: me@example.com
     To: you@example.com
     Subject: This is the Subject!
     Body: This is the Body!

You would pass it to, `send` like so:

     # Send something out:
     $mh->send(
            From    => 'me@example.com',
            To      => 'you@example.com',
            Subject => 'This is the Subject!',
            Body    => 'This is the Body!',
      );

No arguments are really necessary, although your message isn't going to get very far, or have much content.

At the very minimum, you probably want to pass, `To`, `Subject` and, `Body`. All other headers will be filled out to something that's pretty sane.

For example, if the `From` argument isn't passed, the List Owner of the list is used. This proves to be useful.

This method is somewhat strange, once you get to multipart/alternative messages - passing the arguments is done exactly the same way.

## mass_send

     # Send a whole lot of things out:
     $mh->mass_send(
            Subject => "this is the subject',
            Body    => "This is the body of the message',
     );

Mails the message passed to the entire mailing list.

Takes arguments similar to `send`, although you won't want to set the To argument, as it'll be overwritten, when filled out for each subscriber.

`mass_send` is without a doubt the most powerful method in Dada Mail, since this very easy method invocation does a whole lot of hard stuff. Please think of that if you ever delve into the code and see a whole mess of stuff.

## test

     my $test = $mh->test;
     # returns, "0"

     # or:
     $mh->test(1);
     # returns, "1"

     $mh->test;
     # now returns, "1"

The `test` method is used to change part of the behavior of both the, `send` and, `mass_send` methods.

Instead of sending a message via email, the messsage being created will simply be written to a file.

The file name and location is saved in the `test_send_file` method

This method, so rightly named, is handy for testing and debugging, since you can go through the entire process of sending a message, but simply write the message to a file, to be examined by a trained professional. Or, Justin.

## test_send_file

     my $test_file = $mh->test_send_file

     # or:
     $mh->test_send_file('/some/path/to/a/file.txt');

     # Now
     $test_file = $mh->test_send_file;
     # Returns: /some/path/to/a/file.txt

`test_send_file` is used to store and set the location of the file that `DADA::Mail::Send` uses to save email messages to, when `test` is set to, 1.

Defaults to: `$DADA::Config::TMP . '/test_send_file.txt'`

# Private Methods

## _make_general_headers

     my %headers = $mh->_make_general_headers;

Takes no arguments.

Return a hash containing the following Email Headers:

- From
- Reply-To
- Errors-To
- Message-ID
- X-Habeas
- Precedence
- Date

The idea behind `_make_general_headers` is to create usable defaults to email headers that should be included in your email messags.

## _make_list_headers

     my %list_headers = $mh->_make_list_headers

Similar to `_make_general_headers`, `_make_list_headers` creates a set of email headers - in this case headers that deal with Mailing Lists. They are:

- List
- List-URL
- List-Unsubscribe
- List-Subscribe
- List-Owner
- List-Archive
- List-Post
- List-ID

## clean_headers

     %squeaky_clean_headers = $mh->clean_headers(%these_be_the_heaers);

Not a private method per-se, but seems of little use outside the internals of this module -

This method does a little munging to the mail headers for better absorbtion; basically, it changes the case of some of the mail headers so everyone's on the same page

## return_headers

            my %headers = $mh->return_headers($string);

Again, not clearnly a private method, but of little use outside of the internals.

This is a funky little subroutine that'll take a string that holds the header of a mail message, and gives you back a hash of all the headers separated, each key in the hash holds a different header, so if I say

            my $mh = DADA::Mail::Send -> new();
            my %headers = $mh -> return_headers($header_glob);

I can then say:

            my $to = $headers{To};

This subroutine is used quite a bit to take out put from the MIME::Lite module, which allows you to get the whole header with its `header_to_string()` subroutine and hack it up into something Dada Mail can use.

# See Also

A great bit of the scheduling, auto-pickup'ing and status'ing of the mass mailing, (basically, everything except looping through the list is controlled by `DADA::Mail::MailOut`. `DADA::Mail::Send` is quite dumb in what it does, `DADA::Mail::MailOut` is quite smart.

# COPYRIGHT

Copyright (c) 1999-2008 Justin Simoni me - justinsimoni.com http://justinsimoni.com All rights reserved.

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.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.