MOJO::Mail

- NAME
- SYNOPSIS
- DESCRIPTION
- new
- Default Headers
- Handy Dandy Methods

- return_headers
- clean_headers
- send
- bulk_send

- COPYRIGHT
- CONTACT INFO

# NAME

MOJO::Mail

# SYNOPSIS

            use MOJO::Mail

            my $mh = MOJO::Mail->new;

Mail Routines for the Mojo Mail MLM, UC?

# DESCRIPTION

Cool name huh? You have found the heart of the beast, this is where ALL mailings will find themselves, one way or another, let's see if we can get this all straightened out so you can customize this to your heart's delight. Follow me...

First off, there are TWO different ways mailings happen, either by sending one e-mail, using the `send()` method, or when sending to a group, using the `bulk_send()` method. This is somewhat of a fib, since mailings called by `bulk_send()` actually use the `send()` method to do its dirty work. Well, that is, if you're not using a SMTP feature, then both the `send()` and `bulk_send()` have their own way of doing it... kinda.

MOJO::Mail uses the Mail::Bulkmail CPAN module, written by James A Thomason III (thomasoniii@yahoo.com) for ALL its SMTP services. And we pretty much love him for that.

PLEASE NOTE That the version of Mail::Bulkmail.pm provided in this distribution IS NOT the same version as is on CPAN, the version in this distribution has 2 bug fixes, one relating to having the correct date applied to messages, the other relating to the fact that there are top level domains with more than 3 letters in 'em.

You create a single address object like so:

            my $mh = MOJO::Mail->new(\%list_info);
            my %mailing = (
            To       => 'justin@skazat.com',
            From     => 'alex@prolix.nu',
            Subject  => 'party over here!',
            Body     => 'yo yo yo, wheres the flava at? we need some action!',
            );
            $mh->bulk_send(%mailing);

Pretty fricken hard eh? Well, it can get a bit harder than that, but thats a pretty stripped down version, If you wanted, you could theoretically use this as a do all mail sender + all the features that are in the Guts.pm module. Its pretty easy to make some crazy... stuff once you've got a handle on it.

# new

new should take a reference to a hash which is the list settings hash, gotten from `open_database()` in Guts.pm. Why? cause the list settings have all sorts of... well settings to change how things get sent. Can you call this module without this hash reference? Yes! you may, you can even fib the hash reference, if you want:

            my $mh = MOJO::Mail->new({this => 'that'})

please note that you need at least a list name for bulk sending. The list name is needed to open the actual subscription list to send out to people.

you can use just the `send()` method without anything passed to new

# Default Headers

MOJO::Mail has a wide variety of both e-mail headers you can send to it. you do this through either the send() or bulksend() methods

- From
  This should hold where the e-mail is from. Tricky, eh?

  example:

              To => '"Justin Simoni" <justin@skazat.com>',

- To
  Mail Header, This should hold where the e-mail is going to,

  example:

              From =>  '"Alex Skazat" <alex@skazat.com>',

- Bcc
  This is used as a ``Blank Carbon Copy'', meaning a copygoes to whoever is specified in the Bcc header, without it showing up in the To's header. DO NOT USE THIS FOR BULK MAILING Send one 100,000 emails, some poor fella is going to get 100,000 copies

  example: same as the To or From

- Return-Path
  Specifies what address an e-mail will get sent to when someone replies to an e-mail address. Sometimes works, sometimes doesn't, very fluky, better to set with the sendmail '-f' flag

  example:

              'Return-Path' => 'justin@skazat.com',

- Reply-To
  Very similar to the Return-Path,

- Errors-To
  Mail Header, specifies where errors, like if the e-mail address you're trying to send isn't real, or their mailbox is full, a message supposed to use this address to mail the error to.

  example:

              'Errors-To' => 'errors@skazat.com',

- Organization
  Mail Header, um, specify an organization, this could be pretty mch anything you want.

  example:

              Organization => 'Curtled Yogart Appreciation Club',

- Precedence
  Mail Header, sets the so called 'precedence' of a bulk message, the valid values are list, bulk and junk. Certain e-mail clients may use this to filter out spam, or list messages,

  example:

              Precedence => 'junk',

  default is list.

