1Net::SMTP(3pm) Perl Programmers Reference Guide Net::SMTP(3pm)
2
6 Net::SMTP - Simple Mail Transfer Protocol Client
7
9 use Net::SMTP;
10 # Constructors
12 $smtp = Net::SMTP->new('mailhost');
13 $smtp = Net::SMTP->new('mailhost', Timeout => 60);
14
16 This module implements a client interface to the SMTP and ESMTP
17 protocol, enabling a perl5 application to talk to SMTP servers. This
18 documentation assumes that you are familiar with the concepts of the
19 SMTP protocol described in RFC821.
20 A new Net::SMTP object must be created with the new method. Once this
22 has been done, all SMTP commands are accessed through this object.
23 The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.
25
27 This example prints the mail domain name of the SMTP server known as
28 mailhost:
29 #!/usr/local/bin/perl -w
31 use Net::SMTP;
33 $smtp = Net::SMTP->new('mailhost');
35 print $smtp->domain,"\n";
36 $smtp->quit;
37 This example sends a small message to the postmaster at the SMTP server
39 known as mailhost:
40 #!/usr/local/bin/perl -w
42 use Net::SMTP;
44 $smtp = Net::SMTP->new('mailhost');
46 $smtp->mail($ENV{USER});
48 $smtp->to('postmaster');
49 $smtp->data();
51 $smtp->datasend("To: postmaster\n");
52 $smtp->datasend("\n");
53 $smtp->datasend("A simple test message\n");
54 $smtp->dataend();
55 $smtp->quit;
57
59 new ( [ HOST ] [, OPTIONS ] )
60 This is the constructor for a new Net::SMTP object. "HOST" is the
61 name of the remote host to which an SMTP connection is required.
62 "HOST" is optional. If "HOST" is not given then it may instead be
64 passed as the "Host" option described below. If neither is given
65 then the "SMTP_Hosts" specified in "Net::Config" will be used.
66 "OPTIONS" are passed in a hash like fashion, using key and value
68 pairs. Possible options are:
69 Hello - SMTP requires that you identify yourself. This option
71 specifies a string to pass as your mail domain. If not given
72 localhost.localdomain will be used.
73 Host - SMTP host to connect to. It may be a single scalar, as
75 defined for the "PeerAddr" option in IO::Socket::INET, or a
76 reference to an array with hosts to try in turn. The "host" method
77 will return the value which was used to connect to the host.
78 SSL - If the connection should be done from start with SSL,
80 contrary to later upgrade with "starttls". You can use SSL
81 arguments as documented in IO::Socket::SSL, but it will usually use
82 the right arguments already.
83 LocalAddr and LocalPort - These parameters are passed directly to
85 IO::Socket to allow binding the socket to a local port.
86 Timeout - Maximum time, in seconds, to wait for a response from the
88 SMTP server (default: 120)
89 ExactAddresses - If true the all ADDRESS arguments must be as
91 defined by "addr-spec" in RFC2822. If not given, or false, then
92 Net::SMTP will attempt to extract the address from the value
93 passed.
94 Debug - Enable debugging information
96 Example:
98 $smtp = Net::SMTP->new('mailhost',
100 Hello => 'my.mail.domain',
101 Timeout => 30,
102 Debug => 1,
103 );
104 # the same
106 $smtp = Net::SMTP->new(
107 Host => 'mailhost',
108 Hello => 'my.mail.domain',
109 Timeout => 30,
110 Debug => 1,
111 );
112 # the same with direct SSL
114 $smtp = Net::SMTP->new('mailhost',
115 Hello => 'my.mail.domain',
116 Timeout => 30,
117 Debug => 1,
118 SSL => 1,
119 );
120 # Connect to the default server from Net::config
122 $smtp = Net::SMTP->new(
123 Hello => 'my.mail.domain',
124 Timeout => 30,
125 );
126
128 Unless otherwise stated all methods return either a true or false
129 value, with true meaning that the operation was a success. When a
130 method states that it returns a value, failure will be returned as
131 undef or an empty list.
132 banner ()
134 Returns the banner message which the server replied with when the
135 initial connection was made.
136 domain ()
138 Returns the domain that the remote SMTP server identified itself as
139 during connection.
140 hello ( DOMAIN )
142 Tell the remote server the mail domain which you are in using the
143 EHLO command (or HELO if EHLO fails). Since this method is invoked
144 automatically when the Net::SMTP object is constructed the user
145 should normally not have to call it manually.
146 host ()
148 Returns the value used by the constructor, and passed to
149 IO::Socket::INET, to connect to the host.
150 etrn ( DOMAIN )
152 Request a queue run for the DOMAIN given.
153 starttls ( SSLARGS )
155 Upgrade existing plain connection to SSL. You can use SSL
156 arguments as documented in IO::Socket::SSL, but it will usually use
157 the right arguments already.
158 auth ( USERNAME, PASSWORD )
160 Attempt SASL authentication.
161 mail ( ADDRESS [, OPTIONS] )
163 send ( ADDRESS )
164 send_or_mail ( ADDRESS )
165 send_and_mail ( ADDRESS )
166 Send the appropriate command to the server MAIL, SEND, SOML or
167 SAML. "ADDRESS" is the address of the sender. This initiates the
168 sending of a message. The method "recipient" should be called for
169 each address that the message is to be sent to.
170 The "mail" method can some additional ESMTP OPTIONS which is passed
172 in hash like fashion, using key and value pairs. Possible options
173 are:
174 Size => <bytes>
176 Return => "FULL" | "HDRS"
177 Bits => "7" | "8" | "binary"
178 Transaction => <ADDRESS>
179 Envelope => <ENVID> # xtext-encodes its argument
180 ENVID => <ENVID> # similar to Envelope, but expects argument encoded
181 XVERP => 1
182 AUTH => <submitter> # encoded address according to RFC 2554
183 The "Return" and "Envelope" parameters are used for DSN (Delivery
185 Status Notification).
186 The submitter address in "AUTH" option is expected to be in a
188 format as required by RFC 2554, in an RFC2821-quoted form and
189 xtext-encoded, or <> .
190 reset ()
192 Reset the status of the server. This may be called after a message
193 has been initiated, but before any data has been sent, to cancel
194 the sending of the message.
195 recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] )
197 Notify the server that the current message should be sent to all of
198 the addresses given. Each address is sent as a separate command to
199 the server. Should the sending of any address result in a failure
200 then the process is aborted and a false value is returned. It is up
201 to the user to call "reset" if they so desire.
202 The "recipient" method can also pass additional case-sensitive
204 OPTIONS as an anonymous hash using key and value pairs. Possible
205 options are:
206 Notify => ['NEVER'] or ['SUCCESS','FAILURE','DELAY'] (see below)
208 ORcpt => <ORCPT>
209 SkipBad => 1 (to ignore bad addresses)
210 If "SkipBad" is true the "recipient" will not return an error when
212 a bad address is encountered and it will return an array of
213 addresses that did succeed.
214 $smtp->recipient($recipient1,$recipient2); # Good
216 $smtp->recipient($recipient1,$recipient2, { SkipBad => 1 }); # Good
217 $smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 }); # Good
218 @goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 }); # Good
219 $smtp->recipient("$recipient,$recipient2"); # BAD
220 Notify is used to request Delivery Status Notifications (DSNs), but
222 your SMTP/ESMTP service may not respect this request depending upon
223 its version and your site's SMTP configuration.
224 Leaving out the Notify option usually defaults an SMTP service to
226 its default behavior equivalent to ['FAILURE'] notifications only,
227 but again this may be dependent upon your site's SMTP
228 configuration.
229 The NEVER keyword must appear by itself if used within the Notify
231 option and "requests that a DSN not be returned to the sender under
232 any conditions."
233 {Notify => ['NEVER']}
235 $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 }); # Good
237 You may use any combination of these three values
239 'SUCCESS','FAILURE','DELAY' in the anonymous array reference as
240 defined by RFC3461 (see http://rfc.net/rfc3461.html for more
241 information. Note: quotations in this topic from same.).
242 A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN
244 be issued on successful delivery or delivery failure,
245 respectively."
246 A Notify parameter of 'DELAY' "indicates the sender's willingness
248 to receive delayed DSNs. Delayed DSNs may be issued if delivery of
249 a message has been delayed for an unusual amount of time (as
250 determined by the Message Transfer Agent (MTA) at which the message
251 is delayed), but the final delivery status (whether successful or
252 failure) cannot be determined. The absence of the DELAY keyword in
253 a NOTIFY parameter requests that a "delayed" DSN NOT be issued
254 under any conditions."
255 {Notify => ['SUCCESS','FAILURE','DELAY']}
257 $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 }); # Good
259 ORcpt is also part of the SMTP DSN extension according to RFC3461.
261 It is used to pass along the original recipient that the mail was
262 first sent to. The machine that generates a DSN will use this
263 address to inform the sender, because he can't know if recipients
264 get rewritten by mail servers. It is expected to be in a format as
265 required by RFC3461, xtext-encoded.
266 to ( ADDRESS [, ADDRESS [...]] )
268 cc ( ADDRESS [, ADDRESS [...]] )
269 bcc ( ADDRESS [, ADDRESS [...]] )
270 Synonyms for "recipient".
271 data ( [ DATA ] )
273 Initiate the sending of the data from the current message.
274 "DATA" may be a reference to a list or a list. If specified the
276 contents of "DATA" and a termination string ".\r\n" is sent to the
277 server. And the result will be true if the data was accepted.
278 If "DATA" is not specified then the result will indicate that the
280 server wishes the data to be sent. The data must then be sent using
281 the "datasend" and "dataend" methods described in Net::Cmd.
282 expand ( ADDRESS )
284 Request the server to expand the given address Returns an array
285 which contains the text read from the server.
286 verify ( ADDRESS )
288 Verify that "ADDRESS" is a legitimate mailing address.
289 Most sites usually disable this feature in their SMTP service
291 configuration. Use "Debug => 1" option under new() to see if
292 disabled.
293 help ( [ $subject ] )
295 Request help text from the server. Returns the text or undef upon
296 failure
297 quit ()
299 Send the QUIT command to the remote SMTP server and close the
300 socket connection.
301
303 Net::SMTP attempts to DWIM with addresses that are passed. For example
304 an application might extract The From: line from an email and pass that
305 to mail(). While this may work, it is not recommended. The application
306 should really use a module like Mail::Address to extract the mail
307 address and pass that.
308 If "ExactAddresses" is passed to the constructor, then addresses should
310 be a valid rfc2821-quoted address, although Net::SMTP will accept
311 accept the address surrounded by angle brackets.
312 funny user@domain WRONG
314 "funny user"@domain RIGHT, recommended
315 <"funny user"@domain> OK
316
318 Net::Cmd
319
321 Graham Barr <gbarr@pobox.com>
322
324 Copyright (c) 1995-2004 Graham Barr. All rights reserved. This program
325 is free software; you can redistribute it and/or modify it under the
326 same terms as Perl itself.
327perl v5.16.3 2019-01-21 Net::SMTP(3pm)