Programming with Perl Modules: Chapter 4

#!/usr/local/bin/perl -w

use strict; # i will eat it very quick i will eat it using strict
use Mail::POP3Client;

my($pop, $num_mesg, $i);

$pop = Mail::POP3Client->new("nvp",
                            "xxxxxx",
                            "mail.somename.com",
                            110,
                            1);

        # How many messages do we have?
$num_mesg = $pop->Count;
print("You have ".$num_mesg." new message(s).\n");

        # Now, output the headers for all the messages.
for ($i = 1; $i <= $num_mesg; $i++) {
    print $pop->Head($i), "\n";
}

#!/usr/local/bin/perl -w

use strict; # be there or be square
use Mail::POP3Client;

my($pop, $num_mesg, $i);

$pop = Mail::POP3Client->new("nvp", # required
                            "xxxxxx", # required
                            "mail.somename.com", # pop host
                            110, # port (an integer)
                            1); # debug flag (an integer)

$num_mesg = $pop->Count;
print("You have ".$num_mesg." new message(s).\n");

for ($i = 1; $i <= $pop->Count; $i++) {
    foreach ($pop->Head($i)) {
               # output from and subject
        # if matched by regexp
        print $_." " if /^(From|Subject)/;
   }
           # now, send a trailing \n for grins
    print "\n";
}

~/ORA/PRK/Chapters/Mail/scripts> ./ex1_7.pl
POP3: POPStat at ./ex1_7.pl line 8
You have 1 new message(s).
TOP 1 0
+OK Top of message follows
From: "Nathan V. Patwardhan" <nvp> Subject: pop test

Getting and Setting the Host and Port

$obj->Host;

$new_host = 'new-pop.bar.com';
$obj->Host($new_host);

$obj->Port;

$new_port = 7000;
$obj->Port($new_port);

Retrieving the Message Body

#!/usr/local/bin/perl -w

use strict; # those who are late will not be served fruit cup.
use Mail::POP3Client;

my($pop, $num_mesg, $i);
$pop = Mail::POP3Client->new("nvp", # required
                            "xxxxxx", # required
                            "mail.somename.com", # pop host
                            110, # port (an integer)
                            0); # debug flag (an integer)

$num_mesg = $pop->Count;
print("You have ".$num_mesg." new message(s).\n");

for ($i = 1; $i <= $pop->Count; $i++) {
    foreach ($pop->Retrieve($i)) { # show the message, $i
        print $_,"\n"; # add a \n to end of each line
    }
    print "\n";
}

~/ORA/PRK/Chapters/Mail/scripts> ./ex1_8.pl
You have 1 new message(s).
Received: (from nvp@localhost)
        by mail.somename.com (8.8.5/8.8.5) id AAA03248
        for nvp; Mon, 9 Jun 1997 00:11:09 -0500 (EST)
Date: Mon, 9 Jun 1997 00:11:09 -0500 (EST)
From: "Nathan V. Patwardhan" <nvp>
Message-Id: <199706090511.AAA03248@mail.somename.com>
To: nvp
Subject: pop test
Status: RO
this is a pop test

Deleting and Undeleting Messages

$pop->Delete(1);

Like most mail programs, Mail::POP3Client can undelete messages marked for deletion before the program is terminated and the changes saved. The Reset() function takes one argument, representing the number of the message to undelete:

$pop->Reset(1);

Checking the Connection

#!/usr/local/bin/perl -w

use strict; # be there or be square
use Mail::POP3Client;

my($pop, $is_alive);
$pop = Mail::POP3Client->new("nvp", # required
                            "xxxxx", # required
                            "mail.somename.com", # pop host
                            110, # port (an integer)
                            1); # debug flag (an integer)

$is_alive = $pop->Alive; # Alive() returns 1 if connected
if($is_alive == 1) {
    print("You are currently connected to: ".$pop->Host."\n");
} else {
    print("Error: disconnected!\n");
}

~/ORA/PRK/Chapters/Mail/scripts> ./ex1_10.pl
POP3: POPStat at ./ex1_10.pl line 8
You are currently connected to: mail.somename.com

Explicitly Opening and Closing Connections

$pop->Close;
if($pop->Alive == 1) {
    print "Connected.\n";
} else {
    print "Not connected.\n";
}