- Content-Type
  sets the content type of the email message, something like text/plain or text/html, it tells the mail reader how to show the mail message. This is also where you can specify certain character sets, since not everyone uses english as their first language,

  like:

              Content-Type => 'text/html; charset=us-ascii';

- Content-Disposition
  (ah hem) ``Whether a MIME body part is to be shown inline or is an attachment; can also indicate a suggested filename for use when saving an attachment to a file.'' Yeah... I usually use this for HTML and Multipart messages, and I just have it for the ride so emails come out correctly when using mojo_send.pl, as Microsoft Entourage, Outlook like to use this header,

  example:

              'Content-Disposition =>  'inline; filename="index.html"',

- Content-Transfer-Encoding
  (ah hem) ``Coding method used in a MIME message body.''

  example:

              'Content-Transfer-Encoding' =>  7bit',

  you could also say 'base64', '8bit' or 'quote-printable'

- MIME-Version
  this specifies what MIME version your using, usually this is set as 1.0, without setting a MIMIE version HTML e-mails don't come out well,

  example:

              'MIME-Version' => '1.0',

- List
  This can be a mail header, mojo uses it internally to say what list is sending bulk messages, the list name is important to fetch all sorts of things, write temp files, etc,

  example List => 'my list',

- Mailing List Headers
  Theres a whole slew of Mailing List related headers, that are pretty self-explainatory:

  List-Archive

  List-Digest

  List-Help

  List-ID

  List-Owner

  List-Post

  List-Subscribe

  List-Unsubscribe

  List-URL

  List-Software

- References
  this tag is used by popular Mail readers to figure out how different messages are related.

  This isn't used in Mojo Mail, but it may one day for its archives, this usually holds a weird numerical value,

- In-Reply-To
  Again, this is used by mail readers to keep track of e-mail messages.

- Subject
  The subject of your message

  example:

              Subject => 'mail server is about to explode',

- Body
  This is the body message, usually I make the value before hand, and stick the variable in, like this:

              my $Body = <<EOF

              Help!
              I'm trapped in a peanut butter factory,
              The only way I can communicate with the
              real world is by sending messages inside
              peanut butter containers.

                      Bob,
              EOF
              ;

              Body => $Body,

  This really isn't a mail header, but this is how you get the Body of a message to Mojo Mail =back

  Please Note

  In earlier versions of this module, certain key/value pairs were passed to this script to change the way mailings were done. No more. Settings that afect mailings are either passed in the hash ref you passed to `new()` or, by some handy dandy methods

# Handy Dandy Methods

These methods are used to change how Mojo Mail sends mostly Bulk messages, these are the fun ones,

- do_not_send_to
  This ones kinda cool, give it a reference to an array of addresses you do not want sent the email. I use this for mojo-send, to make sure that that whoever you write the e-mail to, won't also receive the e-mail, or that will go on forever,

  you could also specify your entire black list. The possibilities, kids, are endless.

  example: $mh->do_not_send_to(['justin@skazat.com', 'alex@prolix.nu']);

  This array ref is then passed to List::*::create_bulk_sending_file function that makes the actual list to send to. Basically create_bulk_sending_file weeds out the emails in a list we don't want to send to

- bulk_test
  This is a magical paramater that, when changed to one, will only send bulk messages to the list owner. ``What's the point of that?'' well, it'll set up MOJO::Mail as if it was sending a bulk message, instread of being in ``send one message mode'' This makes sure all your configs are peachy keen. 1 for test, nothing for no test,

## return_headers

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

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 seperated, each key in the hash holds a different header, so if I say

            my $mh = MOJO::Mail -> 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 Mojo Mail can use.

## clean_headers

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

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

## send

This method sends an email, it takes a hash of the mail headers, plus the body of the message:

$mh->send(To => 'justin@skazat.com',
| From => 'secret@admirer.com',
| Subject => 'smooch!',
| Body => 'you are so cute, you little Perl Coder you'
| );

## bulk_send

Sends a message to everyone on your list, (that you specified, by passing a hash ref with the list settings.. right?)

Takes the same arguments as `send()`

# COPYRIGHT

Copyright (c) 1999 - 2002 Justin Simoni (justin@skazat.com) http://skazat.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.

# CONTACT INFO

Justin Simoni http://skazat.com justin\@skazat.com

A good place to start to get information is at:

http://mojo.skazat.com