1Net::SMTP(3pm)         Perl Programmers Reference Guide         Net::SMTP(3pm)
2
3
4

NAME

6       Net::SMTP - Simple Mail Transfer Protocol Client
7

SYNOPSIS

9           use Net::SMTP;
10
11           # Constructors
12           $smtp = Net::SMTP->new('mailhost');
13           $smtp = Net::SMTP->new('mailhost', Timeout => 60);
14

DESCRIPTION

16       This module implements a client interface to the SMTP and ESMTP
17       protocol, enabling a perl5 application to talk to SMTP servers. This
18       documentation assumes that you are familiar with the concepts of the
19       SMTP protocol described in RFC821.
20
21       A new Net::SMTP object must be created with the new method. Once this
22       has been done, all SMTP commands are accessed through this object.
23
24       The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.
25

EXAMPLES

27       This example prints the mail domain name of the SMTP server known as
28       mailhost:
29
30           #!/usr/local/bin/perl -w
31
32           use Net::SMTP;
33
34           $smtp = Net::SMTP->new('mailhost');
35           print $smtp->domain,"\n";
36           $smtp->quit;
37
38       This example sends a small message to the postmaster at the SMTP server
39       known as mailhost:
40
41           #!/usr/local/bin/perl -w
42
43           use Net::SMTP;
44
45           $smtp = Net::SMTP->new('mailhost');
46
47           $smtp->mail($ENV{USER});
48           $smtp->to('postmaster');
49
50           $smtp->data();
51           $smtp->datasend("To: postmaster\n");
52           $smtp->datasend("\n");
53           $smtp->datasend("A simple test message\n");
54           $smtp->dataend();
55
56           $smtp->quit;
57

CONSTRUCTOR

59       new ( [ HOST ] [, OPTIONS ] )
60           This is the constructor for a new Net::SMTP object. "HOST" is the
61           name of the remote host to which an SMTP connection is required.
62
63           "HOST" is optional. If "HOST" is not given then it may instead be
64           passed as the "Host" option described below. If neither is given
65           then the "SMTP_Hosts" specified in "Net::Config" will be used.
66
67           "OPTIONS" are passed in a hash like fashion, using key and value
68           pairs.  Possible options are:
69
70           Hello - SMTP requires that you identify yourself. This option
71           specifies a string to pass as your mail domain. If not given
72           localhost.localdomain will be used.
73
74           Host - SMTP host to connect to. It may be a single scalar, as
75           defined for the "PeerAddr" option in IO::Socket::INET, or a
76           reference to an array with hosts to try in turn. The "host" method
77           will return the value which was used to connect to the host.
78
79           LocalAddr and LocalPort - These parameters are passed directly to
80           IO::Socket to allow binding the socket to a local port.
81
82           Timeout - Maximum time, in seconds, to wait for a response from the
83           SMTP server (default: 120)
84
85           ExactAddresses - If true the all ADDRESS arguments must be as
86           defined by "addr-spec" in RFC2822. If not given, or false, then
87           Net::SMTP will attempt to extract the address from the value
88           passed.
89
90           Debug - Enable debugging information
91
92           Example:
93
94               $smtp = Net::SMTP->new('mailhost',
95                                      Hello => 'my.mail.domain',
96                                      Timeout => 30,
97                                      Debug   => 1,
98                                     );
99
100               # the same
101               $smtp = Net::SMTP->new(
102                                      Host => 'mailhost',
103                                      Hello => 'my.mail.domain',
104                                      Timeout => 30,
105                                      Debug   => 1,
106                                     );
107
108               # Connect to the default server from Net::config
109               $smtp = Net::SMTP->new(
110                                      Hello => 'my.mail.domain',
111                                      Timeout => 30,
112                                     );
113

METHODS

