DADA::Mail::Send

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( 
        { 
                -msg => {
                        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 a mass mailing to an entire list.

Warning: Thar Be Dragons

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.

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 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

 # 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 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  => {...}, 
                        -test      => 0,
                        -mass_test => 0, 
                        -test_recipients => '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.

-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> parameter 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_recipients, or the list owner, if no valid recipient is set. Works the same as the, mass_test parameter.

-test_recipients 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_recipients method.

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:

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

list_headers

 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:

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.

COPYRIGHT

Copyright (c) 1999 - 2023 Justin Simoni me - justinsimoni.com https://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.

Dada Mail Project

Download

Installation

Support