Current Path :
/
usr
/
local
/
ssl
/
share
/
man
/
man3
/
Or
Select Your Path :
Upload File :
New :
File
Dir
//usr/local/ssl/share/man/man3/Net::SMTP.3pm
.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" 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" '' '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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" ======================================================================== .\" .IX Title "Net::SMTP 3" .TH Net::SMTP 3 "2017-11-14" "perl v5.10.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. .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\s0, \s-1PASSWORD\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\s0, \s-1SEND\s0, \s-1SOML\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\s0 \s-1OPTIONS\s0 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\s0 2554, 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 => <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\s0 \s-1NOT\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\s0 \s-1DSN\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\s0\*(R" 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" Copyright (C) 1995\-2004 Graham Barr. All rights reserved. .PP Copyright (C) 2013\-2016 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.
