638 lines
14 KiB
HTML
638 lines
14 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Mail::Internet</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Mail::Internet</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2019-07-25<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Mail::Internet - manipulate email messages
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use Mail::Internet;
|
|
my $msg = Mail::Internet->new(\*STDIN);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
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.
|
|
<P>
|
|
|
|
If you start writing a <B>new application</B>, you should use the Mail::Box
|
|
distribution, which has more features and handles messages much better
|
|
according to the RFCs. See <<A HREF="http://perl.overmeer.net/mailbox/">http://perl.overmeer.net/mailbox/</A>>.
|
|
You may also chose MIME::Entity, to get at least some multipart
|
|
support in your application.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>METHODS</H2>
|
|
|
|
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Constructors</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">$obj-><B>dup</B>()<DD>
|
|
|
|
|
|
|
|
|
|
Duplicate the message as a whole. Both header and body will be
|
|
deep-copied: a new Mail::Internet object is returned.
|
|
<DT id="2">$obj-><B>extract</B>(\@lines)<DD>
|
|
|
|
|
|
|
|
|
|
Extract header and body from an <FONT SIZE="-1">ARRAY</FONT> of message lines. Requires an
|
|
object already created with <B>new()</B>, which contents will get overwritten.
|
|
<DT id="3">$obj-><B>new</B>( [$arg], [%options] )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="4">Mail::Internet-><B>new</B>( [$arg], [%options] )<DD>
|
|
|
|
|
|
|
|
<TT>$arg</TT> is optional and may be either a file descriptor (reference to a <FONT SIZE="-1">GLOB</FONT>)
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <B>Mail::Header::new()</B> <TT>%options</TT> <TT>"Modify"</TT>, <TT>"MailFrom"</TT> and <TT>"FoldLength"</TT>
|
|
may also be given.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
-Option--Default
|
|
Body []
|
|
Header undef
|
|
|
|
</PRE>
|
|
|
|
|
|
<DL COMPACT><DT id="5"><DD>
|
|
<DL COMPACT>
|
|
<DT id="6">Body => ARRAY-of-LINES<DD>
|
|
|
|
|
|
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
|
|
<TT>"\n"</TT> (<FONT SIZE="-1">LF</FONT>). If Body is given then <TT>"Mail::Internet"</TT> will not attempt to
|
|
read the body from <TT>$arg</TT> (even if it is specified).
|
|
<DT id="7">Header => Mail::Header<DD>
|
|
|
|
|
|
The value of this option should be a Mail::Header object. If given then
|
|
<TT>"Mail::Internet"</TT> will not attempt to read a mail header from <TT>$arg</TT>, if
|
|
it was specified.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="8"><DD>
|
|
</DL>
|
|
|
|
<DT id="9">$obj-><B>read</B>($fh)<DD>
|
|
|
|
|
|
|
|
|
|
Read a message from the <TT>$fh</TT> into an already existing message
|
|
object. Better use <B>new()</B> with the <TT>$fh</TT> as first argument.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Accessors</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="10">$obj-><B>body</B>( [$body] )<DD>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <I></I>$body<I></I> 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.
|
|
<DT id="11">$obj-><B>head</B>()<DD>
|
|
|
|
|
|
|
|
|
|
Returns the <TT>"Mail::Header"</TT> object which holds the headers for the current
|
|
message
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Processing the message as a whole</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="12">$obj-><B>as_mbox_string</B>( [$already_escaped] )<DD>
|
|
|
|
|
|
|
|
|
|
Returns the message as a string in mbox format. <TT>$already_escaped</TT>, if
|
|
given and true, indicates that <B>escape_from()</B> has already been called on
|
|
this object.
|
|
<DT id="13">$obj-><B>as_string</B>()<DD>
|
|
|
|
|
|
|
|
|
|
Returns the message as a single string.
|
|
<DT id="14">$obj-><B>print</B>( [$fh] )<DD>
|
|
|
|
|
|
|
|
|
|
Print the header, body or whole message to file descriptor <I></I>$fh<I></I>.
|
|
<I></I>$fd<I></I> should be a reference to a <FONT SIZE="-1">GLOB.</FONT> If <I></I>$fh<I></I> is not given the
|
|
output will be sent to <FONT SIZE="-1">STDOUT.</FONT>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$mail->print( \*STDOUT ); # Print message to STDOUT
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="15">$obj-><B>print_body</B>( [$fh] )<DD>
|
|
|
|
|
|
|
|
|
|
Print only the body to the <TT>$fh</TT> (default <FONT SIZE="-1">STDOUT</FONT>).
|
|
<DT id="16">$obj-><B>print_header</B>( [$fh] )<DD>
|
|
|
|
|
|
|
|
|
|
Print only the header to the <TT>$fh</TT> (default <FONT SIZE="-1">STDOUT</FONT>).
|
|
</DL>
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Processing the header</H3>
|
|
|
|
|
|
|
|
Most of these methods are simply wrappers around methods provided
|
|
by Mail::Header.
|
|
<DL COMPACT>
|
|
<DT id="17">$obj-><B>add</B>(<FONT SIZE="-1">PAIRS</FONT>)<DD>
|
|
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">PAIRS</FONT> are field-name and field-content. For each <FONT SIZE="-1">PAIR,</FONT>
|
|
<B>Mail::Header::add()</B> is called. All fields are added after
|
|
existing fields. The last addition is returned.
|
|
<DT id="18">$obj-><B>combine</B>( $tag, [$with] )<DD>
|
|
|
|
|
|
|
|
|
|
See <B>Mail::Header::combine()</B>.
|
|
<DT id="19">$obj-><B>delete</B>( $tag, [$tags] )<DD>
|
|
|
|
|
|
|
|
|
|
Delete all fields with the name <TT>$tag</TT>. <B>Mail::Header::delete()</B> is doing the
|
|
work.
|
|
<DT id="20">$obj-><B>fold</B>( [$length] )<DD>
|
|
|
|
|
|
|
|
|
|
See <B>Mail::Header::fold()</B>.
|
|
<DT id="21">$obj-><B>fold_length</B>( [$tag], [$length] )<DD>
|
|
|
|
|
|
|
|
|
|
See <B>Mail::Header::fold_length()</B>.
|
|
<DT id="22">$obj-><B>get</B>( $tag, [$tags] )<DD>
|
|
|
|
|
|
|
|
|
|
In <FONT SIZE="-1">LIST</FONT> context, all fields with the name <TT>$tag</TT> are returned. In <FONT SIZE="-1">SCALAR</FONT>
|
|
context, only the first field which matches the earliest <TT>$tag</TT> is returned.
|
|
<B>Mail::Header::get()</B> is called to collect the data.
|
|
<DT id="23">$obj-><B>header</B>(\@lines)<DD>
|
|
|
|
|
|
|
|
|
|
See <B>Mail::Header::header()</B>.
|
|
<DT id="24">$obj-><B>replace</B>(<FONT SIZE="-1">PAIRS</FONT>)<DD>
|
|
|
|
|
|
|
|
|
|
The <FONT SIZE="-1">PAIRS</FONT> are field-name and field-content. For each <FONT SIZE="-1">PAIR,</FONT>
|
|
<B>Mail::Header::replace()</B> is called with index 0. If a <TT>$field</TT> is already
|
|
in the header, it will be removed first. Do not specified the same
|
|
field-name twice.
|
|
</DL>
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Processing the body</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="25">$obj-><B>remove_sig</B>( [$nlines] )<DD>
|
|
|
|
|
|
|
|
|
|
Attempts to remove a user's signature from the body of a message. It does this
|
|
by looking for a line equal to <TT>'-- '</TT> within the last <TT>$nlines</TT> of the
|
|
message. If found then that line and all lines after it will be removed. If
|
|
<TT>$nlines</TT> is not given a default value of 10 will be used. This would be of
|
|
most use in auto-reply scripts.
|
|
<DT id="26">$obj-><B>sign</B>(%options)<DD>
|
|
|
|
|
|
|
|
|
|
Add your signature to the body. <B>remove_sig()</B> will strip existing
|
|
signatures first.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
-Option --Default
|
|
File undef
|
|
Signature []
|
|
|
|
</PRE>
|
|
|
|
|
|
<DL COMPACT><DT id="27"><DD>
|
|
<DL COMPACT>
|
|
<DT id="28">File => <FONT SIZE="-1">FILEHANDLE</FONT><DD>
|
|
|
|
|
|
Take from the <FONT SIZE="-1">FILEHANDLE</FONT> all lines starting from the first <TT>"--"</TT>.
|
|
<DT id="29">Signature => STRING|ARRAY-of-LINES<DD>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="30"><DD>
|
|
</DL>
|
|
|
|
|
|
<DT id="31">$obj-><B>tidy_body</B>()<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Removes all leading and trailing lines from the body that only contain
|
|
white spaces.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H3>High-level functionality</H3>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="32">$obj-><B>escape_from</B>()<DD>
|
|
|
|
|
|
|
|
|
|
It can cause problems with some applications if a message contains a line
|
|
starting with <TT>`From '</TT>, in particular when attempting to split a folder.
|
|
This method inserts a leading <TT>"`"</TT>'> on any line that matches the regular
|
|
expression <TT>"/^"</TT>*From/>
|
|
<DT id="33">$obj-><B>nntppost</B>( [%options] )<DD>
|
|
|
|
|
|
|
|
|
|
Post an article via <FONT SIZE="-1">NNTP.</FONT> Requires Net::NNTP to be installed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
-Option--Default
|
|
Debug <false>
|
|
Host <required>
|
|
Port 119
|
|
|
|
</PRE>
|
|
|
|
|
|
<DL COMPACT><DT id="34"><DD>
|
|
<DL COMPACT>
|
|
<DT id="35">Debug => <FONT SIZE="-1">BOOLEAN</FONT><DD>
|
|
|
|
|
|
Debug value to pass to Net::NNTP, see Net::NNTP
|
|
<DT id="36">Host => HOSTNAME|Net::NNTP object<DD>
|
|
|
|
|
|
Name of <FONT SIZE="-1">NNTP</FONT> server to connect to, or a Net::NNTP object to use.
|
|
<DT id="37">Port => <FONT SIZE="-1">INTEGER</FONT><DD>
|
|
|
|
|
|
Port number to connect to on remote host
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="38"><DD>
|
|
</DL>
|
|
|
|
<DT id="39">$obj-><B>reply</B>(%options)<DD>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>".mailhdr"</TT> file in your home directory (if exists) will be read
|
|
first, to provide defaults.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
-Option --Default
|
|
Exclude []
|
|
Indent '>'
|
|
Keep []
|
|
ReplyAll false
|
|
|
|
</PRE>
|
|
|
|
|
|
<DL COMPACT><DT id="40"><DD>
|
|
<DL COMPACT>
|
|
<DT id="41">Exclude => ARRAY-of-FIELDS<DD>
|
|
|
|
|
|
Remove the listed <FONT SIZE="-1">FIELDS</FONT> from the produced message.
|
|
<DT id="42">Indent => <FONT SIZE="-1">STRING</FONT><DD>
|
|
|
|
|
|
Use as indentation string. The string may contain <TT>"%%"</TT> to get a single <TT>"%"</TT>,
|
|
<TT>%f</TT> to get the first from name, <TT>%F</TT> is the first character of <TT>%f</TT>,
|
|
<TT>%l</TT> is the last name, <TT>%L</TT> its first character, <TT>%n</TT> the whole from
|
|
string, and <TT>%I</TT> the first character of each of the names in the from string.
|
|
<DT id="43">Keep => ARRAY-of-FIELDS<DD>
|
|
|
|
|
|
Copy the listed <FONT SIZE="-1">FIELDS</FONT> from the original message.
|
|
<DT id="44">ReplyAll => <FONT SIZE="-1">BOOLEAN</FONT><DD>
|
|
|
|
|
|
Automatically include all To and Cc addresses of the original mail,
|
|
excluding those mentioned in the Bcc list.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="45"><DD>
|
|
</DL>
|
|
|
|
<DT id="46">$obj-><B>send</B>( [$type, [$args...]] )<DD>
|
|
|
|
|
|
|
|
|
|
Send a Mail::Internet message using Mail::Mailer. <TT>$type</TT> and <TT>$args</TT> are
|
|
passed on to <B>Mail::Mailer::new()</B>.
|
|
<DT id="47">$obj-><B>smtpsend</B>( [%options] )<DD>
|
|
|
|
|
|
|
|
|
|
Send a Mail::Internet message using direct <FONT SIZE="-1">SMTP</FONT> to the given
|
|
<FONT SIZE="-1">ADDRESSES,</FONT> each can be either a string or a reference to a list of email
|
|
addresses. If none of <TT>"To"</TT>, <Cc> or <TT>"Bcc"</TT> are given then the addresses
|
|
are extracted from the message being sent.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Requires Net::SMTP and Net::Domain to be installed.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
-Option --Default
|
|
Bcc undef
|
|
Cc undef
|
|
Debug <false>
|
|
Hello localhost.localdomain
|
|
Host $ENV{SMTPHOSTS}
|
|
MailFrom Mail::Util::mailaddress()
|
|
Port 25
|
|
To undef
|
|
|
|
</PRE>
|
|
|
|
|
|
<DL COMPACT><DT id="48"><DD>
|
|
<DL COMPACT>
|
|
<DT id="49">Bcc => <FONT SIZE="-1">ADDRESSES</FONT><DD>
|
|
|
|
|
|
|
|
<DT id="50">Cc => <FONT SIZE="-1">ADDRESSES</FONT><DD>
|
|
|
|
|
|
<DT id="51">Debug => <FONT SIZE="-1">BOOLEAN</FONT><DD>
|
|
|
|
|
|
|
|
Debug value to pass to Net::SMTP, see <Net::SMTP>
|
|
<DT id="52">Hello => <FONT SIZE="-1">STRING</FONT><DD>
|
|
|
|
|
|
Send a <FONT SIZE="-1">HELO</FONT> (or <FONT SIZE="-1">EHLO</FONT>) command to the server with the given name.
|
|
<DT id="53">Host => <FONT SIZE="-1">HOSTNAME</FONT><DD>
|
|
|
|
|
|
Name of the <FONT SIZE="-1">SMTP</FONT> server to connect to, or a Net::SMTP object to use
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If <TT>"Host"</TT> is not given then the <FONT SIZE="-1">SMTP</FONT> host is found by attempting
|
|
connections first to hosts specified in <TT>$ENV{SMTPHOSTS}</TT>, a colon
|
|
separated list, then <TT>"mailhost"</TT> and <TT>"localhost"</TT>.
|
|
<DT id="54">MailFrom => <FONT SIZE="-1">ADDRESS</FONT><DD>
|
|
|
|
|
|
The e-mail address which is used as sender. By default,
|
|
<B>Mail::Util::mailaddress()</B> provides the address of the sender.
|
|
<DT id="55">Port => <FONT SIZE="-1">INTEGER</FONT><DD>
|
|
|
|
|
|
Port number to connect to on remote host
|
|
<DT id="56">To => <FONT SIZE="-1">ADDRESSES</FONT><DD>
|
|
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="57"><DD>
|
|
</DL>
|
|
|
|
|
|
<DT id="58">$obj-><B>unescape_from</B>(())<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Remove the escaping added by <B>escape_from()</B>.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
This module is part of the MailTools distribution,
|
|
<I><A HREF="http://perl.overmeer.net/mailtools/">http://perl.overmeer.net/mailtools/</A></I>.
|
|
<A NAME="lbAM"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
|
|
|
|
The MailTools bundle was developed by Graham Barr. Later, Mark
|
|
Overmeer took over maintenance without commitment to further development.
|
|
<P>
|
|
|
|
Mail::Cap by Gisle Aas <<A HREF="mailto:aas@oslonett.no">aas@oslonett.no</A>>.
|
|
Mail::Field::AddrList by Peter Orbaek <<A HREF="mailto:poe@cit.dk">poe@cit.dk</A>>.
|
|
Mail::Mailer and Mail::Send by Tim Bunce <<A HREF="mailto:Tim.Bunce@ig.co.uk">Tim.Bunce@ig.co.uk</A>>.
|
|
For other contributors see ChangeLog.
|
|
<A NAME="lbAN"> </A>
|
|
<H2>LICENSE</H2>
|
|
|
|
|
|
|
|
Copyrights 1995-2000 Graham Barr <<A HREF="mailto:gbarr@pobox.com">gbarr@pobox.com</A>> and
|
|
2001-2017 Mark Overmeer <<A HREF="mailto:perl@overmeer.net">perl@overmeer.net</A>>.
|
|
<P>
|
|
|
|
This program is free software; you can redistribute it and/or modify it
|
|
under the same terms as Perl itself.
|
|
See <I><A HREF="http://www.perl.com/perl/misc/Artistic.html">http://www.perl.com/perl/misc/Artistic.html</A></I>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="59"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="60"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="61"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="62"><A HREF="#lbAE">METHODS</A><DD>
|
|
<DL>
|
|
<DT id="63"><A HREF="#lbAF">Constructors</A><DD>
|
|
<DT id="64"><A HREF="#lbAG">Accessors</A><DD>
|
|
<DT id="65"><A HREF="#lbAH">Processing the message as a whole</A><DD>
|
|
<DT id="66"><A HREF="#lbAI">Processing the header</A><DD>
|
|
<DT id="67"><A HREF="#lbAJ">Processing the body</A><DD>
|
|
<DT id="68"><A HREF="#lbAK">High-level functionality</A><DD>
|
|
</DL>
|
|
<DT id="69"><A HREF="#lbAL">SEE ALSO</A><DD>
|
|
<DT id="70"><A HREF="#lbAM">AUTHORS</A><DD>
|
|
<DT id="71"><A HREF="#lbAN">LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:47 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|