Mail Helper Modules

Handle Folders with Mail::Folder

Mail::Folder was written by Kevin Johnson (kjj@pobox.com) as an object-oriented, folder-independent interface to email folders that supports mbox, maildir, emaul, and NNTP mailbox formats. Since mbox is a standard mailbox format supported by a number of UNIX mail clients, the examples in this section demonstrate Mail::Folder's mbox (Mail::Folder::Mbox) capabilities. You can find examples for other mail folder formats in Chapter 19 of the Module Reference Guide, Volume 2.[2]

You'll need to create a Mail::Folder object before you can use the module. Mail::Folder uses the new() method as a constructor. The new() method takes three arguments: the type of the folder you'll be using, the name of the folder, and a list of options described below. If you specify the name of the folder, Mail::Folder automatically opens the folder with the open() method.

The options to the new() constructor for Mail::Folder are:

Create

The folder is created if it doesn't already exist.

The Content-length header is created or updated by append_message() and update_message().

Uses .lock style folder locking with the proper folder interface (mbox is the only interface that currently uses this).

Uses flock-style folder locking with the proper folder interface (mbox is the only interface that currently uses this).

Deals with NFS-style file locking with the proper folder interface and the NFS server in question.

The folder interface overrides the default value for timing out. This is particularly useful for folder interfaces that involve network communications. Time is specified in seconds.

Auto-detects folder type if AUTODETECT has been set (neat!).

$ftype = 'mbox';
$foldername = '/home/nvp/Mail/nvp';
$fldr_obj = new($ftype, $foldername [, %options]);

open()

If you haven't specified a folder name in the constructor, you'll need to call the open() method, which takes the folder name as an argument. open() populates the internal data structures with information it gathers from the mail folders. readonly is set if the folder is determined to be read-only.

$folder_obj->open($foldername);

Once you've opened a mail folder, you'll want to read the messages. The get_message() method takes a message number as an argument and returns 0 for failure.

$num = 24;
$folder_obj->get_message($num);

Mail::Folder also parses messages with MIME content (see the section, "The MIME Modules," later in this chapter). The get_mime_message() method calls get_message_file() to get a file to parse, creates a MIME::Parser object, and reads the content into MIME::Entity. get_mime_message() takes the same options as MIME::Entity.

This method returns a filename instead of a Mail::Internet object reference and works well with the MIME tools package.

$num = 2;
$folder_obj->get_message_file($num);

The get_header() method extracts a message header and takes one argument, the message number.

$num = 45;
$folder_obj->get_header($num);

This method works much like get_header(), but calls MIME::Head instead. It takes one argument, the message number.

$num = 392;
$folder_obj->get_mime_header($num);

The append_message() method adds a message to a folder and takes a reference to a Mail::Internet object as an argument.

$folder_obj->append_message($mi_ref);

This method moves messages between folders and takes a message number and folder reference as arguments.

$folder_obj->refile($num, $fldr_ref);

The delete_message() method takes a list of messages to be marked for deletion. Messages won't actually be deleted until sync is called.

@all = (1, 2, 3, 5);
$folder_obj->delete(@all);

This method unmarks a list of messages that have been marked for deletion. Like delete_message(), it takes a list as an argument:

@unmark(1, 3, 4, 6);
$folder_obj->undelete_message(@unmark);

This method returns a list of the message numbers in the folder (in no particular order).

print $folder_obj->message_list."\n";

This method returns the number of messages in the folder.

print "There are ".$folder_obj->qty." 
messages in your folder\n";

Handle Messages with Mail::Internet

Mail::Internet is built on top of Mail::Header, which parses the header of an electronic mail message. Mail::Internet inherits the Mail::Header constructor style that requires a file descriptor or reference to an array be used. For example:

@lines = <STDIN>;
$mi_obj = new Mail::Internet([@lines]);

open(FILE, "/home/nvp/Mail/nvp");
$mi_obj = new Mail::Internet(\*FILE);
close(FILE);

open(FILE, "/home/nvp/Mail/nvp");
$mi_obj = new Mail::Internet(\*FILE);
close(FILE);
$mi_obj->print_header(\*STDOUT);

