Edit File: Net::SMTP.3pm
.\" 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 "2020-12-23" "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. .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 \fInew()\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 \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 "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.