14.2 The Mail Modules (Perl in a Nutshell)

14.2 The Mail Modules

The Mail modules operate at a higher level than the Net modules, interacting with external mail packages such as mail, mailx, sendmail, or a POP3 server in the case of POP3Client. This section describes some of the MailTools modules, Mail::Folder, and Mail::POP3Client.

14.2.1 Send Email with Mail::Mailer

The Mail::Mailer module interacts with external mail programs. When you use Mail::Mailer or create a new Mail::Mailer object, you can specify which mail program you want your program to talk to:

use Mail::Mailer qw(mail);

Another way to specify the mailer is:

use Mail::Mailer;
$type = 'sendmail';
$mailprog = Mail::Mailer->new($type);

where $type is the mail program. Once you've created a new object, use the open function to send the message headers to the mail program as a hash of key/value pairs, where each key represents a header type, and where the value is the value of that header:

# mail headers to use in the message
%headers = (
    'To' => 'you@mail.somename.com',
    'From' => 'me@mail.somename.com',
    'Subject' => 'working?'
);

This code represents headers where the recipient of the mail message is you@mail.somename.com, the mail was sent from me@mail.somename.com, and the subject of the mail message is "working?"

Once %headers has been defined, it is passed to open:

$mailprog->open(\%headers);

You then send the body of the message to the mail program:

print $mailprog "This is the message body.\n";

Now, close the program when the message is finished:

$mailprog->close;

A practical example of using Mail::Mailer might be a command-line-driven application that works much like the Unix mail program, either reading STDIN until EOF or mailing a file specified on the command line.

Mail::Mailer uses the environment variable PERL_MAILERS to augment or modify the built-in mailer selection. PERL_MAILERS is specified in the following format:

"type1:mailbinary1;mailbinary2;...:type2:mailbinaryX;...:..."

The possible types are listed for the new method below.

The following methods are defined in Mail::Mailer:

14.2.2 Better Header Control with Mail::Send

Mail::Send is built on top of Mail::Mailer, which means that you can also choose the mail program that sends the mail. Mail::Send has implemented the methods to, cc, bcc, and subject to replace the %headers hash used in Mail::Mailer.

Mail::Send uses the open method to open the mail program for output; it is built on Mail::Mailer's new method, so that:

# Start mailer and output headers
$fh = $msg->open('sendmail');

serves the same purpose as:

# use sendmail for mailing
$mailer = Mail::Mailer->new('sendmail)';

This code tells Mail::Send to use sendmail as the mail program.

Mail::Send also provides the set and add functions, which assign a value to a header tag and append a value to a header tag, respectively. The set function takes two arguments - a header tag and a value - and is used like this:

$msg->set($scalar, @array);

Therefore, to address a message to you@mail.somename.com:

$msg->set('To', 'you@mail.somename.com');

The above sets the To header to you@mail.somename.com; however, the following sets the To header to postmaster@mail.somename.com and you@mail.somename.com, because they represent an array of values.

$msg->set('To', ('you@mail.somename.com', 'postmaster@mail.somename.com'));

You might think that you could use the set function as follows to add multiple values to a header value:

$msg->set('To', 'you@mail.somename.com');
$msg->set('To', 'someone@their.mailaddress.com');

However, set doesn't append information from one call to another, and the example above would send the mail only to someone@their.mailaddress.com. To append a name to the To header, use the add method. For example:

$msg->add('To', 'you@mail.somename.com');
$msg->add('To', 'someone@their.mailaddress.com');

The following methods are defined for Mail::Send:

14.2.3 Handle Folders with Mail::Folder

Once you've begun downloading and reading your mail from a POP server, you might want to save or categorize your messages into folders, which allow you to add, delete, save, and move messages easily. You can do this with Mail::Folder, which was written by Kevin Johnson as an object-oriented, folder-independent interface to mail folders. Mail::Folder supports a number of mailbox formats with the following interfaces:

Mail::Folder::Emaul: A folder interface somewhat similar to MH.
Mail::Folder::Maildir: An interface to maildir folders.
Mail::Folder::Mbox: Standard Unix mailbox format.
Mail::Folder::NNTP: The beginnings of an interface to NNTP; not all the methods are implemented yet.

If you are interested in writing a folder interface, see the documentation for the module. The documentation explains the concepts and issues involved, and describes some of the methods you may need to override.

The following methods are defined for Mail::Folder:

14.2.4 Handle Messages with Mail::Internet

Mail::Internet implements a number of helpful functions for manipulating a mail message. These include body, print_header, and head. Mail::Internet is built on top of Mail::Header, which parses the header of an email message, and it 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]);

reads a mail message from STDIN (using a reference to an array). The following example reads a mail message from a filehandle, FILE.

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

The print_header function outputs the header of a message to a file descriptor; the default is STDOUT.

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

The above example might output:

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

