PHP and PEAR::Mail - Setup Guide

Important Points

  • PEAR is a PHP framework from The PHP Group that provides reusable PHP components or classes. PEAR::Mail is one of these classes and it provides advanced interfaces to PHP applications and programs for sending emails. The SMTP interface allows a PHP application to access an external SMTP server with control over various options such SMTP ports and authentication.
  • These instructions are a basic guide demonstrating the minimum code required to send a message using PEAR::Mail through AuthSMTP. They are not a guide to a complete or secure setup of an email application, for further instructions on using and securing PHP and PEAR::Mail please see their websites: PEAR::Mail - PHP.net
  • You should ensure that your code is able to gracefully handle errors in not being able to transmit messages to our network. While we endeavour to provide maximum availability for our service there is always the possibility of connectivity or other technical issues beyond our (or your) control. Ideally error handling, logging, message queueing (with retry) and monitoring should all be considered.

Requirements

  • PEAR::Mail is not part of the base PHP installation, it is an advanced framework that needs to be installed separately on the web server that is running your website, if you are unsure if you have access to it you will need to contact your web hosting company or network administrator.

Step 1

  • First you need to make sure the email address(es) you will be sending from have been authorised for your account in our Control Panel.
  • Create a file called authsmtp-test.php on your web server containing the only the following code:

Step 2

  • Change the following lines:
    • $recipients to your email address
    • $headers['From'] to your email address
    • $headers['To'] to your email address
    • 'USERNAME' to your AuthSMTP username
    • 'PASSWORD' to your AuthSMTP password
  • Save the file to your web server.
  • Open a web browser and view the uploaded authsmtp-test.php file on the Internet.
  • You should see a list of the parameters you have entered and the SMTP conversation, if it was successful you will see at the end of the conversation a section that reads 'Message accepted for delivery'
  • This means that AuthSMTP can be used from your web server and you can continue to integrate this into your form / application.
  • We recommend that when you do, you store the username and password variable definitions in a separate PHP file outside your public web directory and reference back to it. Storing them in a public PHP file is a potential security risk.

IMPORTANT: Enabling or disabling SSL

  • Currently PEAR::Mail has SSL/TLS enabled for SMTP and it will always try to negotiate a secure connection, there is no configuration parameter to change this setting.
  • By default we do not enable SSL on your account so you have two options:
    • Enable SSL/TLS on your AuthSMTP account via the Control Panel.
    • Disable SSL/TLS in PEAR::MAIL, to do this you will need access to the source files for the framework on your server - see below.

Disable SMTP TLS / SSL in PEAR::MAIL

  • Edit the file - /pear/Net_SMTP/Net/SMTP.php
  • Find the line with the following content (approximately line 590):
  • function auth($uid, $pwd, $method = '', $tls = true, $authz = '')

  • Replace this with:
  • function auth($uid, $pwd, $method = '', $tls = false, $authz = '')

  • So your changing '$tls' from 'true' to 'false'
  • Save the file

Troubleshooting

  • Ensure that you have the latest PEAR::Mail installed on your server and that PHP is enabled, you may need to contact your web hosting company or network administrator.
  • Try one of the alternative ports - 23, 26, 2525.
  • Check the username and password that you have entered are correct.
  • Check with your Network Administrator or Hosting company that external access on one of the ports is possible.
  • Check the permissions on the files you have uploaded.
  • Check that you have validated the 'From Address' with AuthSMTP, you can check or start the validation process by logging into the Control Panel.

Support

  • If you believe there is a problem with your AuthSMTP account please login to the Control Panel and check the following:
    • You are using the correct username and password, it is possible to set separate passwords for logging into the control panel and for sending email.
    • That your account hasn't expired.
    • See if there is any errors being logged against your account such as unauthorised emails addresses etc.
  • For further support please contact either your web hosting company or check the support resources for: