1Net::SMTP(3) User Contributed Perl Documentation Net::SMTP(3)
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 RFC2821. With IO::Socket::SSL installed it
20 also provides support for implicit and explicit TLS encryption, i.e.
21 SMTPS or SMTP+STARTTLS.
22 The Net::SMTP class is a subclass of Net::Cmd and (depending on
24 avaibility) of IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
25 Class Methods
27 "new([$host][, %options])"
28 This is the constructor for a new Net::SMTP object. $host is the
29 name of the remote host to which an SMTP connection is required.
30 On failure "undef" will be returned and $@ will contain the reason
32 for the failure.
33 $host is optional. If $host is not given then it may instead be
35 passed as the "Host" option described below. If neither is given
36 then the "SMTP_Hosts" specified in "Net::Config" will be used.
37 %options are passed in a hash like fashion, using key and value
39 pairs. Possible options are:
40 Hello - SMTP requires that you identify yourself. This option
42 specifies a string to pass as your mail domain. If not given
43 localhost.localdomain will be used.
44 SendHello - If false then the EHLO (or HELO) command that is
46 normally sent when constructing the object will not be sent. In
47 that case the command will have to be sent manually by calling
48 hello() instead.
49 Host - SMTP host to connect to. It may be a single scalar
51 (hostname[:port]), as defined for the "PeerAddr" option in
52 IO::Socket::INET, or a reference to an array with hosts to try in
53 turn. The "host" method will return the value which was used to
54 connect to the host. Format - "PeerHost" from IO::Socket::INET new
55 method.
56 Port - port to connect to. Default - 25 for plain SMTP and 465 for
58 immediate SSL.
59 SSL - If the connection should be done from start with SSL,
61 contrary to later upgrade with "starttls". You can use SSL
62 arguments as documented in IO::Socket::SSL, but it will usually use
63 the right arguments already.
64 LocalAddr and LocalPort - These parameters are passed directly to
66 IO::Socket to allow binding the socket to a specific local address
67 and port.
68 Domain - This parameter is passed directly to IO::Socket and makes
70 it possible to enforce IPv4 connections even if IO::Socket::IP is
71 used as super class. Alternatively Family can be used.
72 Timeout - Maximum time, in seconds, to wait for a response from the
74 SMTP server (default: 120)
75 ExactAddresses - If true then all $address arguments must be as
77 defined by "addr-spec" in RFC2822. If not given, or false, then
78 Net::SMTP will attempt to extract the address from the value
79 passed.
80 Debug - Enable debugging information
82 Example:
84 $smtp = Net::SMTP->new('mailhost',
86 Hello => 'my.mail.domain',
87 Timeout => 30,
88 Debug => 1,
89 );
90 # the same
92 $smtp = Net::SMTP->new(
93 Host => 'mailhost',
94 Hello => 'my.mail.domain',
95 Timeout => 30,
96 Debug => 1,
97 );
98 # the same with direct SSL
100 $smtp = Net::SMTP->new('mailhost',
101 Hello => 'my.mail.domain',
102 Timeout => 30,
103 Debug => 1,
104 SSL => 1,
105 );
106 # Connect to the default server from Net::config
108 $smtp = Net::SMTP->new(
109 Hello => 'my.mail.domain',
110 Timeout => 30,
111 );
112
114 Unless otherwise stated all methods return either a true or false
115 value, with true meaning that the operation was a success. When a
116 method states that it returns a value, failure will be returned as
117 undef or an empty list.
118 "Net::SMTP" inherits from "Net::Cmd" so methods defined in "Net::Cmd"
120 may be used to send commands to the remote SMTP server in addition to
121 the methods documented here.
122 banner()
124 Returns the banner message which the server replied with when the
125 initial connection was made.
126 domain()
128 Returns the domain that the remote SMTP server identified itself as
129 during connection.
130 hello($domain)
132 Tell the remote server the mail domain which you are in using the
133 EHLO command (or HELO if EHLO fails). Since this method is invoked
134 automatically when the Net::SMTP object is constructed the user
135 should normally not have to call it manually.
136 host()
138 Returns the value used by the constructor, and passed to
139 IO::Socket::INET, to connect to the host.
140 etrn($domain)
142 Request a queue run for the $domain given.
143 starttls(%sslargs)
145 Upgrade existing plain connection to SSL. You can use SSL
146 arguments as documented in IO::Socket::SSL, but it will usually use
147 the right arguments already.
148 "auth($username, $password)"
150 auth($sasl)
151 Attempt SASL authentication. Requires Authen::SASL module. The
152 first form constructs a new Authen::SASL object using the given
153 username and password; the second form uses the given Authen::SASL
154 object.
155 "mail($address[, %options])"
157 send($address)
158 send_or_mail($address)
159 send_and_mail($address)
160 Send the appropriate command to the server MAIL, SEND, SOML or
161 SAML. $address is the address of the sender. This initiates the
162 sending of a message. The method "recipient" should be called for
163 each address that the message is to be sent to.
164 The "mail" method can take some additional ESMTP %options which is
166 passed in hash like fashion, using key and value pairs. Possible
167 options are:
168 Size => <bytes>
170 Return => "FULL" | "HDRS"
171 Bits => "7" | "8" | "binary"
172 Transaction => <ADDRESS>
173 Envelope => <ENVID> # xtext-encodes its argument
174 ENVID => <ENVID> # similar to Envelope, but expects argument encoded
175 XVERP => 1
176 AUTH => <submitter> # encoded address according to RFC 2554
177 The "Return" and "Envelope" parameters are used for DSN (Delivery
179 Status Notification).
180 The submitter address in "AUTH" option is expected to be in a
182 format as required by RFC 2554, in an RFC2821-quoted form and
183 xtext-encoded, or <> .
184 reset()
186 Reset the status of the server. This may be called after a message
187 has been initiated, but before any data has been sent, to cancel
188 the sending of the message.
189 "recipient($address[, $address[, ...]][, %options])"
191 Notify the server that the current message should be sent to all of
192 the addresses given. Each address is sent as a separate command to
193 the server. Should the sending of any address result in a failure
194 then the process is aborted and a false value is returned. It is up
195 to the user to call "reset" if they so desire.
196 The "recipient" method can also pass additional case-sensitive
198 %options as an anonymous hash using key and value pairs. Possible
199 options are:
200 Notify => ['NEVER'] or ['SUCCESS','FAILURE','DELAY'] (see below)
202 ORcpt => <ORCPT>
203 SkipBad => 1 (to ignore bad addresses)
204 If "SkipBad" is true the "recipient" will not return an error when
206 a bad address is encountered and it will return an array of
207 addresses that did succeed.
208 $smtp->recipient($recipient1,$recipient2); # Good
210 $smtp->recipient($recipient1,$recipient2, { SkipBad => 1 }); # Good
211 $smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 }); # Good
212 @goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 }); # Good
213 $smtp->recipient("$recipient,$recipient2"); # BAD
214 Notify is used to request Delivery Status Notifications (DSNs), but
216 your SMTP/ESMTP service may not respect this request depending upon
217 its version and your site's SMTP configuration.
218 Leaving out the Notify option usually defaults an SMTP service to
220 its default behavior equivalent to ['FAILURE'] notifications only,
221 but again this may be dependent upon your site's SMTP
222 configuration.
223 The NEVER keyword must appear by itself if used within the Notify
225 option and "requests that a DSN not be returned to the sender under
226 any conditions."
227 {Notify => ['NEVER']}
229 $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 }); # Good
231 You may use any combination of these three values
233 'SUCCESS','FAILURE','DELAY' in the anonymous array reference as
234 defined by RFC3461 (see <https://www.ietf.org/rfc/rfc3461.txt> for
235 more information. Note: quotations in this topic from same.).
236 A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN
238 be issued on successful delivery or delivery failure,
239 respectively."
240 A Notify parameter of 'DELAY' "indicates the sender's willingness
242 to receive delayed DSNs. Delayed DSNs may be issued if delivery of
243 a message has been delayed for an unusual amount of time (as
244 determined by the Message Transfer Agent (MTA) at which the message
245 is delayed), but the final delivery status (whether successful or
246 failure) cannot be determined. The absence of the DELAY keyword in
247 a NOTIFY parameter requests that a "delayed" DSN NOT be issued
248 under any conditions."
249 {Notify => ['SUCCESS','FAILURE','DELAY']}
251 $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 }); # Good
253 ORcpt is also part of the SMTP DSN extension according to RFC3461.
255 It is used to pass along the original recipient that the mail was
256 first sent to. The machine that generates a DSN will use this
257 address to inform the sender, because he can't know if recipients
258 get rewritten by mail servers. It is expected to be in a format as
259 required by RFC3461, xtext-encoded.
260 "to($address[, $address[, ...]])"
262 "cc($address[, $address[, ...]])"
263 "bcc($address[, $address[, ...]])"
264 Synonyms for "recipient".
265 data([$data])
267 Initiate the sending of the data from the current message.
268 $data may be a reference to a list or a list and must be encoded by
270 the caller to octets of whatever encoding is required, e.g. by
271 using the Encode module's encode() function.
272 If specified the contents of $data and a termination string ".\r\n"
274 is sent to the server. The result will be true if the data was
275 accepted.
276 If $data is not specified then the result will indicate that the
278 server wishes the data to be sent. The data must then be sent using
279 the "datasend" and "dataend" methods described in Net::Cmd.
280 bdat($data)
282 bdatlast($data)
283 Use the alternate $data command "BDAT" of the data chunking service
284 extension defined in RFC1830 for efficiently sending large MIME
285 messages.
286 expand($address)
288 Request the server to expand the given address Returns an array
289 which contains the text read from the server.
290 verify($address)
292 Verify that $address is a legitimate mailing address.
293 Most sites usually disable this feature in their SMTP service
295 configuration. Use "Debug => 1" option under new() to see if
296 disabled.
297 help([$subject])
299 Request help text from the server. Returns the text or undef upon
300 failure
301 quit()
303 Send the QUIT command to the remote SMTP server and close the
304 socket connection.
305 can_inet6()
307 Returns whether we can use IPv6.
308 can_ssl()
310 Returns whether we can use SSL.
311 Addresses
313 Net::SMTP attempts to DWIM with addresses that are passed. For example
314 an application might extract The From: line from an email and pass that
315 to mail(). While this may work, it is not recommended. The application
316 should really use a module like Mail::Address to extract the mail
317 address and pass that.
318 If "ExactAddresses" is passed to the constructor, then addresses should
320 be a valid rfc2821-quoted address, although Net::SMTP will accept the
321 address surrounded by angle brackets.
322 funny user@domain WRONG
324 "funny user"@domain RIGHT, recommended
325 <"funny user"@domain> OK
326
328 This example prints the mail domain name of the SMTP server known as
329 mailhost:
330 #!/usr/local/bin/perl -w
332 use Net::SMTP;
334 $smtp = Net::SMTP->new('mailhost');
336 print $smtp->domain,"\n";
337 $smtp->quit;
338 This example sends a small message to the postmaster at the SMTP server
340 known as mailhost:
341 #!/usr/local/bin/perl -w
343 use Net::SMTP;
345 my $smtp = Net::SMTP->new('mailhost');
347 $smtp->mail($ENV{USER});
349 if ($smtp->to('postmaster')) {
350 $smtp->data();
351 $smtp->datasend("To: postmaster\n");
352 $smtp->datasend("\n");
353 $smtp->datasend("A simple test message\n");
354 $smtp->dataend();
355 } else {
356 print "Error: ", $smtp->message();
357 }
358 $smtp->quit;
360
362 None.
363
365 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
366
368 Net::Cmd, IO::Socket::SSL.
369
371 Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.
372 Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining
374 libnet as of version 1.22_02.
375
377 Copyright (C) 1995-2004 Graham Barr. All rights reserved.
378 Copyright (C) 2013-2016, 2020 Steve Hay. All rights reserved.
380
382 This module is free software; you can redistribute it and/or modify it
383 under the same terms as Perl itself, i.e. under the terms of either the
384 GNU General Public License or the Artistic License, as specified in the
385 LICENCE file.
386
388 Version 3.15
389
391 20 March 2023
392
394 See the Changes file.
395perl v5.36.0 2023-03-21 Net::SMTP(3)