/usr/local/share/man/man3
Edit: /usr/local/share/man/man3/Net::SMTP.3pm (18880B)
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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 "2016-08-01" "perl v5.16.3" "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.
.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 "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( [ \s-1HOST \s0] [, \s-1OPTIONS \s0] )" 4
.IX Item "new ( [ HOST ] [, OPTIONS ] )"
This is the constructor for a new Net::SMTP object. \f(CW\*(C`HOST\*(C'\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\*(C`HOST\*(C'\fR is optional. If \f(CW\*(C`HOST\*(C'\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\*(C`OPTIONS\*(C'\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 the all \s-1ADDRESS\s0 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 "METHODS"
.IX Header "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.
.IP "banner ()" 4
.IX Item "banner ()"
Returns the banner message which the server replied with when the
initial connection was made.
.IP "domain ()" 4
.IX Item "domain ()"
Returns the domain that the remote \s-1SMTP\s0 server identified itself as during
connection.
.IP "hello ( \s-1DOMAIN \s0)" 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.
.IP "host ()" 4
.IX Item "host ()"
Returns the value used by the constructor, and passed to IO::Socket::INET,
to connect to the host.
.IP "etrn ( \s-1DOMAIN \s0)" 4
.IX Item "etrn ( DOMAIN )"
Request a queue run for the \s-1DOMAIN\s0 given.
.IP "starttls ( \s-1SSLARGS \s0)" 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.
.IP "auth ( \s-1USERNAME, PASSWORD \s0)" 4
.IX Item "auth ( USERNAME, PASSWORD )"
.PD 0
.IP "auth ( \s-1SASL \s0)" 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.
.IP "mail ( \s-1ADDRESS\s0 [, \s-1OPTIONS\s0] )" 4
.IX Item "mail ( ADDRESS [, OPTIONS] )"
.PD 0
.IP "send ( \s-1ADDRESS \s0)" 4
.IX Item "send ( ADDRESS )"
.IP "send_or_mail ( \s-1ADDRESS \s0)" 4
.IX Item "send_or_mail ( ADDRESS )"
.IP "send_and_mail ( \s-1ADDRESS \s0)" 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\*(C`ADDRESS\*(C'\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 some additional \s-1ESMTP OPTIONS\s0 which is passed
in hash like fashion, using key and value pairs. Possible options are:
.Sp
.Vb 8
\& Size =>
\& Return => "FULL" | "HDRS"
\& Bits => "7" | "8" | "binary"
\& Transaction =>
\& Envelope => # xtext\-encodes its argument
\& ENVID => # similar to Envelope, but expects argument encoded
\& XVERP => 1
\& AUTH => # 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 <> .
.IP "reset ()" 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.
.IP "recipient ( \s-1ADDRESS\s0 [, \s-1ADDRESS,\s0 [...]] [, \s-1OPTIONS \s0] )" 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 \s-1OPTIONS\s0 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 =>
\& 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 http://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.
.IP "to ( \s-1ADDRESS\s0 [, \s-1ADDRESS\s0 [...]] )" 4
.IX Item "to ( ADDRESS [, ADDRESS [...]] )"
.PD 0
.IP "cc ( \s-1ADDRESS\s0 [, \s-1ADDRESS\s0 [...]] )" 4
.IX Item "cc ( ADDRESS [, ADDRESS [...]] )"
.IP "bcc ( \s-1ADDRESS\s0 [, \s-1ADDRESS\s0 [...]] )" 4
.IX Item "bcc ( ADDRESS [, ADDRESS [...]] )"
.PD
Synonyms for \f(CW\*(C`recipient\*(C'\fR.
.IP "data ( [ \s-1DATA \s0] )" 4
.IX Item "data ( [ DATA ] )"
Initiate the sending of the data from the current message.
.Sp
\&\f(CW\*(C`DATA\*(C'\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\*(C`DATA\*(C'\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\*(C`DATA\*(C'\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.
.IP "bdat ( \s-1DATA \s0)" 4
.IX Item "bdat ( DATA )"
.PD 0
.IP "bdatlast ( \s-1DATA \s0)" 4
.IX Item "bdatlast ( DATA )"
.PD
Use the alternate \s-1DATA\s0 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.
.IP "expand ( \s-1ADDRESS \s0)" 4
.IX Item "expand ( ADDRESS )"
Request the server to expand the given address Returns an array
which contains the text read from the server.
.IP "verify ( \s-1ADDRESS \s0)" 4
.IX Item "verify ( ADDRESS )"
Verify that \f(CW\*(C`ADDRESS\*(C'\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 \fInew()\fR to see if disabled.
.ie n .IP "help ( [ $subject ] )" 4
.el .IP "help ( [ \f(CW$subject\fR ] )" 4
.IX Item "help ( [ $subject ] )"
Request help text from the server. Returns the text or undef upon failure
.IP "quit ()" 4
.IX Item "quit ()"
Send the \s-1QUIT\s0 command to the remote \s-1SMTP\s0 server and close the socket connection.
.IP "can_inet6 ()" 4
.IX Item "can_inet6 ()"
Returns whether we can use IPv6.
.IP "can_ssl ()" 4
.IX Item "can_ssl ()"
Returns whether we can use \s-1SSL.\s0
.SH "ADDRESSES"
.IX Header "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 \fImail()\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 "SEE ALSO"
.IX Header "SEE ALSO"
Net::Cmd,
IO::Socket::SSL
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Barr <\fIgbarr@pobox.com\fR>
.PP
Steve Hay <\fIshay@cpan.org\fR> is now maintaining libnet as of version
1.22_02
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Versions up to 2.31_1 Copyright (c) 1995\-2004 Graham Barr. All rights reserved.
Changes in Version 2.31_2 onwards Copyright (C) 2013\-2015 Steve Hay. All rights
reserved.
.PP
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.