.\" Automatically generated by Pod::Man 2.28 (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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::SMTP 3perl" .TH Net::SMTP 3perl "2018-06-10" "perl v5.20.2" "Perl Programmers Reference Guide" .\" 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-1RFC821.\s0 .PP A new Net::SMTP object must be created with the \fInew\fR method. Once this has been done, all \s-1SMTP\s0 commands are accessed through this object. .PP The Net::SMTP class is a subclass of Net::Cmd and 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 \&\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. .Sp \&\fBPort\fR \- port to connect to. Format \- \f(CW\*(C`PeerHost\*(C'\fR from IO::Socket::INET new method. Default \- 25. .Sp \&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly to IO::Socket to allow binding the socket to a local port. .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 \&\fBPort\fR \- Select a port on the remote host to connect to (default is 25) .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, \& ); \& \& # 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 "auth ( \s-1USERNAME, PASSWORD \s0)" 4 .IX Item "auth ( USERNAME, PASSWORD )" Attempt \s-1SASL\s0 authentication. Requires Authen::SASL module. .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. 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. And 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 "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. .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 .SH "AUTHOR" .IX Header "AUTHOR" Graham Barr .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1995\-2004 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.