From nvp Mon Jun  9 00:11:10 1997
Received: (from nvp@localhost) by mail.somename.com (8.8/8.8) id
    AAA03248 for nvp; Mon, 9 Jun 1997 00:11:09 -0500 (EST)
Date: Mon, 9 Jun 1997 00:11:09 -0500 (EST)
From: "Nathan V. Patwardhan" <nvp>
Message-Id: <199706090511.AAA03248@mail.somename.com>
To: nvp
Subject: pop test
X-Status:
X-Uid: 1
Status: RO

Parse Email Addresses with Mail::Address

"Full Name or Phrase" <username@host> (Comment Area)

"Nathan V. Patwardhan" <nvp@mail.somename.com> (No Comment)

"Nathan V. Patwardhan" <nvp@mail.somename.com>

$addr = Mail::Address->new("Full Name or Phrase",
                           "username@host",
                           "(Comment Area)");

print $addr->phrase();

Nathan V. Patwardhan

print $addr->address();

nvp@mail.somename.com

print $addr->comment();

No Comment

print $addr->user;

nvp

print $addr->host;

nvp@mail.somename.com

 |/path/parseform.pl your_username 

#!/usr/local/bin/perl -w

use MIME::Head; # used to parse the message header
use Mail::Address; # used to parse the sender's address
use strict; # the hills are alive

my($header, $bar, $foo);

$header = new MIME::Head;
$header->read(\*STDIN); # read message from STDIN
$bar = $header->get('From', 0); # grab the header containing 'From'

# If the address doesn't match the form
# PHRASE ADDRESS (COMMENT), use the first regexp which won't
# try to match (COMMENT).  Otherwise, grab everything.
if(....) {
#match address type 1
} else {
#match address type 2
}

Handling MIME Data

Although many mail readers are able to parse and decode the contents of MIME messages, others, like RMAIL and elm, require an external program to parse and display the contents of a MIME-encoded mail message. There are several different packages that handle MIME message interpretation, but we'll concentrate on the metamail package, and specifically the mailcap file. The mailcap file is read by metamail to determine how entities of multipart mail messages or nontext attachments are handled.

For more information on sending mail with MIME attachments, see the discussion of Base64-encoding later in this chapter.

Format of the mailcap File

mailcap entries are divided into four fields, separated by semicolons. The four fields are:

• The Content-type of the entry

• A command to execute when the Content-type is encountered

• An optional flag that is passed to the command if necessary

• An optional entry description, denoted with a description tag

application/x-perl; ptkat %s; nonummy

application/x-perl; ptkat %s; nonummy; \
description="pTk applications that should not be."

mailcap entries preceded with a # are considered comments and are skipped by metamail; blank lines are also ignored. Multiline entries can be written, providing they are denoted with a backslash (\). Many editors automatically insert a backslash at the end of any line that exceeds x characters.

Using the Mail::Cap Module

$mailcap = Mail::Cap->new();

# use the mailcap file stored in /path called local_mailcap
$my_mailcap_file = '/path/local_mailcap';
$mailcap = Mail::Cap->new($my_mailcap_file);

The view() function takes the two parameters (Content-type and filename) and executes the external programs specified in the second and third fields of the mailcap file; edit(), compose(), and print() work in a similar fashion.

Here's a simple program that takes a command-line argument and handles the data from $ARGV[0]:

#!/usr/local/bin/perl -w

use Mail::Cap;

$capfile = '/home/nvp/mailcap';
$mcap = Mail::Cap->new($capfile);
$mcap->view('image/jpg', $ARGV[0]);

The mime.types File

Like the mailcap file, the mime.types file contains a number of RFC 822-compliant Content-types, but the mime.types file generally doesn't contain information about external programs to be executed when a given Content-type is encountered; that decision is made on the browser's end. The mime.types file is used to create an association between a file's extension and Content-type. The server conveys the Content-type to the browser, and the browser takes it from there.

Here's a command-line-based program that parses a file's extension (using File::Basename), and searches a mime.types file for a matching extension. If an extension is found, the Content-type of the document is returned and passed to the Mail::Cap view() function so the document can be viewed correctly.

#!/usr/local/bin/perl -w

use File::Basename; # for the file's extension
use Getopt::Long; # for the command-line arguments
use Mail::Cap; # to parse the mailcap file

