PHP E-mail to SMS (PETS)

• Introduction
• Features
• Requirements
• Installation
• Usage
• Download
• Phone call-back by e-mail
• PHP5 soapclient conflict?
• Other Errors
• History

Introduction

PETS is a simple PHP script to read a mailbox and send the contents (or partial contents) to a mobile phone by SMS (short message service).

Possible uses

• Sending SMSs via e-mail from a scheduling/calendar program
• Sending SMSs via e-mail from some automated monitoring process, to report problems.
• Setting a mail rule in an e-mail client to forward important e-mails via SMS.

Features

• Limited commands can be incorporated into the subject line.
• Can send to a group that is in your PennyTel address book.
• Long messages are truncated.
• Simple anti-spam measures are incorporated.

Requirements

As provided, the script uses the API and SMS services provided by PennyTel. No doubt you can change that to use another provider.

Thus, you need a PennyTel account.

The script uses the NuSOAP SOAP classes.

You will need a mailbox reserved to receive the e-mails that are destined to be sent as SMS.

A Web server able to run PHP scripts.

Installation

I have installed and tested this (NuSoap ver. 0.7.2) on a commercial shared server. I imagine it could be installed on any server that runs PHP.

The PETS script

Download and unzip the PHP file to your local computer.
Rename the file name from pets.php to a name of your choice, if you wish.
Edit the configuration file pets-cfg.php to customise the variables to set your PennyTel account details:

For security, leave the configuration file with the .php extension.

Upload the script file and configuration file to a directory of your choice. For example, example.com/pets

For better security, depending on your host, you can put the configuration file outside the public html area. Just change the path to the include file. Eg., something like: include '/home/username/pets/pets-cfg.php';

NuSOAP

Download the NuSOAP PHP class and upload it to your server. PETS assumes that it is installed at the same level as PETS itself, in a separate directory. That is, if PETS is in:

example.com/pets, then NuSOAP will be in:
example.com/nusoap.

You can modify the path if required, at the require_once('../nusoap/lib/nusoap.php'); statement.

Current code now works with NuSOAP version 0.7.3 and with PHP 5.2.5 and 5.2.6.

Log file

If you wish, PETS can create a log file of activity. This is a simple text file, formatted as CSV to simplify loading into a spreadsheet. You will have to manually delete the log file at some stage as there is no process to stop it growing.

The zip file contains a file called master_smslog.csv, which is just one line of descriptive headers, which you can rename (to the default smslog.csv) and upload to the same directory as the PETS script. You will probably have to use your FTP program to change the permissions of the file so that can be written to (try 666).

The log file records the following:

• Method - echoes the subject line command; reports as SPAM if so, or NOGROUP if there were no entries found in the specified address book group.
• Destination - mobile number to which the SMS was sent.
• Result - SENT or NOTSENT.
• Timestamp - when sent.
• Subject - echoes the subject line, including the command string.
• FromName - the "friendly" name of the sender of e-mail, if available.
• FromAddress - e-mail address of the sender.

Scheduling with cron

Of course, the mailbox needs to be checked on regular intervals. The easiest way to do this is configure a cron job on the server.

How that is done will depend on the control panel used there (if you are not using crontab directly). If you are using cPanel (cron Jobs, Unix style), then do something like:

and use a command like (may depend on your host):
/usr/bin/php /home/username/public_html/pt-sms/sms.php

That will run the script every 5 minutes. Change as required. In the field for an e-mail address for the cron results, enter either a valid e-mail address to receive the results, or enter /dev/nul to send the results nowhere. In some cases, (e.g., some versions of cPanel) the e-mail field should be left empty if you do not want e-mails of the cron results.

Usage

Subject line commands

The behaviour of PETS can be controlled by some extent with commands in the e-mail subject line. The codes can be changed in the script. They commands are case sensitive and must appear at the beginning of the subject. The surrounding symbols ([[ and ]] for example, as the default) must also appear. The commands are not sent as part of the SMS message.

NOTE: Do not try to use angle brackets (<, >). PennyTel will not send SMSs with them in the text. PETS converts them to underscores. Messages sent from Outlook Express as HTML e-mails are sent with a text part and an HTML part. PETS retrieves only the text part, without HTML coding. Any remaining angle brackets are converted to underscores.

