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(
{
-msg => {
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 a mass mailing to an entire list.
There's many coding practices in this module that we would like to change for the better. It's not the easiest to read code.
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 optional 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 to a list - (old API - don't use, if you can help it)
$mh->mass_send(
Subject => "this is the subject',
Body => "This is the body of the message',
);
# Send to a list - new API
my $message_id = $mh->mass_send(
{
-msg => {
Subject => "this is the subject',
Body => "This is the body of the message',
},
-partial_sending => {...},
-multi_list_send => {
-lists => [@alternative_list],
-no_dupes => 1,
},
-test => 0,
-mass_test => 0,
-test_recipient => 'someone@example.com'
}
);
Mails a message to an entire mailing list.
The Old API is similar to the API to send, but will ignore the, To header,
if you do pass it. Use the new API.
-msg is required and should hold a hashref containing the headers of the
message you want to pass and a special key called, Body, that should hold the
actual email message.
-partial_sending is an optional argument and if passed, should hold a hashref
with the following format:
{
first_name => {
equal_to => "John",
},
last_name => {
like => "Doe",
},
}
keys should be named after profile fields and the values themselves should be a hashref. The hashref keys can either be, "equal_to" or, "like", depending on if you want to do an exact match, or a partial match on a string.
-multi_list_send is optional and should hold a hashref with additional arguments. They are:
should hold an array ref of additional lists you would like to send to
should be set to either 1 or, 0. Setting to, 1 will tell DADA::Mail::Send not to
send the same message twice, to a subscriber that may be on two lists.
-test is optional and should hold a value of either 1 or, 0. If set to 1
the mass mailing will NOT be sent out, via email, but rather written to a file. This file
can be specified using the, test_send_file method. The <-test> paramater works
the same way as the test method.
-mass_test is optional and should hold a value of either 1 or, 0. If set to
1 a mass mailing will be done, but only sent to the recipient set in, -test_recipient,
or the list owner, if no valid recipient is set. Works the same as the, mass_test paramater.
-test_recipient is option and should hold a valid email address of where test mass
mailings should be sent. The, <-mass_test> argument should also be set to, 1.
Works the same as the test_recipient method.
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->list_headers
Similar to _make_general_headers, 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.
Copyright (c) 1999 - 2012 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.