1Mail::Internet(3) User Contributed Perl Documentation Mail::Internet(3)
2
6 Mail::Internet - manipulate email messages
7
9 use Mail::Internet;
10 my $msg = Mail::Internet->new(\*STDIN);
11
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 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
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 $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 $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 The Mail::Header::new() %options "Modify", "MailFrom" and
42 "FoldLength" may also be given.
43 -Option--Default
45 Body []
46 Header undef
47 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 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 $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 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 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 $obj->head()
75 Returns the "Mail::Header" object which holds the headers for the
76 current message
77 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 $obj->as_string()
85 Returns the message as a single string.
86 $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 example:
93 $mail->print( \*STDOUT ); # Print message to STDOUT
95 $obj->print_body( [$fh] )
97 Print only the body to the $fh (default STDOUT).
98 $obj->print_header( [$fh] )
100 Print only the header to the $fh (default STDOUT).
101 Processing the header
103 Most of these methods are simply wrappers around methods provided by
104 Mail::Header.
105 $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 $obj->combine( $tag, [$with] )
112 See Mail::Header::combine().
113 $obj->delete( $tag, [$tags] )
115 Delete all fields with the name $tag. Mail::Header::delete() is
116 doing the work.
117 $obj->fold( [$length] )
119 See Mail::Header::fold().
120 $obj->fold_length( [$tag], [$length] )
122 See Mail::Header::fold_length().
123 $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 $obj->header(\@lines)
131 See Mail::Header::header().
132 $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 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 $obj->sign(%options)
148 Add your signature to the body. remove_sig() will strip existing
149 signatures first.
150 -Option --Default
152 File undef
153 Signature []
154 File => FILEHANDLE
156 Take from the FILEHANDLE all lines starting from the first "--".
157 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 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 $obj->nntppost( [%options] )
171 Post an article via NNTP. Requires Net::NNTP to be installed.
172 -Option--Default
174 Debug <false>
175 Host <required>
176 Port 119
177 Debug => BOOLEAN
179 Debug value to pass to Net::NNTP, see Net::NNTP
180 Host => HOSTNAME|Net::NNTP object
182 Name of NNTP server to connect to, or a Net::NNTP object to use.
183 Port => INTEGER
185 Port number to connect to on remote host
186 $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 The ".mailhdr" file in your home directory (if exists) will be read
193 first, to provide defaults.
194 -Option --Default
196 Exclude []
197 Indent '>'
198 Keep []
199 ReplyAll false
200 Exclude => ARRAY-of-FIELDS
202 Remove the listed FIELDS from the produced message.
203 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 Keep => ARRAY-of-FIELDS
212 Copy the listed FIELDS from the original message.
213 ReplyAll => BOOLEAN
215 Automatically include all To and Cc addresses of the original
216 mail, excluding those mentioned in the Bcc list.
217 $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 $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 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 Requires Net::SMTP and Net::Domain to be installed.
232 -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 Bcc => ADDRESSES
244 Cc => ADDRESSES
245 Debug => BOOLEAN
246 Debug value to pass to Net::SMTP, see <Net::SMTP>
247 Hello => STRING
249 Send a HELO (or EHLO) command to the server with the given name.
250 Host => HOSTNAME
252 Name of the SMTP server to connect to, or a Net::SMTP object to
253 use
254 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 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 Port => INTEGER
264 Port number to connect to on remote host
265 To => ADDRESSES
267 $obj->unescape_from(())
268 Remove the escaping added by escape_from().
269
271 This module is part of the MailTools distribution,
272 http://perl.overmeer.net/mailtools/.
273
275 The MailTools bundle was developed by Graham Barr. Later, Mark
276 Overmeer took over maintenance without commitment to further
277 development.
278 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
284 Copyrights 1995-2000 Graham Barr <gbarr@pobox.com> and 2001-2017 Mark
285 Overmeer <perl@overmeer.net>.
286 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
290perl v5.38.0 2023-07-20 Mail::Internet(3)