1. Introduction

The pnpMail is an e-mail interpreter that can understand special messages, perform required operation and send back results to the sender. The main applications are intended for:

- Cell phone users that would like to check e-mails on their home or office computer and retrieve only e-mails that they are interested in.

- Users at home checking their office mail, or vice versa – checking home mail remotely.

The pnpMail’s interactivity provides an advantage over the ‘standard forwarding or filtering solutions’. In addition to checking and getting e-mail, the pnpMail application gives user a capability to execute any shell command on the remote computer and get results back via e-mail. These commands can be any Windows/DOS or Unix shell command, script, application, etc. For the cell phone users especially, the pnpMail also provides an option to send alerts via SMS (short text message system) indicating that the e-mail response was sent.

It should be noted that the responses (mail lists, retrieved e-mails, application execution results, etc.) are sent back as text only messages. This means that any non-text content and non-text attachments will be removed from the retrieved e-mails (i.e., everything that is not the MIME content-type: text/plain). This is for practical and security reasons. Many mail servers (company e-mail, cell phone providers e-mail servers) remove non-text attachments anyway. Some of their pruning techniques are not so sophisticated, meaning they usually remove all attachments even if the attachments are in the text-only format. On this way all text content is preserved and in the same time the security is improved by removing any other type of the content.

2. Installation and execution

Simply unzip the pnpMail.zip file in the installation directory of your choice. The following is the content of the zip file:

ReadMe.txt – this file (text only version)

ReadMe.htm - this file (HTML version)

pnpMail.jar – the jar file containing the application

pnpMail.properties – the properties file

pnpMail.bat – a script file that can be invoked (sourced) from a command line shell (understanding that ‘Java’ is in the environment’s path)

107 - the version file (please do not edit this file)

Licence.key - the licence key file (not included with demo distribution)

Type the following to run the program: java –jar pnpMail.jar, or invoke the pnpMail.bat script.

The path to the java bin directory has to be set in the execution environment; otherwise the absolute path has to be provided, something like \j2sdk1.4.1_01\bin\java on Windows, or /j2sdk1.4.1_01/bin/java on Unix.

On windows, clicking on the ‘jar’ or on the ‘bat’ file will also work, if the environment is properly set.

No command line parameters are required for a normal execution of the pnpMail program. To see the optional parameters invoke the help screen by executing the pnpMail with ‘-h’ or ‘-help’ parameter. (E.g. pnpMail –h, or java –jar pnpMail.jar –h)

IMPORTANT NOTES:

In order to run the program correctly the following has to be configured and installed first:

(1) Java™ 1.4.1 JRE is required. It can be downloaded at http://java.sun.com/j2se/1.4.1

(2) The properties file: pnpMail.properties has to be configured first – please refer to the section 4. Properties file for more details.
Remember – the properties file has to be in the same directory as the pnpMail.jar

(3) There should be no other e-mail program running that may remove e-mails from the mail server. If you want to run your main e-mail program concurrently with the pnpMail then your program should be configured to keep e-mails on the server and remove them later. The most of the popular e-mail programs allows that kind of setting, i.e. ‘remove after n days’, or ‘remove if deleted from the delete folder’, etc. The pnpMail does not remove any e-mail from the mail server except those special command messages.

(4) The licence key file (Licence.key) has to be in the same directory as the pnpMail.jar
If the licence key file is not present, or the key is not valid, the application will run in a demo mode. The demo mode is fully functional, but the running time of one execution is limited to 20 to 120 minutes, randomly chosen each time.

3. Command line syntax

This application interprets e-mails from the user configured source as commands according to the particular syntax of the ‘Subject’ line in the e-mail.

The basic syntax is the following:
u:username p:password c:command [parameter]

This means that if the (optionally) preconfigured sender is John Doe (the ‘From:’ line) and the preconfigured username and password are: jdoe and jdoepwd then an e-mail having the following lines in the header:
From: John Doe
Subject: u:jdoe p:jdoepwd c:somecmd
will be interpreted as a special command message and consequently act upon.

(NOTE: The ‘From:’ user, the ‘username’ and the ‘password’ have to be configured in the properties file – please see the next section.)

The following are the commands:

lm [n] – sends back an e-mail containing a list of e-mail headers (‘from’ and ‘subject’ lines) on the server. If the optional parameter n is used then only n latest headers are sent.

Examples:

u:jdoe p:jdoepwd c:lm (sends an e-mail containing headers of all e-mails on the server)

u:jdoe p:jdoepwd c:lm 15 (sends an e-mail containing up to 15 headers of the latest e-mails on the server)

lmx [n] – this is the text alert version of the lm command. It does the same thing as the lm plus sends an alert in a form of a short text message to the cell phone’s SMS address indicating that the list is e-mailed.

Example:

u:jdoe p:jdoepwd c:lmx (sends an e-mail containing headers of all e-mails on the server and an alert message to the SMS address)

u:jdoe p:jdoepwd c:lmx 8 (sends an e-mail containing up to 8 headers of the latest e-mails on the server and an alert message to the SMS address)

gm <n> – retrieves e-mail number ‘n’ (as per the e-mail list) and sends it back. If the requested message cannot be found, or the number cannot be correctly parsed an error indication is sent back.

Ex., to retrieve the 5th e-mail:

u:jdoe p:jdoepwd c:gm 5

Notes:
- Any content type except ‘text/plain’ will be removed from the e-mail. Plain text attachments will remain.

- There is no need for space between gm and the number, i.e. c:gm5, c:gm 5, and c:gm 5, all of them are equivalent. Leading and trailing white spaces are trimmed.

gmx <n> – this is the text alert version of the gm command. It does the same thing as the gm plus sends an alert in a form of a short text message to the cell phone’s SMS address indicating that the requested e-mail is retrieved and forwarded, or an error has happened.

Ex., to retrieve the 3rd e-mail and to be alerted when it arrives:

u:jdoe p:jdoepwd c:gmx3

sa – sets the alert. The alert is turned on, meaning that alert messages will be sent to the SMS address for each new e-mail arriving at the server. The alert message sent contains the mail reference number, the ‘from’, and the ‘subject’ lines.

Example:

u:jdoe p:jdoepwd c:sa

ra – resets the alert. The alert is turned off, meaning that alert messages will not be sent anymore for new messages arriving at the server.

Example:

u:jdoe p:jdoepwd c:ra

sf – sets the e-mail forwarding. The e-mail forwarding is turned on, meaning that each new e-mail arriving at the server will be forwarded.

Example:

u:jdoe p:jdoepwd c:sf

Notes:
- Any content type except ‘text/plain’ will be removed from the e-mail. Plain text attachments will remain.

rf – resets the e-mail forwarding. The e-mail forwarding is turned off, meaning that new e-mails will not be forwarded when they arrive at the server.

Example:

u:jdoe p:jdoepwd c:rf

run <cmd> -- executes the cmd, which can be a shell command, a script, or an application and sends an e-mail back with the result.

Ex., to get list of files in the ‘c:\windows’ directory:

u:jdoe p:jdoepwd c:run dir c:\windows

Notes:

- Leading and trailing white spaces around ‘cmd’ are irrelevant.
- The current pnpMail release supports only a blocking execution. The program will wait until the cmd process has finished and only then it will send the response. This means any command expecting a user interaction will wait forever. Considering commands that may ask ‘are you sure y/n’ question this is not really a bad thing …

runx <cmd> - this is the text alert version of the run command. It does the same thing as the run plus sends an alert in a form of a short text message to the cell phone’s SMS address indicating that the result is mailed back.

Ex., to see the content of the log.txt file in the current directory and to be alerted when results are mailed:

u:jdoe p:jdoepwd c:runx type log.txt

4. Properties file

The properties file: pnpMail.properties determines the behaviour of the program. An example of the properties file is presented below. Only the ‘PC mail’ section and the ‘Cell phone section’ have to be filled. The defaults in the ‘Advanced section’ work fine, although the e-mail polling frequency can be adjusted according to the needs.

# ===========================================

# PC mail section

#____________________________________________

# PC mail servers – POP and SMTP [mandatory]

popServer=

smtpServer=

# PC mail user name and password [mandatory]

popUser=

popPassword=

# PC mail address [mandatory]

eMailAddressPC=

# =====================================

# Remote mail section

#______________________________________