115       Unless otherwise stated all methods return either a true or false
116       value, with true meaning that the operation was a success. When a
117       method states that it returns a value, failure will be returned as
118       undef or an empty list.
119
120       banner ()
121           Returns the banner message which the server replied with when the
122           initial connection was made.
123
124       domain ()
125           Returns the domain that the remote SMTP server identified itself as
126           during connection.
127
128       hello ( DOMAIN )
129           Tell the remote server the mail domain which you are in using the
130           EHLO command (or HELO if EHLO fails).  Since this method is invoked
131           automatically when the Net::SMTP object is constructed the user
132           should normally not have to call it manually.
133
134       host ()
135           Returns the value used by the constructor, and passed to
136           IO::Socket::INET, to connect to the host.
137
138       etrn ( DOMAIN )
139           Request a queue run for the DOMAIN given.
140
141       auth ( USERNAME, PASSWORD )
142           Attempt SASL authentication.
143
144       mail ( ADDRESS [, OPTIONS] )
145       send ( ADDRESS )
146       send_or_mail ( ADDRESS )
147       send_and_mail ( ADDRESS )
148           Send the appropriate command to the server MAIL, SEND, SOML or
149           SAML. "ADDRESS" is the address of the sender. This initiates the
150           sending of a message. The method "recipient" should be called for
151           each address that the message is to be sent to.
152
153           The "mail" method can some additional ESMTP OPTIONS which is passed
154           in hash like fashion, using key and value pairs.  Possible options
155           are:
156
157            Size        => <bytes>
158            Return      => "FULL" | "HDRS"
159            Bits        => "7" | "8" | "binary"
160            Transaction => <ADDRESS>
161            Envelope    => <ENVID>     # xtext-encodes its argument
162            ENVID       => <ENVID>     # similar to Envelope, but expects argument encoded
163            XVERP       => 1
164            AUTH        => <submitter> # encoded address according to RFC 2554
165
166           The "Return" and "Envelope" parameters are used for DSN (Delivery
167           Status Notification).
168
169           The submitter address in "AUTH" option is expected to be in a
170           format as required by RFC 2554, in an RFC2821-quoted form and
171           xtext-encoded, or <> .
172
173       reset ()
174           Reset the status of the server. This may be called after a message
175           has been initiated, but before any data has been sent, to cancel
176           the sending of the message.
177
178       recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] )
179           Notify the server that the current message should be sent to all of
180           the addresses given. Each address is sent as a separate command to
181           the server.  Should the sending of any address result in a failure
182           then the process is aborted and a false value is returned. It is up
183           to the user to call "reset" if they so desire.
184
185           The "recipient" method can also pass additional case-sensitive
186           OPTIONS as an anonymous hash using key and value pairs.  Possible
187           options are:
188
189             Notify  => ['NEVER'] or ['SUCCESS','FAILURE','DELAY']  (see below)
190             ORcpt   => <ORCPT>
191             SkipBad => 1        (to ignore bad addresses)
192
193           If "SkipBad" is true the "recipient" will not return an error when
194           a bad address is encountered and it will return an array of
195           addresses that did succeed.
196
197             $smtp->recipient($recipient1,$recipient2);  # Good
198             $smtp->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
199             $smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
200             @goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 });  # Good
201             $smtp->recipient("$recipient,$recipient2"); # BAD
202
203           Notify is used to request Delivery Status Notifications (DSNs), but
204           your SMTP/ESMTP service may not respect this request depending upon
205           its version and your site's SMTP configuration.
206
207           Leaving out the Notify option usually defaults an SMTP service to
208           its default behavior equivalent to ['FAILURE'] notifications only,
209           but again this may be dependent upon your site's SMTP
210           configuration.
211
212           The NEVER keyword must appear by itself if used within the Notify
213           option and "requests that a DSN not be returned to the sender under
214           any conditions."
215
216             {Notify => ['NEVER']}
217
218             $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 });  # Good
219
220           You may use any combination of these three values
221           'SUCCESS','FAILURE','DELAY' in the anonymous array reference as
222           defined by RFC3461 (see http://rfc.net/rfc3461.html for more
223           information.  Note: quotations in this topic from same.).
224
225           A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN
226           be issued on successful delivery or delivery failure,
227           respectively."
228
229           A Notify parameter of 'DELAY' "indicates the sender's willingness
230           to receive delayed DSNs.  Delayed DSNs may be issued if delivery of
231           a message has been delayed for an unusual amount of time (as
232           determined by the Message Transfer Agent (MTA) at which the message
233           is delayed), but the final delivery status (whether successful or
234           failure) cannot be determined.  The absence of the DELAY keyword in
235           a NOTIFY parameter requests that a "delayed" DSN NOT be issued
236           under any conditions."
237
238             {Notify => ['SUCCESS','FAILURE','DELAY']}
239
240             $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
241
242           ORcpt is also part of the SMTP DSN extension according to RFC3461.
243           It is used to pass along the original recipient that the mail was
244           first sent to.  The machine that generates a DSN will use this
245           address to inform the sender, because he can't know if recipients
246           get rewritten by mail servers.  It is expected to be in a format as
247           required by RFC3461, xtext-encoded.
248
249       to ( ADDRESS [, ADDRESS [...]] )
250       cc ( ADDRESS [, ADDRESS [...]] )
251       bcc ( ADDRESS [, ADDRESS [...]] )
252           Synonyms for "recipient".
253
254       data ( [ DATA ] )
255           Initiate the sending of the data from the current message.
256
257           "DATA" may be a reference to a list or a list. If specified the
258           contents of "DATA" and a termination string ".\r\n" is sent to the
259           server. And the result will be true if the data was accepted.
260
261           If "DATA" is not specified then the result will indicate that the
262           server wishes the data to be sent. The data must then be sent using
263           the "datasend" and "dataend" methods described in Net::Cmd.
264
265       expand ( ADDRESS )
266           Request the server to expand the given address Returns an array
267           which contains the text read from the server.
268
269       verify ( ADDRESS )
270           Verify that "ADDRESS" is a legitimate mailing address.
271
272           Most sites usually disable this feature in their SMTP service
273           configuration.  Use "Debug => 1" option under new() to see if
274           disabled.
275
276       help ( [ $subject ] )
277           Request help text from the server. Returns the text or undef upon
278           failure
279
280       quit ()
281           Send the QUIT command to the remote SMTP server and close the
282           socket connection.
283

ADDRESSES

285       Net::SMTP attempts to DWIM with addresses that are passed. For example
286       an application might extract The From: line from an email and pass that
287       to mail(). While this may work, it is not recommended.  The application
288       should really use a module like Mail::Address to extract the mail
289       address and pass that.
290
291       If "ExactAddresses" is passed to the constructor, then addresses should
292       be a valid rfc2821-quoted address, although Net::SMTP will accept
293       accept the address surrounded by angle brackets.
294
295        funny user@domain      WRONG
296        "funny user"@domain    RIGHT, recommended
297        <"funny user"@domain>  OK
298

SEE ALSO

300       Net::Cmd
301

AUTHOR

303       Graham Barr <gbarr@pobox.com>
304
306       Copyright (c) 1995-2004 Graham Barr. All rights reserved.  This program
307       is free software; you can redistribute it and/or modify it under the
308       same terms as Perl itself.
309
310
311
312perl v5.12.4                      2011-06-01                    Net::SMTP(3pm)
Impressum