1Mail::Internet(3)     User Contributed Perl Documentation    Mail::Internet(3)
2
3
4

NAME

6       Mail::Internet - manipulate email messages
7

SYNOPSIS

9         use Mail::Internet;
10         my $msg = Mail::Internet->new(\*STDIN);
11

DESCRIPTION

13       This package implements reading, creating, manipulating, and writing
14       email messages.  Sometimes, the implementation tries to be too smart,
15       but in the general case it works as expected.
16
17       If you start writing a new application, you should use the Mail::Box
18       distribution, which has more features and handles messages much better
19       according to the RFCs.  See <http://perl.overmeer.net/mailbox/>.  You
20       may also chose MIME::Entity, to get at least some multipart support in
21       your application.
22

METHODS

24   Constructors
25       $obj->dup()
26           Duplicate the message as a whole.  Both header and body will be
27           deep-copied: a new Mail::Internet object is returned.
28
29       $obj->extract(\@lines)
30           Extract header and body from an ARRAY of message lines.  Requires
31           an object already created with new(), which contents will get
32           overwritten.
33
34       $obj->new( [$arg], [%options] )
35       Mail::Internet->new( [$arg], [%options] )
36           $arg is optional and may be either a file descriptor (reference to
37           a GLOB) or a reference to an array. If given the new object will be
38           initialized with headers and body either from the array of read
39           from the file descriptor.
40
41           The Mail::Header::new() %options "Modify", "MailFrom" and
42           "FoldLength" may also be given.
43
44            -Option--Default
45             Body    []
46             Header  undef
47
48           Body => ARRAY-of-LINES
49             The value of this option should be a reference to an array which
50             contains the lines for the body of the message. Each line should
51             be terminated with "\n" (LF). If Body is given then
52             "Mail::Internet" will not attempt to read the body from $arg
53             (even if it is specified).
54
55           Header => Mail::Header
56             The value of this option should be a Mail::Header object. If
57             given then "Mail::Internet" will not attempt to read a mail
58             header from $arg, if it was specified.
59
60       $obj->read($fh)
61           Read a message from the $fh into an already existing message
62           object.  Better use new() with the $fh as first argument.
63
64   Accessors
65       $obj->body( [$body] )
66           Returns the body of the message. This is a reference to an array.
67           Each entry in the array represents a single line in the message.
68
69           If $body is given, it can be a reference to an array or an array,
70           then the body will be replaced. If a reference is passed, it is
71           used directly and not copied, so any subsequent changes to the
72           array will change the contents of the body.
73
74       $obj->head()
75           Returns the "Mail::Header" object which holds the headers for the
76           current message
77
78   Processing the message as a whole
79       $obj->as_mbox_string( [$already_escaped] )
80           Returns the message as a string in mbox format.  $already_escaped,
81           if given and true, indicates that escape_from() has already been
82           called on this object.
83
84       $obj->as_string()
85           Returns the message as a single string.
86
87       $obj->print( [$fh] )
88           Print the header, body or whole message to file descriptor $fh.
89           $fd should be a reference to a GLOB. If $fh is not given the output
90           will be sent to STDOUT.
91
92           example:
93
94               $mail->print( \*STDOUT );  # Print message to STDOUT
95
96       $obj->print_body( [$fh] )
97           Print only the body to the $fh (default STDOUT).
98
99       $obj->print_header( [$fh] )
100           Print only the header to the $fh (default STDOUT).
101
102   Processing the header
103       Most of these methods are simply wrappers around methods provided by
104       Mail::Header.
105
106       $obj->add(PAIRS)
107           The PAIRS are field-name and field-content.  For each PAIR,
108           Mail::Header::add() is called.  All fields are added after existing
109           fields.  The last addition is returned.
110
111       $obj->combine( $tag, [$with] )
112           See Mail::Header::combine().
113
114       $obj->delete( $tag, [$tags] )
115           Delete all fields with the name $tag.  Mail::Header::delete() is
116           doing the work.
117
118       $obj->fold( [$length] )
119           See Mail::Header::fold().
120
121       $obj->fold_length( [$tag], [$length] )
122           See Mail::Header::fold_length().
123
124       $obj->get( $tag, [$tags] )
125           In LIST context, all fields with the name $tag are returned.  In
126           SCALAR context, only the first field which matches the earliest
127           $tag is returned.  Mail::Header::get() is called to collect the
128           data.
129
130       $obj->header(\@lines)
131           See Mail::Header::header().
132
133       $obj->replace(PAIRS)
134           The PAIRS are field-name and field-content.  For each PAIR,
135           Mail::Header::replace() is called with index 0. If a $field is
136           already in the header, it will be removed first.  Do not specified
137           the same field-name twice.
138
139   Processing the body
140       $obj->remove_sig( [$nlines] )
141           Attempts to remove a user's signature from the body of a message.
142           It does this by looking for a line equal to '-- ' within the last
143           $nlines of the message. If found then that line and all lines after
144           it will be removed. If $nlines is not given a default value of 10
145           will be used. This would be of most use in auto-reply scripts.
146
147       $obj->sign(%options)
148           Add your signature to the body.  remove_sig() will strip existing
149           signatures first.
150
151            -Option   --Default
152             File       undef
153             Signature  []
154
155           File => FILEHANDLE
156             Take from the FILEHANDLE all lines starting from the first "--".
157
158           Signature => STRING|ARRAY-of-LINES
159       $obj->tidy_body()
160           Removes all leading and trailing lines from the body that only
161           contain white spaces.
162
163   High-level functionality
164       $obj->escape_from()
165           It can cause problems with some applications if a message contains
166           a line starting with `From ', in particular when attempting to
167           split a folder.  This method inserts a leading "`"'> on any line
168           that matches the regular expression "/^"*From/>
169
170       $obj->nntppost( [%options] )
171           Post an article via NNTP.  Requires Net::NNTP to be installed.
172
173            -Option--Default
174             Debug   <false>
175             Host    <required>
176             Port    119
177
178           Debug => BOOLEAN
179             Debug value to pass to Net::NNTP, see Net::NNTP
180
181           Host => HOSTNAME|Net::NNTP object
182             Name of NNTP server to connect to, or a Net::NNTP object to use.
183
184           Port => INTEGER
185             Port number to connect to on remote host
186
187       $obj->reply(%options)
188           Create a new object with header initialised for a reply to the
189           current object. And the body will be a copy of the current message
190           indented.
191
192           The ".mailhdr" file in your home directory (if exists) will be read
193           first, to provide defaults.
194
195            -Option  --Default
196             Exclude   []
197             Indent    '>'
198             Keep      []
199             ReplyAll  false
200
201           Exclude => ARRAY-of-FIELDS
202             Remove the listed FIELDS from the produced message.
203
204           Indent => STRING
205             Use as indentation string.  The string may contain "%%" to get a
206             single "%", %f to get the first from name, %F is the first
207             character of %f, %l is the last name, %L its first character, %n
208             the whole from string, and %I the first character of each of the
209             names in the from string.
210
211           Keep => ARRAY-of-FIELDS
212             Copy the listed FIELDS from the original message.
213
214           ReplyAll => BOOLEAN
215             Automatically include all To and Cc addresses of the original
216             mail, excluding those mentioned in the Bcc list.
217
218       $obj->send( [$type, [$args...]] )
219           Send a Mail::Internet message using Mail::Mailer.  $type and $args
220           are passed on to Mail::Mailer::new().
221
222       $obj->smtpsend( [%options] )
223           Send a Mail::Internet message using direct SMTP to the given
224           ADDRESSES, each can be either a string or a reference to a list of
225           email addresses. If none of "To", <Cc> or "Bcc" are given then the
226           addresses are extracted from the message being sent.
227
228           The return value will be a list of email addresses that the message
229           was sent to. If the message was not sent the list will be empty.
230
231           Requires Net::SMTP and Net::Domain to be installed.
232
233            -Option  --Default
234             Bcc       undef
235             Cc        undef
236             Debug     <false>
237             Hello     localhost.localdomain
238             Host      $ENV{SMTPHOSTS}
239             MailFrom  Mail::Util::mailaddress()
240             Port      25
241             To        undef
242
243           Bcc => ADDRESSES
244           Cc => ADDRESSES
245           Debug => BOOLEAN
246             Debug value to pass to Net::SMTP, see <Net::SMTP>
247
248           Hello => STRING
249             Send a HELO (or EHLO) command to the server with the given name.
250
251           Host => HOSTNAME
252             Name of the SMTP server to connect to, or a Net::SMTP object to
253             use
254
255             If "Host" is not given then the SMTP host is found by attempting
256             connections first to hosts specified in $ENV{SMTPHOSTS}, a colon
257             separated list, then "mailhost" and "localhost".
258
259           MailFrom => ADDRESS
260             The e-mail address which is used as sender.  By default,
261             Mail::Util::mailaddress() provides the address of the sender.
262
263           Port => INTEGER
264             Port number to connect to on remote host
265
266           To => ADDRESSES
267       $obj->unescape_from(())
268           Remove the escaping added by escape_from().
269

SEE ALSO

271       This module is part of the MailTools distribution,
272       http://perl.overmeer.net/mailtools/.
273

AUTHORS

275       The MailTools bundle was developed by Graham Barr.  Later, Mark
276       Overmeer took over maintenance without commitment to further
277       development.
278
279       Mail::Cap by Gisle Aas <aas@oslonett.no>.  Mail::Field::AddrList by
280       Peter Orbaek <poe@cit.dk>.  Mail::Mailer and Mail::Send by Tim Bunce
281       <Tim.Bunce@ig.co.uk>.  For other contributors see ChangeLog.
282

LICENSE

284       Copyrights 1995-2000 Graham Barr <gbarr@pobox.com> and 2001-2017 Mark
285       Overmeer <perl@overmeer.net>.
286
287       This program is free software; you can redistribute it and/or modify it
288       under the same terms as Perl itself.  See
289       http://www.perl.com/perl/misc/Artistic.html
290
291
292
293perl v5.38.0                      2023-07-20                 Mail::Internet(3)
Impressum