DADA::Mail::Send
# 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',
);
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.
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.
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 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.
# 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.
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.
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'
my %headers = $mh->_make_general_headers;
Takes no arguments.
Return a hash containing the following Email Headers:
The idea behind _make_general_headers is to create usable defaults to email headers that should be included in your email messags.
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:
%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
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.
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 (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.