Mail::Internet(3pm)

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

AUTHORS

327       The MailTools bundle was developed by Graham Barr.  Later, Mark
328       Overmeer took over maintenance without commitment to further
329       development.
330
331       Mail::Cap by Gisle Aas <aas@oslonett.no>.  Mail::Field::AddrList by
332       Peter Orbaek <poe@cit.dk>.  Mail::Mailer and Mail::Send by Tim Bunce
333       <Tim.Bunce@ig.co.uk>.  For other contributors see ChangeLog.
334

LICENSE

336       Copyrights 1995-2000 Graham Barr <gbarr@pobox.com> and 2001-2007 Mark
337       Overmeer <perl@overmeer.net>.
338
339       This program is free software; you can redistribute it and/or modify it
340       under the same terms as Perl itself.  See
341       http://www.perl.com/perl/misc/Artistic.html
342
343
344
345perl v5.12.2                      2010-10-01                 Mail::Internet(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO

AUTHORS

LICENSE