MailTools is a set of modules that, together, provide the ability to parse parts of mail messages and related files. MailTools was primarily written by Graham Barr ([email protected]).

Modules are included to parse address fields (Address), parse mailcap files (Cap), and filter mail (Filter). The Mail::Field and Header modules allow for the parsing and creation of mail message headers.

Simple text RFC 822 messages may be created or parsed using Mail::Internet. Mail::Mailer provides a Perl interface to the Unix mail or sendmail utilities for sending a message once it has been created. Mail::Util includes a way to read mbox format mailboxes.

The complete list of files in MailTools is:

Version Documented: 1.11 dated 02 January 1998

The dependencies for MailTools are as follows:

MailTools provides the following modules, which are listed with a synopsis of each:

Mail::Address Synopsis:

Constructors:
    Address new (String phrase, String address)
    Address new (String name, String address, String comment)

Public instance methods:
    String phrase (Address address)
    String address (Address address)
    String comment (Address address)
    String format (Address address)
    String name (Address address)
    String host (Address address)
    String user (Address address)
    String path (Address address)    # unimplemented
    String canon (Address address)   # unimplemented
    String[] parse (Address address, String line)

Mail::Cap Synopsis:

Constructors:
    Cap new ()
    Cap new (String filename)

Public instance methods:
    boolean view (Cap mailcap, String mime_type, String filename)
    boolean compose (Cap mailcap, String mime_type, String filename)
    boolean edit (Cap mailcap, String mime_type, String filename)
    boolean print (Cap mailcap, String mime_type, String filename)
    String viewCmd (Cap mailcap, String mime_type, String filename)
    String composeCmd (Cap mailcap, String mime_type, String filename)
    String editCmd (Cap mailcap, String mime_type, String filename)
    String printCmd (Cap mailcap, String mime_type, String filename)
    String field (Cap mailcap, String mime_type, String field)
    String description (Cap mailcap, String mime_type)
    String textualnewlines (Cap mailcap, String mime_type)
    String x11_bitmap (Cap mailcap, String mime_type)
    String nametemplate (Cap mailcap, String mime_type)

Mail::Field Synopsis:

Constructors:
    Field new (String tag)
    Field new (String tag, String value)
    Field new (String tag, String value, String[] options)
    Field[] extract (String tag, Mail::Head head)
    Field[] extract (String tag, Mail::Head head, String[] options)
    Field combine (String[] list_of_Field_objects)

Public instance methods:
    String parse (Field field)
    String tag (Field field)
    String stringify (Field field)

Mail::Filter Synopsis:

Constructors:
    Filter new ()
    Filter new (SubroutineRef[] filters)

Public instance methods:
    boolean add (Filter filter, SubroutineRef[] filters)
    boolean filter (Filter filter, Mail::Internet message)
    boolean filter (Filter filter, Mail::Folder folder)
    Folder folder (Filter filter)
    int msgnum (Filter filter)

Mail::Header Synopsis:

Constructors:
    Header new ()
    Header new (Filehandle handle)
    Header new (String[] array)
    Header new (Filehandle handle, String[] options)
    Header new (String[] array, String[] options)

Public instance methods:
    String modify (Header header)
    String modify (Header header, boolean value)
    Header mail_from (Header header, String option)
    Header fold (Header header)
    Header fold (Header header, int length)
    Header extract (Header header, String[] array)
    Header read (Header header, Filehandle handle)
    Header empty (Header header)
    String[] header (Header header)
    String[] header (Header header, String[] array)
    String add (Header header, String tag, String value)
    String add (Header header, String tag, String value, int index)
    String replace (Header header, String tag, String value)
    String replace (Header header, String tag, String value, int index)
    String combine (Header header, String tag)
    String combine (Header header, String tag, int width)
    String get (Header header, String tag)
    String get (Header header, String tag, int index)
    String[] delete (Header header, String tag)
    String[] delete (Header header, String tag, int index)
    int count (Header header, String tag)
    boolean print (Header header, Filehandle handle)
    int fold_length (Header header)
    int fold_length (Header header, String tag)
    int fold_length (Header header, String tag, int length)
    String[] tags (Header header)
    Header dup (Header header)
    Header cleanup (Header header)
    Header unfold (Header header)
    Header unfold (Header header, String tag)

Mail::Internet Synopsis:

Constructors:
    Internet new ()
    Internet new (Filehandle handle)
    Internet new (String[] ref)
    Internet new (Filehandle handle, String[] options)
    Internet new (String [] ref, String [] options)

Public instance methods:
    String[] body (Internet internet)
    boolean print_header (Internet internet)
    boolean print_header (Internet internet, Filehandle handle)
    boolean print_body (Internet internet)
    boolean print_body (Internet internet, Filehandle handle)
    boolean print (Internet internet)
    boolean print (Internet internet, Filehandle handle)
    Mail::Header head (Internet internet)
    boolean remove_sig (Internet internet)
    boolean remove_sig (Internet internet, int num_lines)
    String tidy_body (Internet internet)
    Internet reply (Internet internet)
    Internet add_signature (Internet internet)
    Internet add_signature (Internet internet, String filename)
    boolean smtpsend (Internet internet)
    boolean nntppost (Internet internet)
    boolean nntppost (Internet internet, String[] options)
    String escape_from (Internet internet)
    String unescape_from (Internet internet)

Mail::Mailer Synopsis:

Constructors:
    Mailer new ()
    Mailer new (String type, String[] args)

Public instance methods:
    Mailer open (Mailer mailer, hashtable headers)
    null close (Mailer mailer)

Mail::Send Synopsis:

Constructors:
    Send new ()
    Send new (String[] headers)

Public instance methods:
    boolean to (Send send, String to)
    boolean subject (Send send, String subject)
    boolean cc (Send send, String cc)
    boolean bcc (Send send, String bcc)
    String[] set (Send send, String header, String[] values)
    boolean add (Send send, String header, String[] values)
    boolean delete (Send send, String header)
    Filehandle open (Send send)    # Closing this handle sends the message

Mail::Util Synopsis:

Public instance methods:
    String[] [] read_mbox (String filename)
    String maildomain ()
    String mailaddress ()

The following example uses the Cap.pm module from MailTools to determine how a GIF image should be viewed and then view it. This might be used by an MUA to display the results of a MIME decoding from a message.

# Use the MailTools module Cap.pm to read a mailcap.file.
use Mail::Cap;

# Create a mailcap object. Without arguments, the constructor tries # to find the mailcap file in the
usual places, or by the # MAILCAPS file. If it is somewhere else, pass in a filename.
my $mailcap = new Mail::Cap;

# Output a GIF file to the appropriate uiewer (e.g. xu).
$cmd = $mailcap->view('image/gif', 'flowers.gif'),

# $cmd will be 1 if a handler was found for image/gif files, # 0 otherwise. $? will inform us of the
result of the # program that was executed to view the image.
die "ERROR: No command for image/gif was found" unless $cmd;