388 lines
10 KiB
Plaintext
388 lines
10 KiB
Plaintext
|
=encoding utf8
|
||
|
|
|
||
|
|
=head1 NAME
|
||
|
|
|
||
|
|
Mail::Internet - manipulate email messages
|
||
|
|
|
||
|
|
=head1 SYNOPSIS
|
||
|
|
|
||
|
|
use Mail::Internet;
|
||
|
|
my $msg = Mail::Internet->new(\*STDIN);
|
||
|
|
|
||
|
|
=head1 DESCRIPTION
|
||
|
|
|
||
|
|
This package implements reading, creating, manipulating, and writing email
|
||
|
|
messages. Sometimes, the implementation tries to be too smart, but in
|
||
|
|
the general case it works as expected.
|
||
|
|
|
||
|
|
If you start writing a B<new application>, you should use the L<Mail::Box>
|
||
|
|
distribution, which has more features and handles messages much better
|
||
|
|
according to the RFCs. See L<http://perl.overmeer.net/mailbox/>.
|
||
|
|
You may also chose L<MIME::Entity>, to get at least some multipart
|
||
|
|
support in your application.
|
||
|
|
|
||
|
|
=head1 METHODS
|
||
|
|
|
||
|
|
=head2 Constructors
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<dup>()
|
||
|
|
|
||
|
|
Duplicate the message as a whole. Both header and body will be
|
||
|
|
deep-copied: a new L<Mail::Internet|Mail::Internet> object is returned.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<extract>(\@lines)
|
||
|
|
|
||
|
|
Extract header and body from an ARRAY of message lines. Requires an
|
||
|
|
object already created with L<new()|Mail::Internet/"Constructors">, which contents will get overwritten.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<new>( [$arg], [%options] )
|
||
|
|
|
||
|
|
=item Mail::Internet-E<gt>B<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 L<Mail::Header::new()|Mail::Header/"Constructors"> %options C<Modify>, C<MailFrom> and C<FoldLength>
|
||
|
|
may also be given.
|
||
|
|
|
||
|
|
-Option--Default
|
||
|
|
Body []
|
||
|
|
Header undef
|
||
|
|
|
||
|
|
=over 2
|
||
|
|
|
||
|
|
=item 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
|
||
|
|
C<\n> (LF). If Body is given then C<Mail::Internet> will not attempt to
|
||
|
|
read the body from C<$arg> (even if it is specified).
|
||
|
|
|
||
|
|
=item Header => Mail::Header
|
||
|
|
|
||
|
|
The value of this option should be a L<Mail::Header|Mail::Header> object. If given then
|
||
|
|
C<Mail::Internet> will not attempt to read a mail header from C<$arg>, if
|
||
|
|
it was specified.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<read>($fh)
|
||
|
|
|
||
|
|
Read a message from the $fh into an already existing message
|
||
|
|
object. Better use L<new()|Mail::Internet/"Constructors"> with the $fh as first argument.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=head2 Accessors
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<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 I<$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.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<head>()
|
||
|
|
|
||
|
|
Returns the C<Mail::Header> object which holds the headers for the current
|
||
|
|
message
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=head2 Processing the message as a whole
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<as_mbox_string>( [$already_escaped] )
|
||
|
|
|
||
|
|
Returns the message as a string in mbox format. C<$already_escaped>, if
|
||
|
|
given and true, indicates that L<escape_from()|Mail::Internet/"High-level functionality"> has already been called on
|
||
|
|
this object.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<as_string>()
|
||
|
|
|
||
|
|
Returns the message as a single string.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<print>( [$fh] )
|
||
|
|
|
||
|
|
Print the header, body or whole message to file descriptor I<$fh>.
|
||
|
|
I<$fd> should be a reference to a GLOB. If I<$fh> is not given the
|
||
|
|
output will be sent to STDOUT.
|
||
|
|
|
||
|
|
example:
|
||
|
|
|
||
|
|
$mail->print( \*STDOUT ); # Print message to STDOUT
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<print_body>( [$fh] )
|
||
|
|
|
||
|
|
Print only the body to the $fh (default STDOUT).
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<print_header>( [$fh] )
|
||
|
|
|
||
|
|
Print only the header to the $fh (default STDOUT).
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=head2 Processing the header
|
||
|
|
|
||
|
|
Most of these methods are simply wrappers around methods provided
|
||
|
|
by L<Mail::Header|Mail::Header>.
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<add>(PAIRS)
|
||
|
|
|
||
|
|
The PAIRS are field-name and field-content. For each PAIR,
|
||
|
|
L<Mail::Header::add()|Mail::Header/"Processing"> is called. All fields are added after
|
||
|
|
existing fields. The last addition is returned.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<combine>( $tag, [$with] )
|
||
|
|
|
||
|
|
See L<Mail::Header::combine()|Mail::Header/"Processing">.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<delete>( $tag, [$tags] )
|
||
|
|
|
||
|
|
Delete all fields with the name $tag. L<Mail::Header::delete()|Mail::Header/"Processing"> is doing the
|
||
|
|
work.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<fold>( [$length] )
|
||
|
|
|
||
|
|
See L<Mail::Header::fold()|Mail::Header/"Processing">.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<fold_length>( [$tag], [$length] )
|
||
|
|
|
||
|
|
See L<Mail::Header::fold_length()|Mail::Header/"Accessors">.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<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.
|
||
|
|
L<Mail::Header::get()|Mail::Header/"Processing"> is called to collect the data.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<header>(\@lines)
|
||
|
|
|
||
|
|
See L<Mail::Header::header()|Mail::Header/""Fake" constructors">.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<replace>(PAIRS)
|
||
|
|
|
||
|
|
The PAIRS are field-name and field-content. For each PAIR,
|
||
|
|
L<Mail::Header::replace()|Mail::Header/"Processing"> 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.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=head2 Processing the body
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<remove_sig>( [$nlines] )
|
||
|
|
|
||
|
|
Attempts to remove a user's signature from the body of a message. It does this
|
||
|
|
by looking for a line equal to C<'-- '> within the last C<$nlines> of the
|
||
|
|
message. If found then that line and all lines after it will be removed. If
|
||
|
|
C<$nlines> is not given a default value of 10 will be used. This would be of
|
||
|
|
most use in auto-reply scripts.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<sign>(%options)
|
||
|
|
|
||
|
|
Add your signature to the body. L<remove_sig()|Mail::Internet/"Processing the body"> will strip existing
|
||
|
|
signatures first.
|
||
|
|
|
||
|
|
-Option --Default
|
||
|
|
File undef
|
||
|
|
Signature []
|
||
|
|
|
||
|
|
=over 2
|
||
|
|
|
||
|
|
=item File => FILEHANDLE
|
||
|
|
|
||
|
|
Take from the FILEHANDLE all lines starting from the first C<< -- >>.
|
||
|
|
|
||
|
|
=item Signature => STRING|ARRAY-of-LINES
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<tidy_body>()
|
||
|
|
|
||
|
|
Removes all leading and trailing lines from the body that only contain
|
||
|
|
white spaces.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=head2 High-level functionality
|
||
|
|
|
||
|
|
=over 4
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<escape_from>()
|
||
|
|
|
||
|
|
It can cause problems with some applications if a message contains a line
|
||
|
|
starting with C<`From '>, in particular when attempting to split a folder.
|
||
|
|
This method inserts a leading C<`>'> on any line that matches the regular
|
||
|
|
expression C</^>*From/>
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<nntppost>( [%options] )
|
||
|
|
|
||
|
|
Post an article via NNTP. Requires Net::NNTP to be installed.
|
||
|
|
|
||
|
|
-Option--Default
|
||
|
|
Debug <false>
|
||
|
|
Host <required>
|
||
|
|
Port 119
|
||
|
|
|
||
|
|
=over 2
|
||
|
|
|
||
|
|
=item Debug => BOOLEAN
|
||
|
|
|
||
|
|
Debug value to pass to Net::NNTP, see L<Net::NNTP>
|
||
|
|
|
||
|
|
=item Host => HOSTNAME|Net::NNTP object
|
||
|
|
|
||
|
|
Name of NNTP server to connect to, or a Net::NNTP object to use.
|
||
|
|
|
||
|
|
=item Port => INTEGER
|
||
|
|
|
||
|
|
Port number to connect to on remote host
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<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 C<.mailhdr> file in your home directory (if exists) will be read
|
||
|
|
first, to provide defaults.
|
||
|
|
|
||
|
|
-Option --Default
|
||
|
|
Exclude []
|
||
|
|
Indent '>'
|
||
|
|
Keep []
|
||
|
|
ReplyAll false
|
||
|
|
|
||
|
|
=over 2
|
||
|
|
|
||
|
|
=item Exclude => ARRAY-of-FIELDS
|
||
|
|
|
||
|
|
Remove the listed FIELDS from the produced message.
|
||
|
|
|
||
|
|
=item Indent => STRING
|
||
|
|
|
||
|
|
Use as indentation string. The string may contain C<%%> to get a single C<%>,
|
||
|
|
C<%f> to get the first from name, C<%F> is the first character of C<%f>,
|
||
|
|
C<%l> is the last name, C<%L> its first character, C<%n> the whole from
|
||
|
|
string, and C<%I> the first character of each of the names in the from string.
|
||
|
|
|
||
|
|
=item Keep => ARRAY-of-FIELDS
|
||
|
|
|
||
|
|
Copy the listed FIELDS from the original message.
|
||
|
|
|
||
|
|
=item ReplyAll => BOOLEAN
|
||
|
|
|
||
|
|
Automatically include all To and Cc addresses of the original mail,
|
||
|
|
excluding those mentioned in the Bcc list.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<send>( [$type, [$args...]] )
|
||
|
|
|
||
|
|
Send a Mail::Internet message using L<Mail::Mailer|Mail::Mailer>. $type and $args are
|
||
|
|
passed on to L<Mail::Mailer::new()|Mail::Mailer/"Constructors">.
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<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 C<To>, <Cc> or C<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
|
||
|
|
|
||
|
|
=over 2
|
||
|
|
|
||
|
|
=item Bcc => ADDRESSES
|
||
|
|
|
||
|
|
=item Cc => ADDRESSES
|
||
|
|
|
||
|
|
=item Debug => BOOLEAN
|
||
|
|
|
||
|
|
Debug value to pass to Net::SMTP, see <Net::SMTP>
|
||
|
|
|
||
|
|
=item Hello => STRING
|
||
|
|
|
||
|
|
Send a HELO (or EHLO) command to the server with the given name.
|
||
|
|
|
||
|
|
=item Host => HOSTNAME
|
||
|
|
|
||
|
|
Name of the SMTP server to connect to, or a Net::SMTP object to use
|
||
|
|
|
||
|
|
If C<Host> is not given then the SMTP host is found by attempting
|
||
|
|
connections first to hosts specified in C<$ENV{SMTPHOSTS}>, a colon
|
||
|
|
separated list, then C<mailhost> and C<localhost>.
|
||
|
|
|
||
|
|
=item MailFrom => ADDRESS
|
||
|
|
|
||
|
|
The e-mail address which is used as sender. By default,
|
||
|
|
L<Mail::Util::mailaddress()|Mail::Util/"FUNCTIONS"> provides the address of the sender.
|
||
|
|
|
||
|
|
=item Port => INTEGER
|
||
|
|
|
||
|
|
Port number to connect to on remote host
|
||
|
|
|
||
|
|
=item To => ADDRESSES
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=item $obj-E<gt>B<unescape_from>(())
|
||
|
|
|
||
|
|
Remove the escaping added by L<escape_from()|Mail::Internet/"High-level functionality">.
|
||
|
|
|
||
|
|
=back
|
||
|
|
|
||
|
|
=head1 SEE ALSO
|
||
|
|
|
||
|
|
This module is part of the MailTools distribution,
|
||
|
|
F<http://perl.overmeer.net/mailtools/>.
|
||
|
|
|
||
|
|
=head1 AUTHORS
|
||
|
|
|
||
|
|
The MailTools bundle was developed by Graham Barr. Later, Mark
|
||
|
|
Overmeer took over maintenance without commitment to further development.
|
||
|
|
|
||
|
|
Mail::Cap by Gisle Aas E<lt>aas@oslonett.noE<gt>.
|
||
|
|
Mail::Field::AddrList by Peter Orbaek E<lt>poe@cit.dkE<gt>.
|
||
|
|
Mail::Mailer and Mail::Send by Tim Bunce E<lt>Tim.Bunce@ig.co.ukE<gt>.
|
||
|
|
For other contributors see ChangeLog.
|
||
|
|
|
||
|
|
=head1 LICENSE
|
||
|
|
|
||
|
|
Copyrights 1995-2000 Graham Barr E<lt>gbarr@pobox.comE<gt> and
|
||
|
|
2001-2017 Mark Overmeer E<lt>perl@overmeer.netE<gt>.
|
||
|
|
|
||
|
|
This program is free software; you can redistribute it and/or modify it
|
||
|
|
under the same terms as Perl itself.
|
||
|
|
See F<http://www.perl.com/perl/misc/Artistic.html>
|
||
|
|
|