Index for Section 3

Alphabetical listing for N

Bottom of page

Net::SMTP(3)
NAME
  Net::SMTP - Simple Mail Transfer Protocol Client

SYNOPSIS
      use Net::SMTP;

      # Constructors
      $smtp = Net::SMTP->new('mailhost');
      $smtp = Net::SMTP->new('mailhost', Timeout => 60);

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 RFC821.

  A new Net::SMTP object must be created with the new method. Once this has
  been done, all SMTP commands are accessed through this object.

  The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.

EXAMPLES
  This example prints the mail domain name of the SMTP server known as
  mailhost:

      #!/usr/local/bin/perl -w

      use Net::SMTP;

      $smtp = Net::SMTP->new('mailhost');
      print $smtp->domain,"\n";
      $smtp->quit;

  This example sends a small message to the postmaster at the SMTP server
  known as mailhost:

      #!/usr/local/bin/perl -w

      use Net::SMTP;

      $smtp = Net::SMTP->new('mailhost');

      $smtp->mail($ENV{USER});
      $smtp->to('postmaster');

      $smtp->data();
      $smtp->datasend("To: postmaster\n");
      $smtp->datasend("\n");
      $smtp->datasend("A simple test message\n");
      $smtp->dataend();

      $smtp->quit;

CONSTRUCTOR
  new Net::SMTP [ HOST, ] [ OPTIONS ]
      This is the constructor for a new Net::SMTP object. "HOST" is the name
      of the remote host to which an SMTP connection is required.

      If "HOST" is an array reference then each value will be attempted in
      turn until a connection is made.

      If "HOST" is not given, then the "SMTP_Host" specified in "Net::Config"
      will be used.

      "OPTIONS" are passed in a hash like fashion, using key and value pairs.
      Possible options are:

      Hello - SMTP requires that you identify yourself. This option specifies
      a string to pass as your mail domain. If not given a guess will be
      taken.

      LocalAddr and LocalPort - These parameters are passed directly to
      IO::Socket to allow binding the socket to a local port.

      Timeout - Maximum time, in seconds, to wait for a response from the
      SMTP server (default: 120)

      ExactAddresses - If true the all ADDRESS arguments must be as defined
      by "addr-spec" in RFC2822. If not given, or false, then Net::SMTP will
      attempt to extract the address from the value passed.

      Debug - Enable debugging information

      Example:

	  $smtp = Net::SMTP->new('mailhost',
				 Hello => 'my.mail.domain'
				 Timeout => 30,
				 Debug	 => 1,
				);

METHODS
  Unless otherwise stated all methods return either a true or false value,
  with true meaning that the operation was a success. When a method states
  that it returns a value, failure will be returned as undef or an empty
  list.

  banner ()
      Returns the banner message which the server replied with when the
      initial connection was made.

  domain ()
      Returns the domain that the remote SMTP server identified itself as
      during connection.

  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.

  etrn ( DOMAIN )
      Request a queue run for the DOMAIN given.

  auth ( USERNAME, PASSWORD )
      Attempt SASL authentication.

  mail ( ADDRESS [, OPTIONS] )
  send ( ADDRESS )
  send_or_mail ( ADDRESS )
  send_and_mail ( ADDRESS )
      Send the appropriate command to the server MAIL, SEND, SOML or SAML.
      "ADDRESS" is the address of the sender. This initiates the sending of a
      message. The method "recipient" should be called for each address that
      the message is to be sent to.

      The "mail" method can some additional ESMTP OPTIONS which is passed in
      hash like fashion, using key and value pairs.  Possible options are:

       Size	   => <bytes>
       Return	   => "FULL" | "HDRS"
       Bits	   => "7" | "8" | "binary"
       Transaction => <ADDRESS>
       Envelope	   => <ENVID>

      The "Return" and "Envelope" parameters are used for DSN (Delivery
      Status Notification).

  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.

  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 false value is returned. It is up to the user
      to call "reset" if they so desire.

      The "recipient" method can some additional OPTIONS which is passed in
      hash like fashion, using key and value pairs.  Possible options are:

       Notify	 =>
       SkipBad	 => ignore bad addresses

      If "SkipBad" is true the "recipient" will not return an error when a
      bad address is encountered and it will return an array of addresses
      that did succeed.

	$smtp->recipient($recipient1,$recipient2);  # Good
	$smtp->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
	$smtp->recipient("$recipient,$recipient2"); # BAD

  to ( ADDRESS [, ADDRESS [...]] )
  cc ( ADDRESS [, ADDRESS [...]] )
  bcc ( ADDRESS [, ADDRESS [...]] )
      Synonyms for "recipient".

  data ( [ DATA ] )
      Initiate the sending of the data from the current message.

      "DATA" may be a reference to a list or a list. If specified the
      contents of "DATA" and a termination string ".\r\n" is sent to the
      server. And the result will be true if the data was accepted.

      If "DATA" 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
      "datasend" and "dataend" methods described in Net::Cmd.

  expand ( ADDRESS )
      Request the server to expand the given address Returns an array which
      contains the text read from the server.

  verify ( ADDRESS )
      Verify that "ADDRESS" is a legitimate mailing address.

  help ( [ $subject ] )
      Request help text from the server. Returns the text or undef upon
      failure

  quit ()
      Send the QUIT command to the remote SMTP server and close the socket
      connection.

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
  mail(). While this may work, it is not reccomended.  The application should
  really use a module like Mail::Address to extract the mail address and pass
  that.

  If "ExactAddresses" is passed to the contructor, then addresses should be a
  valid rfc2821-quoted address, although Net::SMTP will accept accept the
  address surrounded by angle brackets.

   funny user@domain	  WRONG
   "funny user"@domain	  RIGHT, recommended
   <"funny user"@domain>  OK

SEE ALSO
  Net::Cmd

AUTHOR
  Graham Barr <gbarr@pobox.com>

COPYRIGHT
  Copyright (c) 1995-1997 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.

  $Id: //depot/libnet/Net/SMTP.pm#31 $

Index for Section 3

Alphabetical listing for N

Top of page