# you're not leaving this table until you've eaten all of your peas
use strict; 

# remember, we're using strict
my($infile, $capfile, $file_ext, $mimetype, $mailcap);

# program must be executed like: programname -file inputfile
# if not, output a usage message
GetOptions('file=s', \$infile);
$infile or usage();

# specific capfile.  without declaring this, and creating an
# object like: $mailcap = new Mail::Cap, Mail::Cap will expect
# that you have an existing mailcap file (in /etc/mailcap or such),
# or have defined an environment variable MAILCAPS
$capfile = 'mailcap';

# From File::Basename, grab the extension of the file (field 2).
# This extension will be passed to lookup_type-by_extension, which 
# returns a Content-type if the extension matches an entry in the
# mime.types file
($file_ext) = (fileparse($infile, '\..*'))[2];
$mailcap = Mail::Cap->new($capfile);
$mimetype = lookup_type_by_extension($file_ext);
$mailcap->view($mimetype, $infile);

sub lookup_type_by_extension {
    my($ext) = @_;
    my($ctype, @ftype, @found);
    my($m_types) = 'mime.types';

    open(TFILE, $m_types) or die("error opening $m_types: $!");
    while(<TFILE>) {
        # remove newlines
        chop;

        # get the content-type and extensions (file types) of
        # mime.types entries by splitting each line of the file
        # on the tab character
        ($ctype, @ftype) = split(/\t/, $_, 2);

        # check to see if extension appears in @ftype array
        # yes Virginia, I've been reading perlfaq4  :-)
        my %found = ();
        for(@ftype) { $found{$_} = 1; }

        # if extension exists, there will be an element in @found,
        # so scalar(@found) will be greater than zero. Return the
        # content-type of the mime.types entry
        return $ctype if $found{$ext};
    }
    close(TFILE);

}
sub usage {
    print("Usage: $0 -file <filename>\n");
    exit(0); # failure
       }

The MIME Modules

• MIME:Base64, the heart of the MIME modules, which handles encoding and decoding MIME data

• MIME::Lite, a simple yet powerful module for creating simple MIME attachments

• MIME::Entity, a more robust module for creating MIME attachments

• MIME::Parser, which can parse MIME messages

Encoding and Decoding with MIME::Base64

Here's what the base64 algorithm does:

