[Chapter 14] 14.2 The Mail Modules
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T01:56:39Z

#

| Chapter 14 Email Connectivity |

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

- new
- close
- open

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

- new
- add
- bcc
- cancel
- cc
- close
- delete
- open
- set
- subject
- to

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

- new
- add_label
- append_message
- clear_label
- close
- current_message
- debug
- debug_print
- delete_label
- delete_message
- dup
- first_labeled_message
- first_message
- foldername
- get_fields
- get_header
- get_message
- get_message_file
- get_mime_header
- get_mime_message
- get_option
- inverse_select
- is_readonly
- label_exists
- last_labeled_message
- last_message
- list_all_labels
- list_labels
- message_exists
- message_list
- next_labeled_message
- next_message
- open
- pack
- prev_labeled_message
- prev_message
- qty
- refile
- select
- select_label
- set_option
- set_readonly
- sort
- sync
- undelete_message
- update_message

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

- new
- add_signature
- body
- escape_from
- head
- nntppost
- print_header
- remove_sig
- reply
- smtpsend
- tidy_body
- unescape_from

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

- new
- parse
- address
- canon
- comment
- format
- host
- name
- path
- phrase
- user

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

- new
- Alive
- Body
- Close
- Connect
- Count
- Delete
- Head
- HeadAndBody
- Host
- Last
- List
- Login
- Message
- Pass
- POPStat
- Port
- Reset
- Retrieve
- Size
- Socket
- State
- User

14.1 The Net Modules |  | 15. Usenet News