# e-mail address for sending responses

# [mandatory]

eMailAddressMobile=

# e-mail address for sending text alerts (SMS)

# [optional]

SMSAddress=

# remote mail’s ‘From:’ line

# [optional]

mailFrom=

# username and password for special messages

# [mandatory]

user=

password=

# =====================================

# Advanced section

#______________________________________

# Check up to <n> latest e-mails on

# the server -- the default is 10.

# To check all mails on the server

# enter 0 or a negative number.

maxHeaders=10

# Check for new messages every <n> minutes

# The default is 5 minutes

pollingTime=5

# PC mail ports – POP and SMTP
# (normally defaults should be used)

popPort=110

smtpPort=25

# How many seconds to wait for server's

# response (1 second retries)

# The default is 60

retryCnt=60

The ‘PC mail’ section completely corresponds to the e-mail setting of your current e-mail program. The server names (POP and SMTP), as well as username, password, and e-mail address should be copied from there. For example, if you have an e-mail account at Shaw cable with username ‘jdoe’, password ‘jdoepwd’, and e-mail address ‘jdoe@shaw.ca’, and knowing that POP and SMTP servers are both shawmail, then the following values need to be entered:

# PC mail servers – POP and SMTP

popServer=shawmail

smtpServer=shawmail

# PC mail user name and password

popUser=jdoe

popPassword=jdoepwd

# PC mail address

eMailAddressPC=jdoe@shaw.ca

The ‘Remote mail’ section offers you a capability to set up two e-mail addresses – one for e-mail responses, and another for short text message (SMS) responses to your commands. The SMS address is optional – if you do not plan to use text message alerts then you can leave ‘SMSAddress’ field empty.

An example for our friend John who has a cell phone with Telus, number 604.555.6666, and cell phone mail box ‘johnd@telusmail.net’:

# e-mail address for sending responses

# [mandatory]

eMailAddressMobile=johnd@telusmail.net

# e-mail address for sending text alerts (SMS)

# [optional]

SMSAddress=6045556666@msg.telus.com

The mailFrom property is optional. It is used to further qualify special messages by specifying their source. It can be left blank.

If you still would like to set this property, then you need to check headers of e-mails sent from the cell phone e-mail account. If the ‘From:’ line has ‘John Doe’ for example then the properties file should have:

mailFrom=John Doe

On the other hand, if the ‘From:’ line has johnd@telusmail.net then that value should be used:

mailFrom=johnd@telusmail.net

Note that the string case is important. On the other hand there is no need to provide the complete string – the exact match is not performed, only the starting part. This means that mailFrom=John will work fine in the first example, while the mailFrom=johnd will satisfy the second case.

The user and the password properties are a very important security feature and they should be chosen responsibly. Currently there is no enforced minimum for the both properties although they cannot be empty. The example below is not the best – user and password values are easy to guess, but for the sake of simplicity we will use it:

# username and password [mandatory]

user=jdoe

password=johnpwd

The ‘Advanced’ section offers additional adjustments:

- Number of e-mails that are checked on the POP server:
The program only checks up to 10 latest e-mails by default. This number can be increased/decreased by entering a different value for the maxHeaders property. To have no limit, i.e. to check all mails on the server, enter 0 or a negative number.

- E-mail polling frequency:
The units are minutes and the default is 5.

- Number of server retries:
The default is 60 (performed every one second). Increase this number if you notice frequent time-out errors.

- POP port and SMTP port values:
These are standard values. In the normal situation there is no need to change the values.

# Check up to <n> latest e-mails on

# the server -- the default is 10.

# To check all mails on the server

# enter 0 or a negative number.

maxHeaders=10

# Check for new messages every <n> minutes

# The default is 5 minutes

pollingTime=5

# How many seconds to wait for server's

# response (1 second retries)

# The default is 60

retryCnt=60

# PC mail ports – POP and SMTP
# (normally defaults should be used)

popPort=110

smtpPort=25

5. Additional info

Please visit the pnpMail page at the http://members.shaw.ca/jvsoft/pnpMail.htm for the latest news, information and the latest product version.

For any additional info please visit the JVSoft main page: http://members.shaw.ca/jvsoft

6. JVSoft Software License Agreement

