Contacting a contact list: A tutorial - revisited

The Environment

First of all I'll set up the environment. I've created a folder called 'contact_tutorial_2' and downloaded the libgmailer script (I'm using 0.9.0beta8) and the msn messenger contact list importer. I've extracted the files from the zip archives and deleted everything except libgmailer.php and msn_contact_grab.class.php.

Database

This is where a generic tutorial starts to make less sense. I think most people will have access to a database but how you interact with it may very well be different. I've mainly been using the MDB2 package available from the pear repository for a while but you may be using the mysql extension, the mysqli extension, the pdo extension, from PEAR there is the MB package, DBA package, MDB package and the MDB2 package. Then there are a near limitless number of custom implementations built on all those and more.

Essentially it's a mess. What I'm going to do in this tutorial is create a class to handle all the database interactions so that if you need to change to your own solution you only need to make changes in one place. To keep things as accessible as possible I'll base the class on the mysql extension. To keep things short in this post I won't include any code here but instead comment as extensively as possible in the files which can be downloaded at the end of this post. Feel free to download those now and follow along as I discuss what is going on.

Three tables will be needed and an sql file for these is included in the download. The first table records to whom emails have been sent. We will query this table to ensure that only one email is sent in relation to one page. The second table records those people who have requested to never be contacted again. The third and final table records the message, subject and link you want to be sent each time someone uses the script. This enables different messages to be sent for different parts of your site.

One thing worth noting here is that we don't store any email addresses. Instead we create a one-way encrypted hash and store that. We don't need the email address itself and this way protects it against mis-use if your database is ever compromised. We will use md5 to hash the emails. Brute force can compromise this protection but it should be sufficient for our purposes.

Three steps

The original tutorial had three steps and three files. Here I'll stick with much the same.

The first file was get_login_details.php and there need only be a small change to this. It was just a html form to get the login details from the user. So that multiple different messages can be sent we will add an identifier to a session variable. This will be retrieved from the url so to send the first message in the database just add ?link=1 to the url.

The second file was called choose_contacts.php and after fetching the contacts from the relevant service presented them to the user so they could choose which ones they actually wanted to contact. The original tutorial script was vulnerable to a malicious user. They could skip the emails returned here and inject any they chose into the final file which would then go ahead and send them all an email. This time we will restrict it so that only email addresses on their contact list can be contacted. To do this the contact email addresses will be stored in a session variable which will then be checked by the third file.

The third file is where things get a little more complex. We have to

1) Check to make sure each email was returned as part of their contact list
2) Establish a database connection and fetch the email subject and message
3) Check to make sure we can contact the email address
4) Send the email and record the fact that it has been sent

We will stick with send_emails.php for the file name. At the top of this file you will need to change the email address in the extra_header variable to your own.

In addition to this you will also need to open up the db_connection.php file and set your database variables in the connect function and change a handful of characters in the salt variable. This is used to make the hash more secure but it is best if it is unique so make a few changes. Once the script is in use though no further changes to the salt should ever be made. If you do the script will no longer be able to tell if an email address has been contacted prior to the change.

Opting out

Finally one additional file is needed. This file will add an email address to the database if the owner of the email address does not want to be contacted again. I would highly recommend you include a link to this file in all your emails. Perhaps something along the following lines at the bottom of each email.

This service is purely a forwarding service. If you would rather not allow people to be able to send you emails via our service, we offer an OPT OUT service. Please visit the following link . . .

Download

The files are available for download. Don't forget to also grab the msn contact grab files and the libgmailer class linked to at the start of the article.

Questions?

There is a lot going on in this tutorial so if you have any questions please post them below and I'll do what I can to help.