The group name is the name as per the group name in the PennyTel account address book. It it not case sensitive, but the name must match exactly otherwise. That is, spaces, etc, are significant. WARNING: No checks are made as to the number of entries in your particular PennyTel group, so if you are not careful you may end up sending to a lot of phones.

Because you may want to send e-mails from some automated process, or forward some e-mails that arrive, but are thus unable to modify the subject line, PETS allows the sending of messages without the subject line commands. However, the sender of the e-mail must be in the list allowed in the $Allowed_Addr variable, otherwise the mail will be classified as spam, and not sent.

Because the Short Message Service does not guarantee delivery, it may be worth considering configuring the e-mail address for the SMS mailbox so that it also forwards the e-mail to another e-mail address. That way, you will obtain the (full) contents of the message by e-mail, as well. You should be able to do that on the host server.

Message Format

Messages are sent in the following format, with the items separated with dashes:

<Subject>-<From (name)>-<From (email address)>-<Body of e-mail>

PennyTel allows messages of up to 255 characters and will automatically send up to two SMSs. PETS uses this feature; messages longer than the limit (default of 255) are truncated, and the indicator of "-more." is appended to the end of the message.

End-of-lines, excess whitespace, and HTML tags are stripped.

Download

Previous version: 1.3 June 2007 (for NuSOAP 0.7.2)
pets.zip (8k)

Current version: 1.4 June 2008 (for NuSOAP 0.7.3)
pets-1-4.zip (10k)

Phone call-back by e-mail

Here is an "offshoot" of the project... a script that will make a VoIP call-back, initiated by e-mail.

Subject line is:
<First leg><space><second leg>
Eg:
617xxxxxxxx 612xxxxxxxx
will have the originating call (first leg) go to a Queensland number, and the destination to NSW.
NOTE: THIS IS ONLY DEMONSTRATION, PROOF-OF-CONCEPT CODE!! (E.g., PennyTel account details are hard coded.)

For use with NuSOAP 0.7.3 you'll need to change line 22 to:
$client = new nusoap_client("http://pennytel.com/pennytelapi/services/PennyTelAPI");

php-cb-demo.zip (2k)

PHP5 soapclient conflict?

If you are getting an error message something like:
Fatal error: Cannot redeclare class soapclient in <your host path>/nusoap/lib/nusoap.php on line 7240 then it could be some conflict with PHP5 builtin soapclient.

Do this to fix it (this should not be necessary if you are using NuSOAP 0.7.3):

Edit all the occurrences of "soapclient" in the files in nusoap/lib, changing to, say, "soapclientNU". Not all files have it. Take care to not modify names of which "soapclient" is a subset. Rename the file class.soapclient.php to class.soapclientNU.php (if you also changed references to it).

Change (line 50 approx.), in pets.php, the line:
$client = new soapclient("http://pennytel.com/pennytelapi/services/PennyTelAPI");
to
$client = new soapclientNU("http://pennytel.com/pennytelapi/services/PennyTelAPI");

[Here are the edited files for version 0.7.2 (they go in the nusoap/lib directory): nusoap-0-7-2-nu.zip. You'll still have to edit line 50 of pets.php if you use those modified lib files.]

Other Errors

If you get an error such as the following, then double check your PennyTel login usrename and password.

Array
(
    [faultcode] => soapenv:Server.userException
    [faultstring] => java.lang.NullPointerException
    [detail] => Array
        (
            [hostname] => penny1
        )

)

History

• 1.1: Change method of getting parts.
• 11 May 2007
•  
• 1.2: Modify the handling of angle brackets (<, >)
• 14 May 2007
•  
• 1.3: Add $Allow_Any_Sender option
• 2 June 2007
•  
• 1.4: Change to work with NuSOAP 0.7.3
• Change maximum message length to new shorter PT limit.
• 10 June 2008

Disclaimer

This program is provided as is, with no warranty of any kind. Use of the program for any legal purpose is permitted, so long as accreditation is not removed from the code.