METHODS

Constructors

$obj->dup

Duplicate the message as a whole. Both header and body will be deep-copied: a new Mail::Internet object is returned.

$obj->extract( ARRAY-of-LINES )

Extract header and body from an ARRAY of message lines. Requires an object already created with new(), which contents will get overwritten.

$obj->new( [ARG], [OPTIONS] )
$class->new( [ARG], [OPTIONS] )

ARG is optional 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.

The Mail::Header::new() OPTIONS Modify, MailFrom and FoldLength may also be given.

Option Default

Body

[]

Header

undef

Body => ARRAY-of-LINES
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).
Header => Mail::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.
$obj->read( FILEHANDLE )

Read a message from the FILEHANDLE into an already existing message object. Better use new() with the FILEHANDLE as first argument.

Accessors

$obj->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 reference to an array or an array, then the body will be replaced. If a reference is passed, it is used directly and not copied, so any subsequent changes to the array will change the contents of the body.

Processing the message as a whole

$obj->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.

$obj->as_string

Returns the message as a single string.

$obj->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.

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

Processing the header

Most of these methods are simply wrappers around methods provided by Mail::Header.

$obj->add( PAIRS-of-FIELD )

The PAIRS are field-name and field-content. For each PAIR, Mail::Header::add() is called. All fields are added after existing fields. The last addition is returned.

$obj->combine( TAG, [WITH] )

See Mail::Header::combine().

$obj->delete( TAG, [TAGs] )

Delete all fields with the name TAG. Mail::Header::delete() is doing the work.

$obj->fold( [LENGTH] )

See Mail::Header::fold().

$obj->fold_length( [TAG], [LENGTH] )

See Mail::Header::fold_length().

$obj->get( TAG, [TAGs] )

In LIST context, all fields with the name TAG are returned. In SCALAR context, only the first field which matches the earliest TAG is returned. Mail::Header::get() is called to collect the data.

$obj->replace( PAIRS-of-FIELD )

The PAIRS are field-name and field-content. For each PAIR, Mail::Header::replace() is called with INDEX 0. If a FIELD is already in the header, it will be removed first. Do not specified the same field-name twice.

Processing the body

$obj->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.

$obj->sign( OPTIONS )

Add your signature to the body. remove_sig() will strip existing signatures first.

Option Default

File

undef

Signature

[]

File => FILEHANDLE
Take from the FILEHANDLE all lines starting from the first < -- >.
Signature => STRING|ARRAY-of-LINES
$obj->tidy_body

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

High-level functionality

$obj->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 any line that matches the regular expression /^*From/>

$obj->nntppost( [OPTIONS] )

Post an article via NNTP. Requires Net::NNTP to be installed.

Option Default

Debug

<false>

Host

<required>

Port

119

Debug => BOOLEAN
Debug value to pass to Net::NNTP, see manual Net::NNTP
Host => HOSTNAME|Net::NNTP object
Name of NNTP server to connect to, or a Net::NNTP object to use.
Port => INTEGER
Port number to connect to on remote host
$obj->reply( OPTIONS )

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.

The .mailhdr file in your home directory (if exists) will be read first, to provide defaults.

Option Default

Exclude

[]

Indent

'>'

Keep

[]

ReplyAll

false

Exclude => ARRAY-of-FIELDS
Remove the listed FIELDS from the produced message.
Indent => STRING
Use as indentation string. The string may contain %% to get a single %, %f to get the first from name, %/code is the first character of %f, %l is the last name, %L its first character, %n the whole from string, and %/code the first character of each of the names in the from string.
Keep => ARRAY-of-FIELDS
Copy the listed FIELDS from the original message.
ReplyAll => BOOLEAN
Automatically include all To and Cc addresses of the original mail, excluding those mentioned in the Bcc list.
$obj->send( [TYPE, [ARGS...]] )

Send a Mail::Internet message using Mail::Mailer. TYPE and ARGS are passed on to Mail::Mailer::new().

$obj->smtpsend( [OPTIONS] )

Send a Mail::Internet message using direct SMTP. 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.

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.

Requires Net::SMTP and Net::Domain to be installed.

Option Default

Bcc

undef

Cc

undef

Debug

<false>

Hello

localhost.localdomain

Host

$ENV{SMTPHOSTS}

MailFrom

Mail::Util::mailaddress()

Port

25

To

undef

Bcc => ADDRESSES
Cc => ADDRESSES
Debug => BOOLEAN
Debug value to pass to Net::SMPT, see <Net::SMTP>
Hello => STRING
Send a HELO (or EHLO) command to the server with the given name.
Host => HOSTNAME
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.
MailFrom => ADDRESS
The e-mail address which is used as sender. By default, Mail::Util::mailaddress() provides the address of the sender.
Port => INTEGER
Port number to connect to on remote host
To => ADDRESSES
$obj->unescape_from( () )

Remove the escaping added by escape_from().