where print_body also takes a file descriptor as an argument, but only outputs the body of the message, whereas the print function outputs an entire message.

14.2.5 Mail::Internet Reference

14.2.6 Parse Email Addresses with Mail::Address

Mail::Address parses RFC 822-compliant mail addresses of the form:

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

For example, under RFC 822, an address might be represented as:

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

or:

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

The Mail::Address constructor parses an email address into three parts based on the categories shown above:

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

Mail::Address also outputs portions of the mail address with the functions phrase, address, comment, format, name, host, and user. The phrase, address, and comment functions represent the first, second, and third entities that were passed to the Mail::Address constructor, where the phrase function:

print $addr->phrase();

outputs:

Nathan V. Patwardhan

The address function:

print $addr->address();

outputs:

nvp@mail.somename.com

And the comment function:

print $addr->comment();

outputs:

No Comment

A real mail address can be "unmangled," or parsed from its user@somehost.com format, with the user and host functions. The user function removes everything starting with the @ to the end of the address, and host removes everything up to and including the @. Using the previous example of nvp@mail.somename.com, the following line:

print $addr->user;

outputs:

nvp

And the following line using the host function:

print $addr->host;

outputs:

nvp@mail.somename.com

14.2.7 Mail::Address Reference

14.2.8 Reading Email with Mail::POP3Client

Many networks have machines dedicated to sending and receiving email. Since users might hold accounts on foo.bar.com, while mail is sent to pop-server.bar.com, there must be a means to transfer the mail from the "post office" machine to the host on which the user works. The Post Office Protocol, or POP, negotiates this mail transfer.

When a user wants to retrieve his or her mail, the user's mail client connects to the POP server and authenticates the user with a login name and password, as we described earlier. Once authenticated, the user can list, read, and delete messages from the POP server.

The Mail::POP3Client module simplifies the process of "talking POP" by implementing a number of functions to login, parse, and read mail messages held on the POP server. Information that the POP server needs, such as the user's login name and password, and possibly some optional information (the name of the POP host, the port, and a debugging flag) are passed to the constructor when a new POP3Client object is created. For example:

use Mail::POP3Client;

$pop = Mail::POP3Client->new("login",     # required
                             "password",  #required
                             "pophost.your.domain", # not required
                             port,        # default is 110
                             debug_flag); # any positive integer

POP3Client provides functions to perform the following:

14.2.8.1 Counting messages

The Count function returns the number of messages in the mailbox. Once they have been authenticated, users can list the headers of the messages in their mailbox using the Head function in conjunction with the Count function, as shown in the following example:

use strict; 
use Mail::POP3Client;
my($pop, $num_mesg, $i);
$pop = Mail::POP3Client->new("nvp",
                            "xxxxxx");

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

for ($i = 1; $i <= $num_mesg; $i++) {
    print $pop->Head($i), "\n";   #print header for each message
}

You can also use a regular expression to parse the headers and display certain information, such as the sender and subject of each mail message:

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

$pop = Mail::POP3Client->new("nvp",
                            "xxxxxx");

for ($i = 1; $i <= $pop->Count; $i++) {
    foreach ($pop->Head($i)) {
               # output from and subject 
        print $_." " if /^(From|Subject)/;
   }
    print "\n";
}

14.2.8.2 Getting and setting the host and port

The Host method returns or sets the current POP host. For example:

$obj->Host;

returns the current POP host. To set the new POP host to new-pop.bar.com, you could do this:

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

The Port method works like Host, returning or setting the current port that the POP server is bound to:

$obj->Port;            #return the current port for the POP server
$new_port = 7000;      #set the port to 7000
$obj->Port($new_port);

14.2.8.3 Retrieving the message body

Naturally, you'll want to read more than the headers of your mail messages, so you'll want to use the Body, HeadAndBody, and Retrieve methods. Body outputs the body of the message, while HeadAndBody and Retrieve are synonyms that output both the head and the body of the message.

14.2.8.4 Deleting and undeleting messages

Messages can be deleted from the POP mailbox with the Delete method. Delete marks messages on the server for deletion; they aren't permanently removed until a QUIT command is received. Delete takes one argument - the number of the message to delete:

$pop->Delete(1);         #delete the first message

Like most mail programs, Mail::POP3Client can undelete messages that have been marked for deletion. Use the Reset method to do this:

$pop->Reset(1);          #undelete the first message

14.2.8.5 Checking the connection

Most programs that require a user to log in will time out after a certain period of time for security and resource reasons. The Alive method checks to see if the connection to the POP server is still open; it returns true if the connection is good, and false otherwise.

14.2.8.6 Explicitly opening and closing connections

POP connections can be explicitly opened and closed with Login and Close. Close takes no arguments and closes the connection to the POP server.

14.2.9 Mail::POP3Client Methods

The following methods are defined by Mail::POP3Client:


14.1 The Net Modules		15. Usenet News