README

PEAR:Mail driver SmtpMX
=======================

Mail_smtpmx is a mail driver for direct delivery. When sending mails it 
acts pretty much like any Mail Transport Agent (MTA). As configured to 
deliver mail, they directly connect to the responsible mail server for 
each recipient and don't use smarthosts to relay mails. Hence it checks 
the MX-records for every recipient and connects to each mail-server 
directly. 

Of course Mail_smtpmx is only able to send mails. This makes it a quite small
class, also because of the useage of Net_SMTP. 

Requirements
============

PEAR:Net_SMTP: to connect, verify and transport mail
PEAR:Mail: of course - this is just a driver for Mail!
Network connection!

Either Linux/Unix which makes getmxrr() work or PEAR:Net_DNS 
to figure out mail exchange hosts. See option "netdns".

How to test it: 
===============
Use the script: mailer.php to test it. It is a PHP-CLI script, just run it 
from shell. The script requires at least on argument: an email address to
send a mail to. You can specify more than one address in RFC822 style. 

Example: 
 ./mailer.php xxxxxxxxxxx@php-tools.net, foo@bar.org

You may want to test it with different addresses - maybe it is a good 
idea to test it on quite busy or slow servers as well. 

Options
=======
Mail_smtpmx allows some options to be set during object initialisation, 
these options must while calling the factory-method of Mail.

The following options may be used:

mailname  The name of the local mail system 
          (a valid hostname which matches the reverse lookup)

port      smtp-port - the default comes from getservicebyname() 
          and should work fine

timeout   The SMTP connection timeout. Defaults to none.

verp      Whether to use VERP or not. Defaults to false.

vrfy      Whether to use the SMTP-verify command (VRFY) or not. 
          Defaults to false.

debug     Activate SMTP debug mode? Defaults to false.

test      Run in dummy mode: do everything but reset SMTP-connection 
          just before sending data (RSET).

netdns    whether to use PEAR:Net_DNS or the PHP build in function 
          getmxrr, default is true. Actually this is only required on
          Windows platforms. Unix/Linux machines can use getmxrr() 
          which does not require any further PEAR package.

Why Mail_smtpmx? 
================

The major benefit is to recieve a proper response a responsible mail server 
(MX). Therefore address verification works and if the MX accepts the mail, 
one can be pretty sure that is will arrive. 

In other words, one can figure out at runtime whether mail delivery succeeded 
or failed. This makes it possible to react on errors instandly. Also "mail 
delivery failure" mails will be avoided. (Of course, it's much easier to react 
on the return value if a function call, than to  parse "failure" emails, 
arriving three days afterwards...)

Why not?
========

Of course, there are disadvantages, as well. Because of mail-abuse (SPAM), 
Mail_smtpmx will only work on internet sites with proper a propper, static
ip address (hopefully).

Also Mail_smtpmx will be slower than using mail() (in combination with a 
smarthost). 

Hence it does direct delivery, it is the perfect tool for SPAM-applications 
:-(

IMPORTANT:
Also it is strongly recommend to send mails asynchron when using Mail_smtpmx!
Use Process controll (fork, kill, ...) in your application to avoid dead-locks.

This is required because of the unpredictable behaviour of network connections, 
mail-servers and so on. Conntact me for further information!


Include Path? 
=============

The example script mangle the php include_path. This is necessary, because 
Mail_smtpmx is not (yet) part of the PEAR package: Mail. Hence it is not installed
in the propper directory. 

regards gERD