diff options
Diffstat (limited to 'upstream/archlinux/man3/Net::SMTP.3perl')
| -rw-r--r-- | upstream/archlinux/man3/Net::SMTP.3perl | 496 |
1 files changed, 496 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/Net::SMTP.3perl b/upstream/archlinux/man3/Net::SMTP.3perl new file mode 100644 index 00000000..3d6312f2 --- /dev/null +++ b/upstream/archlinux/man3/Net::SMTP.3perl @@ -0,0 +1,496 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" 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 +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. 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 3perl" +.TH Net::SMTP 3perl 2024-02-11 "perl v5.38.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 SMTP and ESMTP +protocol, enabling a perl5 application to talk to SMTP servers. This +documentation assumes that you are familiar with the concepts of the +SMTP protocol described in RFC2821. +With IO::Socket::SSL installed it also provides support for implicit and +explicit TLS encryption, i.e. SMTPS or SMTP+STARTTLS. +.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 SMTP 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 \- SMTP 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 EHLO (or HELO) 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(CWhello()\fR instead. +.Sp +\&\fBHost\fR \- SMTP 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 "host" 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 SMTP and 465 for immediate SSL. +.Sp +\&\fBSSL\fR \- If the connection should be done from start with SSL, contrary to later +upgrade with \f(CW\*(C`starttls\*(C'\fR. +You can use SSL 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 +SMTP 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 RFC2822. 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 SMTP 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 SMTP 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 EHLO +command (or HELO if EHLO 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 SSL. +You can use SSL 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 SASL 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 MAIL, SEND, SOML or SAML. \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 ESMTP \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 DSN (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 RFC 2554, 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 +SMTP/ESMTP service may not respect this request depending upon its version and +your site's SMTP configuration. +.Sp +Leaving out the Notify option usually defaults an SMTP service to its default +behavior equivalent to ['FAILURE'] notifications only, but again this may be +dependent upon your site's SMTP configuration. +.Sp +The NEVER keyword must appear by itself if used within the Notify option and "requests +that a DSN not be returned to the sender under any conditions." +.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 'SUCCESS','FAILURE','DELAY' in +the anonymous array reference as defined by RFC3461 (see +<https://www.ietf.org/rfc/rfc3461.txt> for more information. Note: quotations +in this topic from same.). +.Sp +A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN be issued on +successful delivery or delivery failure, respectively." +.Sp +A Notify parameter of 'DELAY' "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 (MTA) at which the message is delayed), but the final delivery status +(whether successful or failure) cannot be determined. The absence of the DELAY +keyword in a NOTIFY parameter requests that a "delayed" DSN NOT be issued under +any conditions." +.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 SMTP DSN extension according to RFC3461. +It is used to pass along the original recipient that the mail was first +sent to. The machine that generates a DSN 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 RFC3461, 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(CWencode()\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 "BDAT" of the data chunking service extension +defined in RFC1830 for efficiently sending large MIME 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 SMTP service configuration. +Use "Debug => 1" 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 QUIT command to the remote SMTP 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 SSL. +.SS Addresses +.IX Subsection "Addresses" +Net::SMTP attempts to DWIM 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 SMTP 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 SMTP 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 GNU General Public +License or the Artistic License, as specified in the \fILICENCE\fR file. +.SH VERSION +.IX Header "VERSION" +Version 3.15 +.SH DATE +.IX Header "DATE" +20 March 2023 +.SH HISTORY +.IX Header "HISTORY" +See the \fIChanges\fR file. |