Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Net::SMTP.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Net::SMTP 3pm"
61 .TH Net::SMTP 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Net::SMTP \- Simple Mail Transfer Protocol Client
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Net::SMTP;
72 \&
73 \& # Constructors
74 \& $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
75 \& $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq, Timeout => 60);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 This module implements a client interface to the SMTP and ESMTP
80 protocol, enabling a perl5 application to talk to SMTP servers. This
81 documentation assumes that you are familiar with the concepts of the
82 SMTP protocol described in RFC2821.
83 With IO::Socket::SSL installed it also provides support for implicit and
84 explicit TLS encryption, i.e. SMTPS or SMTP+STARTTLS.
85 .PP
86 The Net::SMTP class is a subclass of Net::Cmd and (depending on avaibility) of
87 IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
88 .SS "Class Methods"
89 .IX Subsection "Class Methods"
90 .ie n .IP """new([$host][, %options])""" 4
91 .el .IP "\f(CWnew([$host][, %options])\fR" 4
92 .IX Item "new([$host][, %options])"
93 This is the constructor for a new Net::SMTP object. \f(CW$host\fR is the
94 name of the remote host to which an SMTP connection is required.
95 .Sp
96 On failure \f(CW\*(C`undef\*(C'\fR will be returned and \f(CW$@\fR will contain the reason
97 for the failure.
98 .Sp
99 \&\f(CW$host\fR is optional. If \f(CW$host\fR is not given then it may instead be
100 passed as the \f(CW\*(C`Host\*(C'\fR option described below. If neither is given then
101 the \f(CW\*(C`SMTP_Hosts\*(C'\fR specified in \f(CW\*(C`Net::Config\*(C'\fR will be used.
102 .Sp
103 \&\f(CW%options\fR are passed in a hash like fashion, using key and value pairs.
104 Possible options are:
105 .Sp
106 \&\fBHello\fR \- SMTP requires that you identify yourself. This option
107 specifies a string to pass as your mail domain. If not given localhost.localdomain
108 will be used.
109 .Sp
110 \&\fBSendHello\fR \- If false then the EHLO (or HELO) command that is normally sent
111 when constructing the object will not be sent. In that case the command will
112 have to be sent manually by calling \f(CWhello()\fR instead.
113 .Sp
114 \&\fBHost\fR \- SMTP host to connect to. It may be a single scalar (hostname[:port]),
115 as defined for the \f(CW\*(C`PeerAddr\*(C'\fR option in IO::Socket::INET, or a reference to
116 an array with hosts to try in turn. The "host" method will return the value
117 which was used to connect to the host.
118 Format \- \f(CW\*(C`PeerHost\*(C'\fR from IO::Socket::INET new method.
119 .Sp
120 \&\fBPort\fR \- port to connect to.
121 Default \- 25 for plain SMTP and 465 for immediate SSL.
122 .Sp
123 \&\fBSSL\fR \- If the connection should be done from start with SSL, contrary to later
124 upgrade with \f(CW\*(C`starttls\*(C'\fR.
125 You can use SSL arguments as documented in IO::Socket::SSL, but it will
126 usually use the right arguments already.
127 .Sp
128 \&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly
129 to IO::Socket to allow binding the socket to a specific local address and port.
130 .Sp
131 \&\fBDomain\fR \- This parameter is passed directly to IO::Socket and makes it
132 possible to enforce IPv4 connections even if IO::Socket::IP is used as super
133 class. Alternatively \fBFamily\fR can be used.
134 .Sp
135 \&\fBTimeout\fR \- Maximum time, in seconds, to wait for a response from the
136 SMTP server (default: 120)
137 .Sp
138 \&\fBExactAddresses\fR \- If true then all \f(CW$address\fR arguments must be as
139 defined by \f(CW\*(C`addr\-spec\*(C'\fR in RFC2822. If not given, or false, then
140 Net::SMTP will attempt to extract the address from the value passed.
141 .Sp
142 \&\fBDebug\fR \- Enable debugging information
143 .Sp
144 Example:
145 .Sp
146 .Vb 5
147 \& $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq,
148 \& Hello => \*(Aqmy.mail.domain\*(Aq,
149 \& Timeout => 30,
150 \& Debug => 1,
151 \& );
152 \&
153 \& # the same
154 \& $smtp = Net::SMTP\->new(
155 \& Host => \*(Aqmailhost\*(Aq,
156 \& Hello => \*(Aqmy.mail.domain\*(Aq,
157 \& Timeout => 30,
158 \& Debug => 1,
159 \& );
160 \&
161 \& # the same with direct SSL
162 \& $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq,
163 \& Hello => \*(Aqmy.mail.domain\*(Aq,
164 \& Timeout => 30,
165 \& Debug => 1,
166 \& SSL => 1,
167 \& );
168 \&
169 \& # Connect to the default server from Net::config
170 \& $smtp = Net::SMTP\->new(
171 \& Hello => \*(Aqmy.mail.domain\*(Aq,
172 \& Timeout => 30,
173 \& );
174 .Ve
175 .SH "Object Methods"
176 .IX Header "Object Methods"
177 Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR
178 value, with \fItrue\fR meaning that the operation was a success. When a method
179 states that it returns a value, failure will be returned as \fIundef\fR or an
180 empty list.
181 .PP
182 \&\f(CW\*(C`Net::SMTP\*(C'\fR inherits from \f(CW\*(C`Net::Cmd\*(C'\fR so methods defined in \f(CW\*(C`Net::Cmd\*(C'\fR may
183 be used to send commands to the remote SMTP server in addition to the methods
184 documented here.
185 .ie n .IP banner() 4
186 .el .IP \f(CWbanner()\fR 4
187 .IX Item "banner()"
188 Returns the banner message which the server replied with when the
189 initial connection was made.
190 .ie n .IP domain() 4
191 .el .IP \f(CWdomain()\fR 4
192 .IX Item "domain()"
193 Returns the domain that the remote SMTP server identified itself as during
194 connection.
195 .ie n .IP hello($domain) 4
196 .el .IP \f(CWhello($domain)\fR 4
197 .IX Item "hello($domain)"
198 Tell the remote server the mail domain which you are in using the EHLO
199 command (or HELO if EHLO fails). Since this method is invoked
200 automatically when the Net::SMTP object is constructed the user should
201 normally not have to call it manually.
202 .ie n .IP host() 4
203 .el .IP \f(CWhost()\fR 4
204 .IX Item "host()"
205 Returns the value used by the constructor, and passed to IO::Socket::INET,
206 to connect to the host.
207 .ie n .IP etrn($domain) 4
208 .el .IP \f(CWetrn($domain)\fR 4
209 .IX Item "etrn($domain)"
210 Request a queue run for the \f(CW$domain\fR given.
211 .ie n .IP starttls(%sslargs) 4
212 .el .IP \f(CWstarttls(%sslargs)\fR 4
213 .IX Item "starttls(%sslargs)"
214 Upgrade existing plain connection to SSL.
215 You can use SSL arguments as documented in IO::Socket::SSL, but it will
216 usually use the right arguments already.
217 .ie n .IP """auth($username, $password)""" 4
218 .el .IP "\f(CWauth($username, $password)\fR" 4
219 .IX Item "auth($username, $password)"
220 .PD 0
221 .ie n .IP auth($sasl) 4
222 .el .IP \f(CWauth($sasl)\fR 4
223 .IX Item "auth($sasl)"
224 .PD
225 Attempt SASL authentication. Requires Authen::SASL module. The first form
226 constructs a new Authen::SASL object using the given username and password;
227 the second form uses the given Authen::SASL object.
228 .ie n .IP """mail($address[, %options])""" 4
229 .el .IP "\f(CWmail($address[, %options])\fR" 4
230 .IX Item "mail($address[, %options])"
231 .PD 0
232 .ie n .IP send($address) 4
233 .el .IP \f(CWsend($address)\fR 4
234 .IX Item "send($address)"
235 .ie n .IP send_or_mail($address) 4
236 .el .IP \f(CWsend_or_mail($address)\fR 4
237 .IX Item "send_or_mail($address)"
238 .ie n .IP send_and_mail($address) 4
239 .el .IP \f(CWsend_and_mail($address)\fR 4
240 .IX Item "send_and_mail($address)"
241 .PD
242 Send the appropriate command to the server MAIL, SEND, SOML or SAML. \f(CW$address\fR
243 is the address of the sender. This initiates the sending of a message. The
244 method \f(CW\*(C`recipient\*(C'\fR should be called for each address that the message is to
245 be sent to.
246 .Sp
247 The \f(CW\*(C`mail\*(C'\fR method can take some additional ESMTP \f(CW%options\fR which is passed
248 in hash like fashion, using key and value pairs. Possible options are:
249 .Sp
250 .Vb 8
251 \& Size => <bytes>
252 \& Return => "FULL" | "HDRS"
253 \& Bits => "7" | "8" | "binary"
254 \& Transaction => <ADDRESS>
255 \& Envelope => <ENVID> # xtext\-encodes its argument
256 \& ENVID => <ENVID> # similar to Envelope, but expects argument encoded
257 \& XVERP => 1
258 \& AUTH => <submitter> # encoded address according to RFC 2554
259 .Ve
260 .Sp
261 The \f(CW\*(C`Return\*(C'\fR and \f(CW\*(C`Envelope\*(C'\fR parameters are used for DSN (Delivery
262 Status Notification).
263 .Sp
264 The submitter address in \f(CW\*(C`AUTH\*(C'\fR option is expected to be in a format as
265 required by RFC 2554, in an RFC2821\-quoted form and xtext\-encoded, or <> .
266 .ie n .IP reset() 4
267 .el .IP \f(CWreset()\fR 4
268 .IX Item "reset()"
269 Reset the status of the server. This may be called after a message has been
270 initiated, but before any data has been sent, to cancel the sending of the
271 message.
272 .ie n .IP """recipient($address[, $address[, ...]][, %options])""" 4
273 .el .IP "\f(CWrecipient($address[, $address[, ...]][, %options])\fR" 4
274 .IX Item "recipient($address[, $address[, ...]][, %options])"
275 Notify the server that the current message should be sent to all of the
276 addresses given. Each address is sent as a separate command to the server.
277 Should the sending of any address result in a failure then the process is
278 aborted and a \fIfalse\fR value is returned. It is up to the user to call
279 \&\f(CW\*(C`reset\*(C'\fR if they so desire.
280 .Sp
281 The \f(CW\*(C`recipient\*(C'\fR method can also pass additional case\-sensitive \f(CW%options\fR as an
282 anonymous hash using key and value pairs. Possible options are:
283 .Sp
284 .Vb 3
285 \& Notify => [\*(AqNEVER\*(Aq] or [\*(AqSUCCESS\*(Aq,\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq] (see below)
286 \& ORcpt => <ORCPT>
287 \& SkipBad => 1 (to ignore bad addresses)
288 .Ve
289 .Sp
290 If \f(CW\*(C`SkipBad\*(C'\fR is true the \f(CW\*(C`recipient\*(C'\fR will not return an error when a bad
291 address is encountered and it will return an array of addresses that did
292 succeed.
293 .Sp
294 .Vb 5
295 \& $smtp\->recipient($recipient1,$recipient2); # Good
296 \& $smtp\->recipient($recipient1,$recipient2, { SkipBad => 1 }); # Good
297 \& $smtp\->recipient($recipient1,$recipient2, { Notify => [\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq], SkipBad => 1 }); # Good
298 \& @goodrecips=$smtp\->recipient(@recipients, { Notify => [\*(AqFAILURE\*(Aq], SkipBad => 1 }); # Good
299 \& $smtp\->recipient("$recipient,$recipient2"); # BAD
300 .Ve
301 .Sp
302 Notify is used to request Delivery Status Notifications (DSNs), but your
303 SMTP/ESMTP service may not respect this request depending upon its version and
304 your site\*(Aqs SMTP configuration.
305 .Sp
306 Leaving out the Notify option usually defaults an SMTP service to its default
307 behavior equivalent to [\*(AqFAILURE\*(Aq] notifications only, but again this may be
308 dependent upon your site\*(Aqs SMTP configuration.
309 .Sp
310 The NEVER keyword must appear by itself if used within the Notify option and "requests
311 that a DSN not be returned to the sender under any conditions."
312 .Sp
313 .Vb 1
314 \& {Notify => [\*(AqNEVER\*(Aq]}
315 \&
316 \& $smtp\->recipient(@recipients, { Notify => [\*(AqNEVER\*(Aq], SkipBad => 1 }); # Good
317 .Ve
318 .Sp
319 You may use any combination of these three values \*(AqSUCCESS\*(Aq,\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq in
320 the anonymous array reference as defined by RFC3461 (see
321 <https://www.ietf.org/rfc/rfc3461.txt> for more information. Note: quotations
322 in this topic from same.).
323 .Sp
324 A Notify parameter of \*(AqSUCCESS\*(Aq or \*(AqFAILURE\*(Aq "requests that a DSN be issued on
325 successful delivery or delivery failure, respectively."
326 .Sp
327 A Notify parameter of \*(AqDELAY\*(Aq "indicates the sender\*(Aqs willingness to receive
328 delayed DSNs. Delayed DSNs may be issued if delivery of a message has been
329 delayed for an unusual amount of time (as determined by the Message Transfer
330 Agent (MTA) at which the message is delayed), but the final delivery status
331 (whether successful or failure) cannot be determined. The absence of the DELAY
332 keyword in a NOTIFY parameter requests that a "delayed" DSN NOT be issued under
333 any conditions."
334 .Sp
335 .Vb 1
336 \& {Notify => [\*(AqSUCCESS\*(Aq,\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq]}
337 \&
338 \& $smtp\->recipient(@recipients, { Notify => [\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq], SkipBad => 1 }); # Good
339 .Ve
340 .Sp
341 ORcpt is also part of the SMTP DSN extension according to RFC3461.
342 It is used to pass along the original recipient that the mail was first
343 sent to. The machine that generates a DSN will use this address to inform
344 the sender, because he can\*(Aqt know if recipients get rewritten by mail servers.
345 It is expected to be in a format as required by RFC3461, xtext\-encoded.
346 .ie n .IP """to($address[, $address[, ...]])""" 4
347 .el .IP "\f(CWto($address[, $address[, ...]])\fR" 4
348 .IX Item "to($address[, $address[, ...]])"
349 .PD 0
350 .ie n .IP """cc($address[, $address[, ...]])""" 4
351 .el .IP "\f(CWcc($address[, $address[, ...]])\fR" 4
352 .IX Item "cc($address[, $address[, ...]])"
353 .ie n .IP """bcc($address[, $address[, ...]])""" 4
354 .el .IP "\f(CWbcc($address[, $address[, ...]])\fR" 4
355 .IX Item "bcc($address[, $address[, ...]])"
356 .PD
357 Synonyms for \f(CW\*(C`recipient\*(C'\fR.
358 .ie n .IP data([$data]) 4
359 .el .IP \f(CWdata([$data])\fR 4
360 .IX Item "data([$data])"
361 Initiate the sending of the data from the current message.
362 .Sp
363 \&\f(CW$data\fR may be a reference to a list or a list and must be encoded by the
364 caller to octets of whatever encoding is required, e.g. by using the Encode
365 module\*(Aqs \f(CWencode()\fR function.
366 .Sp
367 If specified the contents of \f(CW$data\fR and a termination string \f(CW".\er\en"\fR is
368 sent to the server. The result will be true if the data was accepted.
369 .Sp
370 If \f(CW$data\fR is not specified then the result will indicate that the server
371 wishes the data to be sent. The data must then be sent using the \f(CW\*(C`datasend\*(C'\fR
372 and \f(CW\*(C`dataend\*(C'\fR methods described in Net::Cmd.
373 .ie n .IP bdat($data) 4
374 .el .IP \f(CWbdat($data)\fR 4
375 .IX Item "bdat($data)"
376 .PD 0
377 .ie n .IP bdatlast($data) 4
378 .el .IP \f(CWbdatlast($data)\fR 4
379 .IX Item "bdatlast($data)"
380 .PD
381 Use the alternate \f(CW$data\fR command "BDAT" of the data chunking service extension
382 defined in RFC1830 for efficiently sending large MIME messages.
383 .ie n .IP expand($address) 4
384 .el .IP \f(CWexpand($address)\fR 4
385 .IX Item "expand($address)"
386 Request the server to expand the given address Returns an array
387 which contains the text read from the server.
388 .ie n .IP verify($address) 4
389 .el .IP \f(CWverify($address)\fR 4
390 .IX Item "verify($address)"
391 Verify that \f(CW$address\fR is a legitimate mailing address.
392 .Sp
393 Most sites usually disable this feature in their SMTP service configuration.
394 Use "Debug => 1" option under \fBnew()\fR to see if disabled.
395 .ie n .IP help([$subject]) 4
396 .el .IP \f(CWhelp([$subject])\fR 4
397 .IX Item "help([$subject])"
398 Request help text from the server. Returns the text or undef upon failure
399 .ie n .IP quit() 4
400 .el .IP \f(CWquit()\fR 4
401 .IX Item "quit()"
402 Send the QUIT command to the remote SMTP server and close the socket connection.
403 .ie n .IP can_inet6() 4
404 .el .IP \f(CWcan_inet6()\fR 4
405 .IX Item "can_inet6()"
406 Returns whether we can use IPv6.
407 .ie n .IP can_ssl() 4
408 .el .IP \f(CWcan_ssl()\fR 4
409 .IX Item "can_ssl()"
410 Returns whether we can use SSL.
411 .SS Addresses
412 .IX Subsection "Addresses"
413 Net::SMTP attempts to DWIM with addresses that are passed. For
414 example an application might extract The From: line from an email
415 and pass that to \fBmail()\fR. While this may work, it is not recommended.
416 The application should really use a module like Mail::Address
417 to extract the mail address and pass that.
418 .PP
419 If \f(CW\*(C`ExactAddresses\*(C'\fR is passed to the constructor, then addresses
420 should be a valid rfc2821\-quoted address, although Net::SMTP will
421 accept the address surrounded by angle brackets.
422 .PP
423 .Vb 3
424 \& funny user@domain WRONG
425 \& "funny user"@domain RIGHT, recommended
426 \& <"funny user"@domain> OK
427 .Ve
428 .SH EXAMPLES
429 .IX Header "EXAMPLES"
430 This example prints the mail domain name of the SMTP server known as mailhost:
431 .PP
432 .Vb 1
433 \& #!/usr/local/bin/perl \-w
434 \&
435 \& use Net::SMTP;
436 \&
437 \& $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
438 \& print $smtp\->domain,"\en";
439 \& $smtp\->quit;
440 .Ve
441 .PP
442 This example sends a small message to the postmaster at the SMTP server
443 known as mailhost:
444 .PP
445 .Vb 1
446 \& #!/usr/local/bin/perl \-w
447 \&
448 \& use Net::SMTP;
449 \&
450 \& my $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
451 \&
452 \& $smtp\->mail($ENV{USER});
453 \& if ($smtp\->to(\*(Aqpostmaster\*(Aq)) {
454 \& $smtp\->data();
455 \& $smtp\->datasend("To: postmaster\en");
456 \& $smtp\->datasend("\en");
457 \& $smtp\->datasend("A simple test message\en");
458 \& $smtp\->dataend();
459 \& } else {
460 \& print "Error: ", $smtp\->message();
461 \& }
462 \&
463 \& $smtp\->quit;
464 .Ve
465 .SH EXPORTS
466 .IX Header "EXPORTS"
467 \&\fINone\fR.
468 .SH "KNOWN BUGS"
469 .IX Header "KNOWN BUGS"
470 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
471 .SH "SEE ALSO"
472 .IX Header "SEE ALSO"
473 Net::Cmd,
474 IO::Socket::SSL.
475 .SH AUTHOR
476 .IX Header "AUTHOR"
477 Graham Barr <[email protected] <mailto:[email protected]>>.
478 .PP
479 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
480 libnet as of version 1.22_02.
481 .SH COPYRIGHT
482 .IX Header "COPYRIGHT"
483 Copyright (C) 1995\-2004 Graham Barr. All rights reserved.
484 .PP
485 Copyright (C) 2013\-2016, 2020 Steve Hay. All rights reserved.
486 .SH LICENCE
487 .IX Header "LICENCE"
488 This module is free software; you can redistribute it and/or modify it under the
489 same terms as Perl itself, i.e. under the terms of either the GNU General Public
490 License or the Artistic License, as specified in the \fILICENCE\fR file.
491 .SH VERSION
492 .IX Header "VERSION"
493 Version 3.15
494 .SH DATE
495 .IX Header "DATE"
496 20 March 2023
497 .SH HISTORY
498 .IX Header "HISTORY"
499 See the \fIChanges\fR file.