1. Reads data into a variable (in this case, we're using a scalar, $_) and defines an end-of-line character. We'll need to add this to the 76th character of each encoded line.

   $end_of_line = "\n" unless defined $end_of_line;
   

2. Iterates through $_ and encodes lines using substr() and pack() with the u attribute to uuencode the lines, appending each line to a scalar, $res, then chopping the last character from each line.

   while ($_[0] =~ /(.{1,45})/gs) {
        $encoded .= substr(pack('u', $1), 1);
        chop($res);
   }
   

3. After uuencoding all the data, transforms certain characters using tr/// to comply with the MIME specification. Also adjusts the padding of each line. The tr and padding statements represent the actual base64-encoded string.

   # for 'smart' base64 'uu'encoding
   $encoded =~ tr|` -_|AA-Za-z0-9+/|;
   
   # fix padding at the end
   my $padding = (3 - length($_[0]) % 3) % 3;
   $encoded =~ s/.{$padding}$/'=' x $padding/e if $padding;
   

4. Now, using a regular expression, breaks the string into lines containing no more than 76 characters.

   if (length $end_of_line) {
        $encoded =~ s/(.{1,76})/$1$end_of_line/g;
   }
   

5. Finally, returns the base64-encoded string.

   $encoded
   

   What results is a file that looks like gibberish when not viewed with software capable of parsing base64-encoded content. MIME and the base64 encoding scheme are an ingenious way of transmitting multiple segments of mixed data between individuals who are using software capable of decoding these messages.

#!/usr/local/bin/perl -w

### Script: test.b64

use MIME::Base64 ();

        ### clear text string
$to_encode = "There once was the good Duke of Earl,\n".
             "who used to sit home and hack Perl.";

        ### output the clear text string
print("Clear String: \n". $to_encode ."\n");         

        ### Now, encode the clear text string, $to_encode
$encoded = MIME::Base64::encode($to_encode);

        ### Let's output the encoded string
print("\nEncoded: \n$encoded\n");

        ### decode the clear text string
$decoded = MIME::Base64::decode($encoded); 

        ### If all has gone okay, we're right back to where
        ### we started. Output the decoded string.
print("\nDecoded: \n".
                $decoded
                ."\n"); 

#!/usr/local/bin/perl -w

### Script name: test3.b64

use MIME::Base64 ();

$input = 'output.mime'; ### input file
$output_file = 'from_mime.gif'; ### output file

print("Base64-encoded file: $input\n");
print("Output image: $output_file\n");

open(INPUT, "$input") or die("Input file $input error: $!");
open(OUTPUT, ">$output_file") or die("Output file $output_file error: $!");

         ### Again, DON'T chop() lines from the input file. This will
         ### break the base64-encoding scheme for the input file and
         ### your output file will get corrupted!
while($line = <INPUT>) { 
    $decoded = MIME::Base64::decode($line); ### output decoded line
    print OUTPUT $decoded;

}

close(OUTPUT);
close(INPUT);

Handling Multipart Mixed Messages

When you add content to a multipart message, you're asking your mail program to map a Content-type to the extension of the filename you've included. If your mail program can't determine the Content-type of one of the files you've attached, most programs will use a default Content-type.

So, how's an ordinary mail message different from a multipart mail message?

Normal mail headers contain the following information: From, Date, Subject, and To. If I were to send myself a plaintext (nonencoded) mail message, with the subject "Here's looking at you, Nate," the headers would look like:

From nvp Wed Mar  5 20:34:43 1997
Received: (from nvp@localhost) by mail.somename.com (8.7.5/8.7.3) 
id UAA00505 for nvp; Wed, 5 Mar 1997 20:34:42 -0500 (EST)
Date: Wed, 5 Mar 1997 20:34:42 -0500 (EST)
From: "Nathan V. Patwardhan" <nvp>
Message-Id: <199703060134.UAA00505@mail.somename.com>
To: nvp
Subject: Here's looking at you, Nate
Status: RO

1. First, send a MIME header that announces our version of MIME.

   MIME-Version: 1.0
   

2. Next, send the Content-type and boundary for the document. Since our mail message will contain several different types of content, we'll use the multipart/mixed Content-type and define a boundary that will separate all the different parts we'll attaching to our message. The RFC documents state that a message's boundary must be preceded by two dashes for each of the message's boundaries, and that the message's ending boundary must also contain two trailing dashes, so we'll start with the boundary shown below.

   Content-Type: multipart/mixed; boundary = "--someboundaryhere"
   

3. Now, start adding content to our multipart message, which follows a line of text that reads like the following:

   This is a multipart message in MIME format.
   

4. Each section of content that appears in a multipart message is denoted by the boundary shown above and formatted with the Content-Type, filename, Content-Transfer-Encoding, and Content-Disposition of the attachment included in the section.

   --someboundaryhere
   Content-Type: format/type; name="filenamehere"
   Content-Transfer-Encoding: base64
   Content-Disposition: inline; filename="filenamehere"
   

5. Finally, we'll end the multipart message by sending an ending boundary denoted by the two trailing slashes described in the RFC.

   --someboundaryhere--
   

#!/usr/local/bin/perl -w

# we'll need this to check filenames
use File::Basename;
# needed for Base64 encoding
use MIME::Base64;

# the mail program we'll be using for sending
$mailprog = '/usr/lib/sendmail';

# the subject of our mail message
$subject = 'This is a test message in MIME format';

# who'll be receiving our mail message
$recip = 'nvp@ora.com';

# okay, let's generate a boundary for each section
# of the multipart mail message
$bndry = encode_boundary($subject);

open(MAILER, "|".$mailprog." -t ".$recip)
     or die("error opening $mailprog: $!");
print MAILER "To: $recip\n";
print MAILER "X-Mailer: $0/1.0\n";
print MAILER "MIME-Version: 1.0\n";
print MAILER "Content-Type: multipart/mixed;".
          "boundary=\"".$bndry."\"\n\n";
print MAILER "This is a multi-part message in MIME format.\n";

# now, let's do something with each @ARGV member if it's a file
# other entries will be treated as body text in the message
for(@ARGV) {
    # if it's a file, let's encode the contents and
    # send them to the mailer
    if(-e $_) {
        undef $/;
        open(IN, $_) or die("no: $!"); $enc = <IN>; close(IN);
         $encoded = MIME::Base64::encode($enc);
        print $encoded."\n";
        print MAILER<<TYPE;
$bndry
Content-Type: application/octet-stream; name="$_"
Content-Transfer-Encoding: base64
Content-Disposition: inline; filename="$_"

$encoded
TYPE
} else {
# otherwise, we'll send the contents to
# the mailer as-is
print MAILER<<TEXT;
$bndry
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

$_
TEXT
}
}

# okay, we're done sending the parts.
# let's send the ending boundary
print MAILER $bndry.'--'."\n\n";
close(MAILER);

# subroutine to encode a boundary. There are *much* better ways
# to do this, but this subroutine is offered only for illustration
sub encode_boundary {
    my $boundary = shift;
    $boundary =~ s/(\s+)//g;
    $boundary = '------------'.substr(pack('u', $boundary), 0, 24);
    return $boundary;
}

# ok, if the entity name has an extension, we'll attach it as a file
# if it doesn't have an extension, we'll attach it as-is
sub do_part {
    my $part = shift;
    my($ext) = fileparse($part);

    unless(defined($ext)) {
        return undef;
    } else {
        return $ext;
    }
}

Create Simple Attachments with MIME::Lite

Let's start with MIME::Lite because of the lightweight nature of this module and straightforward API details that make it easy to get started writing applications with MIME::Lite. In fact, you can send email with an attachment using MIME::Lite in three steps:

1. Use this module.

   use MIME::Lite;
   

2. Create a MIME::Lite object and pass it the necessary header information so that the file(s) can be included.

   $object = MIME::Lite->new(
       From     =>'nvp@somemail.com',
       To       =>'recipient@theirdomain.com',
       Cc       =>'do you want to copy anyone?',
       Subject  =>'What\'s your favorite subject',
       Type     =>'mime type here',
       Encoding =>'encoding type here - base64 for binaries',
       Path     =>'path and name of file here');
   

3. Send the message. You can represent the message as a string with as_string and send $show_string to STDOUT:

   $show_string = $object->as_string;
   print $show_string."\n";
   

   Or, send the message through a filehandle:

   $object->print(\*SENDMAIL);
   

   Assuming you're on a UNIX system, you can send the message directly to sendmail without using a filehandle:

   $object->send;
   

   As you noticed from the example above, it's not difficult to send an email message containing one attachment with MIME::Lite. But what about multipart messages?

   MIME::Lite uses the attach() method to add parts to a multipart message. Since you aren't able to add multiple parts to the MIME::Lite constructor, like so,

   # WRONG! - DON'T DO THIS
   
   $message = MIME::Lite->new(
       From     => 'nvp@somemailhost.com',
       To       => 'recipient@someotherhost.com',
       Subject  => 'Stop hitting me!',
       Type     => 'multipart/mixed',
       Type     => 'image/gif',
       Encoding => 'base64',
       Path     => 'some_useless_animated_and_blinking.gif',
       Type     => 'image/jpeg',
       Encoding => 'base64',
       Path     => 'another_senseless.jpg');
   

   you must add a multipart/mixed type to the constructor, then add each part with the attach() method. For example, you can create a multipart message with an attached GIF, JPEG, and body text with the following steps.

4. First, tell MIME::Lite that it's going to be adding parts to a message by setting the Content-type to multipart/mixed.

   $message = MIME::Lite->new(
       From    => 'nvp@somemailhost.com',
       To      => 'recipient@sybil-has-multiple-parts-too.com',
       Subject => 'GIF and JPEG for you!',
       Type    => 'multipart/mixed');
   

5. Now, use attach to add the first attachment to the mail message, a GIF.

   attach $message
       Type     => 'image/gif',
       Path     => '/the/path/less/traveled',
       Filename => 'some_gif_to_add.gif';
   

6. Next, use attach to add another attachment to the mail message, a JPEG.

   attach $message
       Type     =>'image/jpeg',
       Path     =>'/the/path/slightly/less/traveled',
       Filename =>'some_jpeg_to_add.jpg';
   

7. After you've finished adding parts to the message, send the contents of the message to STDOUT. This is helpful if you want to debug the contents of your message before sending it to someone. For example, it would be embarrassing to accidentally send something bawdy to a person who didn't appreciate bawdy content.

   $check_message_for_smut = $msg->as_string;
   print $check_message_for_smut."\n";
   

8. Finally, after you've ensured that your message is syntactically and "morally" correct, you can send it. Since you're probably running a UNIX flavor that supports the send() method, we'll use that:

   $message->send;
   

   Other MIME::Lite methods that come in handy when debugging email messages are header_as_string() and body_as_string(). Like their method names indicate, header_as_string() outputs the header of an email message created with MIME::Lite, and body_as_string() outputs the body of an email message created with MIME::Lite. Both are used like as_string():

   # Show us your body
   $body_not_bawdy = $message->body_as_string;
   print $body_not_bawdy."\n";
   
   # Show us your header
   $header_how_are_you = $message->header_as_string;
   print $header_how_are_you."\n";
   

   Instead of using as_string(), body_as_string(), or header_as_string(), you can use print(FILEHANDLE), print_body(FILEHANDLE), or print_header(FILEHANDLE). For example, if you wanted to output the contents of an email message to a file before sending the email, you could do the following:

   $outfile = '/path/output_file_name';
   open(OUTFILE, ">".$outfile)
       or die("output file $outfile error: $!");
   $message->print(\*OUTFILE);
   close(OUTFILE);
   

Header Hacking with MIME::Lite

$message = MIME::Lite->new(
    From    => 'nvp@somemailhost.com',
    To      => 'recipient@sybil-has-multiple-parts-too.com',
    Subject => 'GIF and JPEG for you!',
    Type    => 'multipart/mixed');

$object->add(Header-Type => 'value');

$message->add(CC => 'user@host1.com, user@host2.com');

$object->replace(Header-Type => 'new-header-value');

The remainder of this chapter discusses the modules distributed with the MIME-tools package. The MIME-tools package was also written by Eryq (eryq@enteract.com), and features a MIME header parser and multipart message generator similar to that in MIME::Lite. You'll want to use the MIME-tools package for any application you'll write that needs to both parse and create multipart MIME messages as well as manipulate mail header fields and their respective values.

More Robust Attachments with MIME::Entity

Remember the $message object we used in the MIME::Lite examples? Let's re-write it so it can be used with MIME::Entity.

1. First, you'll notice that new has been replaced with build. Since we'll be building a multipart message, we'll need the build method to get us started. You'll also notice that the message's type (multipart/mixed) doesn't appear as a named parameter like From, To, Subject, and Type. If you don't create your $message object properly, you'll get an error message that looks something like the following.

   can't build entity: no body, and not multipart! at 
   /usr/local/lib/perl5/site_perl/MIME/Entity.pm line xxx.
   

   Your MIME::Entity constructor should look like this:

   my $message = MIME::Entity->build(
       Type     =>"multipart/mixed",
       -From    => 'nvp@somemailhost.com',
       -To      => 'recipient@parts-are-parts.com',
       -Subject => 'GIF and JPEG for you!',
       -Type    => 'multipart/mixed');
   

2. Now it's time to attach content to the message. You'll be using the attach method as you did with MIME::Lite.

   attach $message
       Path => '/path/to/content',
       Type => 'whatever/whatever',
       Encoding => 'base64';
   

   For example, you could attach a GIF to your message with:

   attach $message
       Path => '/home/nvp/some_nutty_image.gif',
       Type => 'image/gif',
       Encoding => 'base64';
   

3. After you've added the content you wanted, you can send the mail message. Unlike MIME::Lite, MIME::Entity doesn't implement a send method, so you'll need to open an external m ail program to send your mail. The print method takes a filehandle as an argument, so you can open a pipe to your mail program in a filehandle and print the contents of the MIME message using the print method.

   open(MAILER, "|mailprogram params")
       or die("mailer error: $!");
   $message->print(\*MAILER);
   close(MAILER);
   

4. Let's put it all together in this example.

   #!/usr/local/bin/perl -w
   
   use MIME::Entity;
   
   # the mail program of choice
   $mailprog = '/usr/lib/sendmail';
   
   # who the mail is from, to, and the subject of this message
   $from = 'wwwmailer@mimetest.com';
   $to = 'nvp@mail.somename.com';
   $subject = 'Looks like a runner!';
   
   # files to attach
   $text_attach = '/home/nvp/.cshrc';
   $img_attach = '/home/nvp/Perl/PRK/MIME/scripts/mygif.gif'; 
   
   # Text to place at the end of the message (after the other attachments)
   $message = 'This is the end of the message.';
   
   # Create the object, and set up the mail headers:
   $message = MIME::Entity->build(
       Type     =>"multipart/mixed",
       -From    => "$from",
       -To      => "$to",
       -Subject => "$subject");
   
   # Attachment #1: a simple text document: 
   attach $message  Path=>"$text_attach";
   
   # Attachment #2: a GIF file:
   attach $message  Path        => "$img_attach",
       Type        => "image/gif",
       Encoding    => "base64";
   
   # Attachment #3: some literal text:
   attach $message  Data=>$message;
   
   # Send it!
   open(MAIL, "|$mailprog -t $to") 
       or die("mail open $mailprog error: $!");
   $message->print(\*MAIL);
   close(MAIL);
   

Parsing MIME Messages with MIME::Parser

1. The new() method, the constructor, is needed to create a MIME::Parser object.

   $object = new MIME::Parser;
   

2. Next, the output_dir() method tells MIME::Parser where you'll be depositing the entities you've parsed from the multipart message.

   $output_to_dir = '/path/to/put/files';
   $object->output_dir($output_to_dir);
   

3. Now, use the output_prefix() method that tells MIME::Parser to append a certain prefix to the entities it extracts from the multipart message. If you choose not to add a prefix to the output files, the filenames default to the names listed in the boundary sections of the multipart message.

   $default_prefix = 'entity_oh_my_goodness';
   $object->output_prefix($default_prefix);
   

4. You'll need to read an input file containing the multipart message to be parsed. MIME::Parser's read() method reads from a filehandle and assigns the data to a scalar.

   open(INPUT, $input) 
       or die("Input $input error: $!");
   my $entity = $object->read(\*INPUT) 
       or die "couldn't parse MIME stream";
   close(INPUT);
   

5. When you're ready to parse and output entities from the file, you'll need the output_to_core() method, which outputs the entities of a MIME message to the filesystem.

   $object->output_to_core;
   

   MIME::Parser can run silently. That is, you don't have to read what MIME::Parser tells you has been decoded. Although you should use any and all capabilities to debug your program's output, you don't have to use MIME::Parser's dump_skeleton() method that outputs something similar to:

   Content-type: multipart/mixed
   Body-file: NONE
   Subject: Mail message with MIME attachment.
   Num-parts: 2
   --
       Content-type: text/plain
       Body-file: /tmp/get_mime.pl-12113-1.doc
       --
       Content-type: image/gif
       Body-file: /tmp/tiffany.gif
       --
   

#!/usr/local/bin/perl -w

# for our MIME parsing needs
use MIME::Parser;

# for our filename/path parsing needs
use File::Basename;

# please use me - i like it!
use strict;

# where to put the decoded parts
my $output_path = '/tmp';

# derive the base filenames of extracted parts from
# the name of the script. uses basename method of
# File::Basename.yippee.
my ($parsed) = (basename($0))[0];

# our input file, a multipart message
my $input_file = '/tmp/mime.head';

my $parser = MIME::Parser->new();

# output directory for parsed files
$parser->output_dir($output_path);

# Basenames for parsed files
$parser->output_prefix($parsed);

# KEY PART: Now, write the entities (parsed from boundaries) 
# to the filesystem
$parser->output_to_core();

# Parse the input file: (which can be @ARGV if you want it to be!)
open(INPUT, "$input_file") or die("Input error: $!");
my $entity = $parser->read(\*INPUT) 
    or die "couldn't parse MIME stream";
close(INPUT);

# Tell us about the MIME entities!  You can suppress
# this if you don't want output for the sake of debugging
$entity->dump_skeleton;          # for debugging 

[2] Mail::Folders enables you to read, write, add, save, and delete messages from your existing mail folders reliably as of Mail::Folder Version 0.06 and Perl Version 5.004_01.

Return to Table of Contents