This License Agreement ("Agreement") is a legal agreement between you (either an individual or a single entity) and JVSoft for the pnpMail software product identified above, which includes computer software, electronic documentation, and the associated printed materials ("Software"). By installing, copying or otherwise using the Software, you agree to be bound by the terms of this Agreement. If you do not agree to the terms of this Agreement, you may not download or use the Software and have to destroy all copies of the Software in your possession.

LICENSE GRANT

JVSoft hereby grants to you a non-exclusive, non-transferable license to use the accompanying Software on the following terms:

You may: a. use the Software on maximum two single computers; b. use the Software on any additional computer as long as more than two computers are not used simultaneously; and c. copy the Software for backup purposes, provided any copy must contain all of the original Software's proprietary notices.

You may not: a. permit other individuals or entities to use the Software; b. modify, translate, reverse engineer, decompile, disassemble (except to the extent applicable laws specifically prohibit such restriction), or create derivative works based on the Software; c. copy the Software (except for back-up purposes); d. rent, lease, or otherwise transfer rights to the Software; or e. remove any proprietary notices or labels on the Software.

The Software is in "use" on a computer when it is loaded into temporary memory (i.e., RAM) or installed into permanent memory (e.g. hard disk, CD-ROM) of that computer.

TITLE

Title, ownership rights, and intellectual property rights in and to the Software, and any copies of the Software shall remain with JVSoft and/or its suppliers. The Software is protected by the copyright laws and international copyright treaties. Title, ownership rights, and intellectual property rights in and to the content accessed through the Software is the property of the applicable content owner and may be protected by applicable copyright or other law. This License gives you no rights to such content.

SERVICE AND SUPPORT

The service and support that JVSoft offers for the Software under this Agreement are limited to the service or support, if any, that is freely available on JVSoft's Web site.

TERMINATION

This license will terminate automatically if you fail to comply with the limitations described above. On termination, you must destroy all copies of the Software.

NO WARRANTY

The Software is supplied on an "as is" basis, and you will bear all risks as to quality and performance of the program. Without limiting the generality of the foregoing, a. you assume the entire cost of any service or repair and of any damage resulting from the information contained in or compiled by the Software, and b. you assume all responsibilities for selection of the Software to achieve your intended results, and for the installation of, use of, and results obtained from the Software.

JVSOFT MAKES NO OTHER EXPRESS WARRANTY AND NO WARRANTY OF NO INFRINGEMENT OF THIRD PARTIES' RIGHTS. THE DURATION OF IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION, WARRANTIES OF MERCHANTABILITY AND OF FITNESS FOR A PARTICULAR PURPOSE, IS LIMITED TO THE ABOVE LIMITED WARRANTY PERIOD; SOME COUNTRIES DO NOT ALLOW LIMITATIONS ON HOW LONG AN IMPLIED WARRANTY LASTS, SO LIMITATIONS MAY NOT APPLY TO YOU. NO JVSOFT DEALER, AGENT, OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, EXTENSIONS, OR ADDITIONS TO THIS WARRANTY.

THIS WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS, AND YOU MAY HAVE OTHER LEGAL RIGHTS THAT VARY FROM COUNTRY TO COUNTRY OR BY JURISDICTION. LIMITATION OF LIABILITY. UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, TORT, CONTRACT, OR OTHERWISE, SHALL JVSOFT OR ITS SUPPLIERS OR RESELLERS BE LIABLE TO YOU OR ANY OTHER PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR MALFUNCTION, OR ANY AND ALL OTHER COMMERCIAL DAMAGES OR LOSSES, OR FOR ANY DAMAGES IN EXCESS OF JVSOFT'S LIST PRICE FOR A LICENSE TO THE SOFTWARE, IF ANY, EVEN IF JVSOFT SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. THIS LIMITATION OF LIABILITY SHALL NOT APPLY TO LIABILITY FOR DEATH OR PERSONAL INJURY TO THE EXTENT APPLICABLE LAW PROHIBITS SUCH LIMITATION. FURTHERMORE, SOME COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THIS LIMITATION AND EXCLUSION MAY NOT APPLY TO YOU.

This Agreement is the entire Agreement between us and supersedes any other communications, advertisements, or understandings with respect to the Software.