NAME
    Mail::Internet - manipulate Internet format (RFC 822) mail messages

SYNOPSIS
        use Mail::Internet;

DESCRIPTION
    This package provides a class object which can be used for reading,
    creating, manipulating and writing a message with RFC822 compliant
    headers.

    If you start writing a new application, you may want to use the
    Mail::Box set of packages (requires perl 5.6.1), which has more
    features. See http://perl.overmeer.net/mailbox.

CONSTRUCTOR
    new ( [ ARG ], [ OPTIONS ] )
        "ARG" is optiona and may be either a file descriptor (reference to a
        GLOB) or a reference to an array. If given the new object will be
        initialized with headers and body either from the array of read from
        the file descriptor.

        "OPTIONS" is a list of options given in the form of key-value pairs,
        just like a hash table. Valid options are

        Header  The value of this option should be a "Mail::Header" object.
                If given then "Mail::Internet" will not attempt to read a
                mail header from "ARG", if it was specified.

        Body    The value of this option should be a reference to an array
                which contains the lines for the body of the message. Each
                line should be terminated with "\n" (LF). If Body is given
                then "Mail::Internet" will not attempt to read the body from
                "ARG" (even if it is specified).

        The Mail::Header options "Modify", "MailFrom" and "FoldLength" may
        also be given.

METHODS
    body ( [ BODY ] )
        Returns the body of the message. This is a reference to an array.
        Each entry in the array represents a single line in the message.

        If *BODY* is given, it can be a referenc to an aray or an array,
        then the body will be replaced. If a reference is passed, it is used
        directly and not copied, so any sunsequent changes to the array will
        change the contents of the body.

    print_header ( [ FILEHANDLE ] )
    print_body ( [ FILEHANDLE ] )
    print ( [ FILEHANDLE ] )
        Print the header, body or whole message to file descriptor
        *FILEHANDLE*. *$fd* should be a reference to a GLOB. If *FILEHANDLE*
        is not given the output will be sent to STDOUT.

            $mail->print( \*STDOUT );  # Print message to STDOUT

    as_string ()
        Returns the message as a single string.

    as_mbox_string ( [ ALREADY_ESCAPED ] )
        Returns the message as a string in mbox format. "ALREADY_ESCAPED",
        if given and true, indicates that ->escape_from has already been
        called on this object.

    head ()
        Returns the "Mail::Header" object which holds the headers for the
        current message

UTILITY METHODS
    The following methods are more a utility type than a manipulation type
    of method.

    remove_sig ( [ NLINES ] )
        Attempts to remove a users signature from the body of a message. It
        does this by looking for a line equal to '-- ' within the last
        "NLINES" of the message. If found then that line and all lines after
        it will be removed. If "NLINES" is not given a default value of 10
        will be used. This would be of most use in auto-reply scripts.

    tidy_body ()
        Removes all leading and trailing lines from the body that only
        contain white spaces.

    reply ()
        Create a new object with header initialised for a reply to the
        current object. And the body will be a copy of the current message
        indented.

    add_signature ( [ FILE ] )
        Append a signature to the message. "FILE" is a file which contains
        the signature, if not given then the file "$ENV{HOME}/.signature"
        will be checked for.

    send ( [ type [ args.. ]] )
        Send a Mail::Internet message using Mail::Mailer. Type and args are
        passed on to "Mail::Mailer"

    smtpsend ( [ OPTIONS ] )
        Send a Mail::Internet message via SMTP, requires Net::SMTP

        The return value will be a list of email addresses that the message
        was sent to. If the message was not sent the list will be empty.

        Options are passed as key-value pairs. Current options are

        Host
            Name of the SMTP server to connect to, or a Net::SMTP object to
            use

            If "Host" is not given then the SMTP host is found by attempting
            connections first to hosts specified in $ENV{SMTPHOSTS}, a colon
            separated list, then "mailhost" and "localhost".

        To
        Cc
        Bcc Send the email to the given addresses, each can be either a
            string or a reference to a list of email addresses. If none of
            "To", <Cc> or "Bcc" are given then the addresses are extracted
            from the message being sent.

        Hello
            Send a HELO (or EHLO) command to the server with the given name.

        Port
            Port number to connect to on remote host

        Debug
            Debug value to pass to Net::SMPT, see <Net::SMTP>

    nntppost ( [ OPTIONS ] )
        Post an article via NNTP, requires Net::NNTP.

        Options are passed as key-value pairs. Current options are

        Host
            Name of NNTP server to connect to, or a Net::NNTP object to use.

        Port
            Port number to connect to on remote host

        Debug
            Debug value to pass to Net::NNTP, see <Net::NNTP>

    escape_from ()
        It can cause problems with some applications if a message contains a
        line starting with `From ', in particular when attempting to split a
        folder. This method inserts a leading "`"'> on anyline that matches
        the regular expression "/^"*From/>

    unescape_from ()
        This method will remove the escaping added by escape_from

SEE ALSO
    Mail::Header Mail::Address

AUTHOR
    Graham Barr. Maintained by Mark Overmeer <mailtools@overmeer.net>

COPYRIGHT
    Copyright (c) 1995-2001 Graham Barr. All rights reserved. This program
    is free software; you can redistribute it and/or modify it under the
    same terms as Perl itself.

