Mail::Internet(3pm)

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

NAME

6       Mail::Internet - manipulate email messages
7

INHERITANCE

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

AUTHORS

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

LICENSE

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