1Net::SMTP(3)          User Contributed Perl Documentation         Net::SMTP(3)
2
3
4

NAME

6       Net::SMTP - Simple Mail Transfer Protocol Client
7

SYNOPSIS

9           use Net::SMTP;
10
11           # Constructors
12           $smtp = Net::SMTP->new('mailhost');
13           $smtp = Net::SMTP->new('mailhost', Timeout => 60);
14

DESCRIPTION

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
23       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
26   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
31           On failure "undef" will be returned and $@ will contain the reason
32           for the failure.
33
34           $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
38           %options are passed in a hash like fashion, using key and value
39           pairs.  Possible options are:
40
41           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
45           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
50           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
57           Port - port to connect to.  Default - 25 for plain SMTP and 465 for
58           immediate SSL.
59
60           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
65           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
69           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
73           Timeout - Maximum time, in seconds, to wait for a response from the
74           SMTP server (default: 120)
75
76           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
81           Debug - Enable debugging information
82
83           Example:
84
85               $smtp = Net::SMTP->new('mailhost',
86                                      Hello => 'my.mail.domain',
87                                      Timeout => 30,
88                                      Debug   => 1,
89                                     );
90
91               # the same
92               $smtp = Net::SMTP->new(
93                                      Host => 'mailhost',
94                                      Hello => 'my.mail.domain',
95                                      Timeout => 30,
96                                      Debug   => 1,
97                                     );
98
99               # 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
107               # Connect to the default server from Net::config
108               $smtp = Net::SMTP->new(
109                                      Hello => 'my.mail.domain',
110                                      Timeout => 30,
111                                     );
112

Object Methods

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
119       "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
123       banner()
124           Returns the banner message which the server replied with when the
125           initial connection was made.
126
127       domain()
128           Returns the domain that the remote SMTP server identified itself as
129           during connection.
130
131       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
137       host()
138           Returns the value used by the constructor, and passed to
139           IO::Socket::INET, to connect to the host.
140
141       etrn($domain)
142           Request a queue run for the $domain given.
143
144       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
149       "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
156       "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
165           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
169            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
178           The "Return" and "Envelope" parameters are used for DSN (Delivery
179           Status Notification).
180
181           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
185       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
190       "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
197           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
201             Notify  => ['NEVER'] or ['SUCCESS','FAILURE','DELAY']  (see below)
202             ORcpt   => <ORCPT>
203             SkipBad => 1        (to ignore bad addresses)
204
205           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
209             $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
215           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
219           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
224           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
228             {Notify => ['NEVER']}
229
230             $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 });  # Good
231
232           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
237           A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN
238           be issued on successful delivery or delivery failure,
239           respectively."
240
241           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
250             {Notify => ['SUCCESS','FAILURE','DELAY']}
251
252             $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
253
254           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
261       "to($address[, $address[, ...]])"
262       "cc($address[, $address[, ...]])"
263       "bcc($address[, $address[, ...]])"
264           Synonyms for "recipient".
265
266       data([$data])
267           Initiate the sending of the data from the current message.
268
269           $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
273           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
277           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
281       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
287       expand($address)
288           Request the server to expand the given address Returns an array
289           which contains the text read from the server.
290
291       verify($address)
292           Verify that $address is a legitimate mailing address.
293
294           Most sites usually disable this feature in their SMTP service
295           configuration.  Use "Debug => 1" option under new() to see if
296           disabled.
297
298       help([$subject])
299           Request help text from the server. Returns the text or undef upon
300           failure
301
302       quit()
303           Send the QUIT command to the remote SMTP server and close the
304           socket connection.
305
306       can_inet6()
307           Returns whether we can use IPv6.
308
309       can_ssl()
310           Returns whether we can use SSL.
311
312   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
319       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
323        funny user@domain      WRONG
324        "funny user"@domain    RIGHT, recommended
325        <"funny user"@domain>  OK
326

EXAMPLES

328       This example prints the mail domain name of the SMTP server known as
329       mailhost:
330
331           #!/usr/local/bin/perl -w
332
333           use Net::SMTP;
334
335           $smtp = Net::SMTP->new('mailhost');
336           print $smtp->domain,"\n";
337           $smtp->quit;
338
339       This example sends a small message to the postmaster at the SMTP server
340       known as mailhost:
341
342           #!/usr/local/bin/perl -w
343
344           use Net::SMTP;
345
346           my $smtp = Net::SMTP->new('mailhost');
347
348           $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
359           $smtp->quit;
360

EXPORTS

362       None.
363

KNOWN BUGS

365       See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
366

SEE ALSO

368       Net::Cmd, IO::Socket::SSL.
369

AUTHOR

371       Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.
372
373       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
379       Copyright (C) 2013-2016, 2020 Steve Hay.  All rights reserved.
380

LICENCE

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

VERSION

388       Version 3.15
389

DATE

391       20 March 2023
392

HISTORY

394       See the Changes file.
395
396
397
398perl v5.36.0                      2023-03-21                      Net::SMTP(3)
Impressum