.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::SMTP 3"
.TH Net::SMTP 3 "2021-08-09" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::SMTP \- Simple Mail Transfer Protocol Client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::SMTP;
\&
\&    # Constructors
\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq, Timeout => 60);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements a client interface to the \s-1SMTP\s0 and \s-1ESMTP\s0
protocol, enabling a perl5 application to talk to \s-1SMTP\s0 servers. This
documentation assumes that you are familiar with the concepts of the
\&\s-1SMTP\s0 protocol described in \s-1RFC2821.\s0
With IO::Socket::SSL installed it also provides support for implicit and
explicit \s-1TLS\s0 encryption, i.e. \s-1SMTPS\s0 or \s-1SMTP+STARTTLS.\s0
.PP
The Net::SMTP class is a subclass of Net::Cmd and (depending on avaibility) of
IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
.SS "Class Methods"
.IX Subsection "Class Methods"
.ie n .IP """new([$host][, %options])""" 4
.el .IP "\f(CWnew([$host][, %options])\fR" 4
.IX Item "new([$host][, %options])"
This is the constructor for a new Net::SMTP object. \f(CW$host\fR is the
name of the remote host to which an \s-1SMTP\s0 connection is required.
.Sp
On failure \f(CW\*(C`undef\*(C'\fR will be returned and \f(CW$@\fR will contain the reason
for the failure.
.Sp
\&\f(CW$host\fR is optional. If \f(CW$host\fR is not given then it may instead be
passed as the \f(CW\*(C`Host\*(C'\fR option described below. If neither is given then
the \f(CW\*(C`SMTP_Hosts\*(C'\fR specified in \f(CW\*(C`Net::Config\*(C'\fR will be used.
.Sp
\&\f(CW%options\fR are passed in a hash like fashion, using key and value pairs.
Possible options are:
.Sp
\&\fBHello\fR \- \s-1SMTP\s0 requires that you identify yourself. This option
specifies a string to pass as your mail domain. If not given localhost.localdomain
will be used.
.Sp
\&\fBSendHello\fR \- If false then the \s-1EHLO\s0 (or \s-1HELO\s0) command that is normally sent
when constructing the object will not be sent. In that case the command will
have to be sent manually by calling \f(CW\*(C`hello()\*(C'\fR instead.
.Sp
\&\fBHost\fR \- \s-1SMTP\s0 host to connect to. It may be a single scalar (hostname[:port]),
as defined for the \f(CW\*(C`PeerAddr\*(C'\fR option in IO::Socket::INET, or a reference to
an array with hosts to try in turn. The \*(L"host\*(R" method will return the value
which was used to connect to the host.
Format \- \f(CW\*(C`PeerHost\*(C'\fR from IO::Socket::INET new method.
.Sp
\&\fBPort\fR \- port to connect to.
Default \- 25 for plain \s-1SMTP\s0 and 465 for immediate \s-1SSL.\s0
.Sp
\&\fB\s-1SSL\s0\fR \- If the connection should be done from start with \s-1SSL,\s0 contrary to later
upgrade with \f(CW\*(C`starttls\*(C'\fR.
You can use \s-1SSL\s0 arguments as documented in IO::Socket::SSL, but it will
usually use the right arguments already.
.Sp
\&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly
to IO::Socket to allow binding the socket to a specific local address and port.
.Sp
\&\fBDomain\fR \- This parameter is passed directly to IO::Socket and makes it
possible to enforce IPv4 connections even if IO::Socket::IP is used as super
class. Alternatively \fBFamily\fR can be used.
.Sp
\&\fBTimeout\fR \- Maximum time, in seconds, to wait for a response from the
\&\s-1SMTP\s0 server (default: 120)
.Sp
\&\fBExactAddresses\fR \- If true then all \f(CW$address\fR arguments must be as
defined by \f(CW\*(C`addr\-spec\*(C'\fR in \s-1RFC2822.\s0 If not given, or false, then
Net::SMTP will attempt to extract the address from the value passed.
.Sp
\&\fBDebug\fR \- Enable debugging information
.Sp
Example:
.Sp
.Vb 5
\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq,
\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
\&                           Timeout => 30,
\&                           Debug   => 1,
\&                          );
\&
\&    # the same
\&    $smtp = Net::SMTP\->new(
\&                           Host => \*(Aqmailhost\*(Aq,
\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
\&                           Timeout => 30,
\&                           Debug   => 1,
\&                          );
\&
\&    # the same with direct SSL
\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq,
\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
\&                           Timeout => 30,
\&                           Debug   => 1,
\&                           SSL     => 1,
\&                          );
\&
\&    # Connect to the default server from Net::config
\&    $smtp = Net::SMTP\->new(
\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
\&                           Timeout => 30,
\&                          );
.Ve
.SH "Object Methods"
.IX Header "Object Methods"
Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR
value, with \fItrue\fR meaning that the operation was a success. When a method
states that it returns a value, failure will be returned as \fIundef\fR or an
empty list.
.PP
\&\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
be used to send commands to the remote \s-1SMTP\s0 server in addition to the methods
documented here.
.ie n .IP """banner()""" 4
.el .IP "\f(CWbanner()\fR" 4
.IX Item "banner()"
Returns the banner message which the server replied with when the
initial connection was made.
.ie n .IP """domain()""" 4
.el .IP "\f(CWdomain()\fR" 4
.IX Item "domain()"
Returns the domain that the remote \s-1SMTP\s0 server identified itself as during
connection.
.ie n .IP """hello($domain)""" 4
.el .IP "\f(CWhello($domain)\fR" 4
.IX Item "hello($domain)"
Tell the remote server the mail domain which you are in using the \s-1EHLO\s0
command (or \s-1HELO\s0 if \s-1EHLO\s0 fails).  Since this method is invoked
automatically when the Net::SMTP object is constructed the user should
normally not have to call it manually.
.ie n .IP """host()""" 4
.el .IP "\f(CWhost()\fR" 4
.IX Item "host()"
Returns the value used by the constructor, and passed to IO::Socket::INET,
to connect to the host.
.ie n .IP """etrn($domain)""" 4
.el .IP "\f(CWetrn($domain)\fR" 4
.IX Item "etrn($domain)"
Request a queue run for the \f(CW$domain\fR given.
.ie n .IP """starttls(%sslargs)""" 4
.el .IP "\f(CWstarttls(%sslargs)\fR" 4
.IX Item "starttls(%sslargs)"
Upgrade existing plain connection to \s-1SSL.\s0
You can use \s-1SSL\s0 arguments as documented in IO::Socket::SSL, but it will
usually use the right arguments already.
.ie n .IP """auth($username, $password)""" 4
.el .IP "\f(CWauth($username, $password)\fR" 4
.IX Item "auth($username, $password)"
.PD 0
.ie n .IP """auth($sasl)""" 4
.el .IP "\f(CWauth($sasl)\fR" 4
.IX Item "auth($sasl)"
.PD
Attempt \s-1SASL\s0 authentication. Requires Authen::SASL module. The first form
constructs a new Authen::SASL object using the given username and password;
the second form uses the given Authen::SASL object.
.ie n .IP """mail($address[, %options])""" 4
.el .IP "\f(CWmail($address[, %options])\fR" 4
.IX Item "mail($address[, %options])"
.PD 0
.ie n .IP """send($address)""" 4
.el .IP "\f(CWsend($address)\fR" 4
.IX Item "send($address)"
.ie n .IP """send_or_mail($address)""" 4
.el .IP "\f(CWsend_or_mail($address)\fR" 4
.IX Item "send_or_mail($address)"
.ie n .IP """send_and_mail($address)""" 4
.el .IP "\f(CWsend_and_mail($address)\fR" 4
.IX Item "send_and_mail($address)"
.PD
Send the appropriate command to the server \s-1MAIL, SEND, SOML\s0 or \s-1SAML.\s0 \f(CW$address\fR
is the address of the sender. This initiates the sending of a message. The
method \f(CW\*(C`recipient\*(C'\fR should be called for each address that the message is to
be sent to.
.Sp
The \f(CW\*(C`mail\*(C'\fR method can take some additional \s-1ESMTP\s0 \f(CW%options\fR which is passed
in hash like fashion, using key and value pairs.  Possible options are:
.Sp
.Vb 8
\& Size        => <bytes>
\& Return      => "FULL" | "HDRS"
\& Bits        => "7" | "8" | "binary"
\& Transaction => <ADDRESS>
\& Envelope    => <ENVID>     # xtext\-encodes its argument
\& ENVID       => <ENVID>     # similar to Envelope, but expects argument encoded
\& XVERP       => 1
\& AUTH        => <submitter> # encoded address according to RFC 2554
.Ve
.Sp
The \f(CW\*(C`Return\*(C'\fR and \f(CW\*(C`Envelope\*(C'\fR parameters are used for \s-1DSN\s0 (Delivery
Status Notification).
.Sp
The submitter address in \f(CW\*(C`AUTH\*(C'\fR option is expected to be in a format as
required by \s-1RFC 2554,\s0 in an RFC2821\-quoted form and xtext-encoded, or <> .
.ie n .IP """reset()""" 4
.el .IP "\f(CWreset()\fR" 4
.IX Item "reset()"
Reset the status of the server. This may be called after a message has been 
initiated, but before any data has been sent, to cancel the sending of the
message.
.ie n .IP """recipient($address[, $address[, ...]][, %options])""" 4
.el .IP "\f(CWrecipient($address[, $address[, ...]][, %options])\fR" 4
.IX Item "recipient($address[, $address[, ...]][, %options])"
Notify the server that the current message should be sent to all of the
addresses given. Each address is sent as a separate command to the server.
Should the sending of any address result in a failure then the process is
aborted and a \fIfalse\fR value is returned. It is up to the user to call
\&\f(CW\*(C`reset\*(C'\fR if they so desire.
.Sp
The \f(CW\*(C`recipient\*(C'\fR method can also pass additional case-sensitive \f(CW%options\fR as an
anonymous hash using key and value pairs.  Possible options are:
.Sp
.Vb 3
\&  Notify  => [\*(AqNEVER\*(Aq] or [\*(AqSUCCESS\*(Aq,\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq]  (see below)
\&  ORcpt   => <ORCPT>
\&  SkipBad => 1        (to ignore bad addresses)
.Ve
.Sp
If \f(CW\*(C`SkipBad\*(C'\fR is true the \f(CW\*(C`recipient\*(C'\fR will not return an error when a bad
address is encountered and it will return an array of addresses that did
succeed.
.Sp
.Vb 5
\&  $smtp\->recipient($recipient1,$recipient2);  # Good
\&  $smtp\->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
\&  $smtp\->recipient($recipient1,$recipient2, { Notify => [\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq], SkipBad => 1 });  # Good
\&  @goodrecips=$smtp\->recipient(@recipients, { Notify => [\*(AqFAILURE\*(Aq], SkipBad => 1 });  # Good
\&  $smtp\->recipient("$recipient,$recipient2"); # BAD
.Ve
.Sp
Notify is used to request Delivery Status Notifications (DSNs), but your
\&\s-1SMTP/ESMTP\s0 service may not respect this request depending upon its version and
your site's \s-1SMTP\s0 configuration.
.Sp
Leaving out the Notify option usually defaults an \s-1SMTP\s0 service to its default
behavior equivalent to ['\s-1FAILURE\s0'] notifications only, but again this may be
dependent upon your site's \s-1SMTP\s0 configuration.
.Sp
The \s-1NEVER\s0 keyword must appear by itself if used within the Notify option and \*(L"requests
that a \s-1DSN\s0 not be returned to the sender under any conditions.\*(R"
.Sp
.Vb 1
\&  {Notify => [\*(AqNEVER\*(Aq]}
\&
\&  $smtp\->recipient(@recipients, { Notify => [\*(AqNEVER\*(Aq], SkipBad => 1 });  # Good
.Ve
.Sp
You may use any combination of these three values '\s-1SUCCESS\s0','\s-1FAILURE\s0','\s-1DELAY\s0' in
the anonymous array reference as defined by \s-1RFC3461\s0 (see
<https://www.ietf.org/rfc/rfc3461.txt> for more information.  Note: quotations
in this topic from same.).
.Sp
A Notify parameter of '\s-1SUCCESS\s0' or '\s-1FAILURE\s0' \*(L"requests that a \s-1DSN\s0 be issued on
successful delivery or delivery failure, respectively.\*(R"
.Sp
A Notify parameter of '\s-1DELAY\s0' \*(L"indicates the sender's willingness to receive
delayed DSNs.  Delayed DSNs may be issued if delivery of a message has been
delayed for an unusual amount of time (as determined by the Message Transfer
Agent (\s-1MTA\s0) at which the message is delayed), but the final delivery status
(whether successful or failure) cannot be determined.  The absence of the \s-1DELAY\s0
keyword in a \s-1NOTIFY\s0 parameter requests that a \*(R"delayed\*(L" \s-1DSN NOT\s0 be issued under
any conditions.\*(R"
.Sp
.Vb 1
\&  {Notify => [\*(AqSUCCESS\*(Aq,\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq]}
\&
\&  $smtp\->recipient(@recipients, { Notify => [\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq], SkipBad => 1 });  # Good
.Ve
.Sp
ORcpt is also part of the \s-1SMTP DSN\s0 extension according to \s-1RFC3461.\s0
It is used to pass along the original recipient that the mail was first
sent to.  The machine that generates a \s-1DSN\s0 will use this address to inform
the sender, because he can't know if recipients get rewritten by mail servers.
It is expected to be in a format as required by \s-1RFC3461,\s0 xtext-encoded.
.ie n .IP """to($address[, $address[, ...]])""" 4
.el .IP "\f(CWto($address[, $address[, ...]])\fR" 4
.IX Item "to($address[, $address[, ...]])"
.PD 0
.ie n .IP """cc($address[, $address[, ...]])""" 4
.el .IP "\f(CWcc($address[, $address[, ...]])\fR" 4
.IX Item "cc($address[, $address[, ...]])"
.ie n .IP """bcc($address[, $address[, ...]])""" 4
.el .IP "\f(CWbcc($address[, $address[, ...]])\fR" 4
.IX Item "bcc($address[, $address[, ...]])"
.PD
Synonyms for \f(CW\*(C`recipient\*(C'\fR.
.ie n .IP """data([$data])""" 4
.el .IP "\f(CWdata([$data])\fR" 4
.IX Item "data([$data])"
Initiate the sending of the data from the current message.
.Sp
\&\f(CW$data\fR may be a reference to a list or a list and must be encoded by the
caller to octets of whatever encoding is required, e.g. by using the Encode
module's \f(CW\*(C`encode()\*(C'\fR function.
.Sp
If specified the contents of \f(CW$data\fR and a termination string \f(CW".\er\en"\fR is
sent to the server. The result will be true if the data was accepted.
.Sp
If \f(CW$data\fR is not specified then the result will indicate that the server
wishes the data to be sent. The data must then be sent using the \f(CW\*(C`datasend\*(C'\fR
and \f(CW\*(C`dataend\*(C'\fR methods described in Net::Cmd.
.ie n .IP """bdat($data)""" 4
.el .IP "\f(CWbdat($data)\fR" 4
.IX Item "bdat($data)"
.PD 0
.ie n .IP """bdatlast($data)""" 4
.el .IP "\f(CWbdatlast($data)\fR" 4
.IX Item "bdatlast($data)"
.PD
Use the alternate \f(CW$data\fR command \*(L"\s-1BDAT\*(R"\s0 of the data chunking service extension
defined in \s-1RFC1830\s0 for efficiently sending large \s-1MIME\s0 messages.
.ie n .IP """expand($address)""" 4
.el .IP "\f(CWexpand($address)\fR" 4
.IX Item "expand($address)"
Request the server to expand the given address Returns an array
which contains the text read from the server.
.ie n .IP """verify($address)""" 4
.el .IP "\f(CWverify($address)\fR" 4
.IX Item "verify($address)"
Verify that \f(CW$address\fR is a legitimate mailing address.
.Sp
Most sites usually disable this feature in their \s-1SMTP\s0 service configuration.
Use \*(L"Debug => 1\*(R" option under \fBnew()\fR to see if disabled.
.ie n .IP """help([$subject])""" 4
.el .IP "\f(CWhelp([$subject])\fR" 4
.IX Item "help([$subject])"
Request help text from the server. Returns the text or undef upon failure
.ie n .IP """quit()""" 4
.el .IP "\f(CWquit()\fR" 4
.IX Item "quit()"
Send the \s-1QUIT\s0 command to the remote \s-1SMTP\s0 server and close the socket connection.
.ie n .IP """can_inet6()""" 4
.el .IP "\f(CWcan_inet6()\fR" 4
.IX Item "can_inet6()"
Returns whether we can use IPv6.
.ie n .IP """can_ssl()""" 4
.el .IP "\f(CWcan_ssl()\fR" 4
.IX Item "can_ssl()"
Returns whether we can use \s-1SSL.\s0
.SS "Addresses"
.IX Subsection "Addresses"
Net::SMTP attempts to \s-1DWIM\s0 with addresses that are passed. For
example an application might extract The From: line from an email
and pass that to \fBmail()\fR. While this may work, it is not recommended.
The application should really use a module like Mail::Address
to extract the mail address and pass that.
.PP
If \f(CW\*(C`ExactAddresses\*(C'\fR is passed to the constructor, then addresses
should be a valid rfc2821\-quoted address, although Net::SMTP will
accept the address surrounded by angle brackets.
.PP
.Vb 3
\& funny user@domain      WRONG
\& "funny user"@domain    RIGHT, recommended
\& <"funny user"@domain>  OK
.Ve
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This example prints the mail domain name of the \s-1SMTP\s0 server known as mailhost:
.PP
.Vb 1
\&    #!/usr/local/bin/perl \-w
\&
\&    use Net::SMTP;
\&
\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
\&    print $smtp\->domain,"\en";
\&    $smtp\->quit;
.Ve
.PP
This example sends a small message to the postmaster at the \s-1SMTP\s0 server
known as mailhost:
.PP
.Vb 1
\&    #!/usr/local/bin/perl \-w
\&
\&    use Net::SMTP;
\&
\&    my $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
\&
\&    $smtp\->mail($ENV{USER});
\&    if ($smtp\->to(\*(Aqpostmaster\*(Aq)) {
\&     $smtp\->data();
\&     $smtp\->datasend("To: postmaster\en");
\&     $smtp\->datasend("\en");
\&     $smtp\->datasend("A simple test message\en");
\&     $smtp\->dataend();
\&    } else {
\&     print "Error: ", $smtp\->message();
\&    }
\&
\&    $smtp\->quit;
.Ve
.SH "EXPORTS"
.IX Header "EXPORTS"
\&\fINone\fR.
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::Cmd,
IO::Socket::SSL.
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.
.PP
Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining
libnet as of version 1.22_02.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1995\-2004 Graham Barr.  All rights reserved.
.PP
Copyright (C) 2013\-2016, 2020 Steve Hay.  All rights reserved.
.SH "LICENCE"
.IX Header "LICENCE"
This module is free software; you can redistribute it and/or modify it under the
same terms as Perl itself, i.e. under the terms of either the \s-1GNU\s0 General Public
License or the Artistic License, as specified in the \fI\s-1LICENCE\s0\fR file.
.SH "VERSION"
.IX Header "VERSION"
Version 3.13
.SH "DATE"
.IX Header "DATE"
23 Dec 2020
.SH "HISTORY"
.IX Header "HISTORY"
See the \fIChanges\fR file.
