forked from extern/egroupware
118 lines
4.6 KiB
Plaintext
118 lines
4.6 KiB
Plaintext
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.
|