phpgw_send.inc.php
  Itzchak Rehberg <izzy@qumran.org>
  v1.0, 07 August 2000

  documentation of the smtp "send" class
  ______________________________________________________________________

  Table of Contents


  1. Why another mail() function?
  2. Function reference
  3. Additional functionality
     3.1. The smail->err Array
     3.2. The smail->to_res Array
     3.3. The function msg()
  4. Comments
     4.1. reply codes according to RFC821 - short explanation


  ______________________________________________________________________


  1. Why another mail() function?

  Who ever has used php's owm (built-in) mail() function will certainly
  agree to its limitations.  And if I say "limitations", this is a very
  neat way  to describe  what  we  really  think  of it  -  it's almost
  unreliable at all. Imagine sending a mail to multiple recipients: how
  will you know  if a copy was sent  to all of them,  and not  just one
  address failed?  Or  even only one address  did *not*  fail?  There's
  almost no possibility for detailed error checking (if there's limited
  possibility for it,  I didn't see it).  That  was the point  when  we
  decided on writing an own mail() function to use with phpGroupWare.

  We call the class "send" instead of "smtp" since we plan to have nntp
  sending, too, with the same structure and function naming.

  ______________________________________________________________________


  2. Function reference
  
  Syntax is almost the same as for the mail() function, so please refer
  to php's docu on this.  The difference, of course,  is that smtp is a
  class,  so you first have to create an instance of it  before you can
  actually use it, e.g.:
  
  $mymailer = new send;
  $mymailer->smail($to,$subject,$message,$header);

  ______________________________________________________________________


  3. Additional functionality

  As mentioned above, the smtp class provides additional error checking
  facilities. These are realized by two arrays used inside the class:

  3.1. The smail->err Array
  
  This array  holds the latest information  returned by the remote smtp
  server. It consists of 3 parts:
  smail->err["code"] is a 3 digit code according to RFC821
  smail->err["msg"]  is the additional message returned by the server
  smail->err["desc"] may  hold  some  more  detailed  information,   if
                     available

  3.2. The smail->to_res Array
  
  This is actually an array of arrays holding information equivalent to
  the smail->err array, but for each single recipient.  So here you can
  check for each recipient, if the server accepted him/her.  There's an
  additional field smail->to_res["addr"] to identify the recipient:
  smail->to_res["addr"] is the concerned recipient's address
  smail->to_res["code"] is a 3 digit code according to RFC821
  smail->to_res["msg"]  is the additional message returned by the server
  smail->to_res["desc"] may  hold  some  more detailed  information,  if
                        available

  3.3. The function msg($service, $to, $subject, $body)

  We use this additional function to build the message header and call
  the "smail()" function right from within this. So you may want to
  adapt the header information, if you want to use the class outside
  the phpGroupWare environment.

  ______________________________________________________________________


  4. Comments

  the server to use is hardcoded  into the smtp->smail() func  using the
  variable $phpgw_info  -  so if you want to use the function outside of
  phpGroupWare, you may want to change this.

  4.1. reply codes according to RFC821 - short explanation
  
  The reply code according to RFC821 consists of 3 digits, I'll refer to
  those here as xyz. X holds some general information - and by x only
  one already can decide wether the code tells something good or bad. Y
  tells the service affected, and z may give some non specified detail.
  
  value | x                                    | y
  ------+--------------------------------------+------------------------
    0   | -                                    | syntax
    1   | accepted, confirmation required      | information only
    2   | action completed successfully        | connection related
    3   | accepted, send more (detailed) data  | -
    4   | not accepted, try again later        | -
    5   | refused, don't retry                 | mail system
  
  so x=4 notifies of some temporary, x=5 of some permanent problem.
  
  If the 3-digit-code is followed by a "-", it's a multi-line response
  (last line of this response will have a blank following the 3-digit
  code). Otherwise the 3-digit-code is just followed by a blank.