Introduction

Useful Mailer is a newsletter system that can send any number of mails. With the editor you can create HTML mail. A text only version is created automatically and sent with the mail, so text only email readers or email readers with HTML option turned off will also be served. In the HTML message you can include images inline. That means the images will be sent together with the mail message. Images on remote server that are only referenced will be filtered out by many email programs for security reasons. Up to two attachments can be sent together with the message, ( e.g. an Excel spreadsheet and a PDF document). Your messages can be personalised, that means that individual data like first name, last name, a gift certificate code etc. can be inserted in each mail. Email addresses and possible other individual data are drawn from CSV files, so no database is necessary. You can manage your data in Excel datasheets, your local database or any other way, output them as CSV files and feed them to the Mailer. After sending the Mailings you can delete your valuable data from the server. But of course it is possible to adapt Useful Mailer to your existing database. If you have access to the crontab of your server you can control your mailer with a cronjob. As an alternative the system posses a pseudo-cronjob that triggers mailings from your local computer.

Contents

• Installation
• Administration
  • Settings
  • Sender settings
  • Control lists
• Main menu
  • Adress lists
  • New draft
  • Personalising emails
  • Saved drafts
  • Manage images
  • Send mail
• Tools
  • Continue
  • Kill task

Installation

Unpack the ZIP file and upload the complete folder usefulmailer to your server. Secure the system with an .htaccess file. (If you don't know how to do this, you can find information here , or you can use this script to generate the necessary files.)

Set writing permissions (CHMOD 777) for the following directories:

attachments
config
control
emails
images
lists
tasks

(All except graphic_elements and scripts)

Please delete the file named delete_this_file.htm from the directories named above.

Administration

Settings

Cronjob

A script can only send a limited number of mails in one go. Furthermore the spam watchers might prick their ears if several hundred mails are sent within a few seconds. For this reason the script must be called in regular intervals until all the mails are sent. If you have access to the crontab of your server, use this. Ask your provider how to do this. The script that must be triggered by the cronjob is sendmail.php.

A typical crontab entry could look like this :

1,6,11,16,21,26,31,36,41,46,51,56 * * * * cd /home/useful/www.useful-scripts.biz/docs/usefulmailer; /var/www/php4/bin/php.cli ./sendmail.php

If the minimum interval allowed by your provider is e.g. 5 minutes you can set the number of mails per round to 10. More would not be advisable if you are using inline images or attachments. When testing with cronjob though we successfuly sent 200 mails at one go.

If you do not have access to your server's crontab,click Local pseudo-cronjob. In this case you must let the program run until all mails are sent.

Number of mails per program call

Enter 10 if the system will be steered by the server crontab. If you select local pseudo-cronjob a good setting is to send 1 mail every 10 seconds (10000 milliseconds).

Interval in milliseconds

Only has a meaning when local pseudo-cronjob is being used. Enter the number of milliseconds between program calls, eg. 60000 for 1 minute. Otherwise set it to 0.

Term used for column that contains email addresses

The CSV files you are using must have the names of the columns in the first line. Here is an example:

firstname;lastname;email 
Jane;Doe;jdoe@example.com
Martin;Auer;mail@martinauer.net
Erika;Mustermann;mustermann@beispiel.de
Marko;Markovic;m.markovic@froozle.net
Matti;Meikäläinen;meikalainen@froozle.net

The order of the columns is not important, Useful Mailer will also be happy with this:

mail;firstname;name;giftcertificate

"Jane Doe" <jdoe@example.com>;Jane;Doe;EF58lW17Y

Only enter the term you use for the column containing the email address. Even if you use only one column that contains nothing but email addresses you must state the name of the columns in the first line and enter it here.

Separators in CSV files

Enter here the character that is used to separate the values in each line. In our example this would be the semicolon: ;
Please do not use the tab as a separator!

Email address that error messages should be sent to

When you let a cronjob steer the system the program cannot display possible error messages in the browser. For this reason it must send them by email. Enter here your own email addres or the the email of your sysadmin.

Sender settings

Sender email address

Enter the email address that should appear in your newsletter as the senders email address. Replies and possible error messages my mail servers will be sent to this address.

Sender name

Enter a name here. Must email clients display this name in the overview panel.

Logfiles

When you send a newsletter, for each sent mail the system enters the date, time and email address of the recipient into a logfile that has the same name as the draft. After sending the mailings you can check this list and delete it when you don't need it any more.

Main menu

Address lists

Here you manage your address lists.

Select list

The dropdown menu displaysthe names of all the lists you have saved.When you select a list it will be displayed and you can check it, edit it and save it again.

When you select Enter new list you can manually enter or copy and paste a new list. Enter a filename and click save. If you don't enter a filename the list will be saved with the date and time as filename.

Filename

If you have selected a list and enter a new filename in this field (without file extension) you can save the list under a new name.

Upload list

Here you can upload a list from your local computer. After uploading you can view and edit it.

New draft

Email Editor

Here you can design an email in a WYSIWYG HTML editor that works just like a word processor. Each icon of the editor shows a tooltip that explains its function when you point the cursor on it.
Enter a filename and save your email draft. Use a table to design mails with more than one column.

Inserting Images:

In the text editor click the icon "image". The dialog "image" will open. To the right of the input field "File Path" there is an icon in the form of a folder. Click it-. The dialog "Asset manager" will open. It will show you a list of images available. Click one of the filenames to see a priview. Click OK and the file path will be entered into the input field. (You can also use the asset manager to upload and delete images) Now do the necessary formatting in the "image" dialog.

If you enter the full URL of an image
E.g. http://www.example.com/images/image.gif
the image will not be sent inline. Only the link to the image will be sent. Do this only if you have special reasons, because many email clients will filter out linked images for security reasons.

You can also design a page in your favorite HTML editor and then paste it into the email editor. Click the HTML code icon and paste the code into the dialog window that opens. Only copy the part between the <body> and </body> tags, because the head and body tags will be added by the system.

Avoid layouts that are too complex and test every layout with different email clients because thay all handle HTML mails differently.

Personalised emails

Suppose your CSV file looks like this:

firstname;lastname;email;code
Jane;Doe;jdoe@example.com;EK546lMp 
Martin;Auer;mail@martinauer.net;noP59RdD

Then you could formulate your email like this:

Hi {firstname} {lastname},

to show you our appreciation as our valuable customer
we send you a gift certificate worth $10 that you can
use for any purchase in our online shop. Just enter 
the following code in the field

{code}

And you will receive a rebate of $10.

In each mail the term between the {braces} will be replaced by the term under the respective column heading.

Saved drafts

Here the names of the drafts that you have saved in the system are displayed. Click on any of them to display and edit the draft or save it under a new name.

Manage images

Here you can upload, view and delete images.

Send mail

From the dropdown menu select one of your saved email drafts.
A second dropdown menu will appear.
Select one of your saved attachments or no attachment.
If you select an attachment another dropdown menu will appear from which you can select another attachment.
Otherwise there will appear a dropdown menu from which you can select one of your saved address lists.
A summary of your selection appears and the field Subject. Enter a subject for your mailing.

Check your selections.

Check your selections once more.

Click Send mail.

If you are using the cronjob of your server the message Mail task [subject] has been saved will appear. You can now close the browser window and do something else. In case a previous mail task has not been completed you will see the message Mailt task cannot be saved because the previous mail task has not yet been completed. In this case you must wait till the old task is finished and then send your mailing again.

If you are using the local pseudo cronjob you will see a window in which you can watch the system working. You will see these messages:
MAILS YET TO BE SENT:
LIST EMPTY
THERE IS NO TASK TO PERFORM
Only when you see the last message the mail task is completed.
You also see the address(es) currently served and the number of the program call.

Tools

Continue

When you are using the local pseudo cronjob and you close the browser window, the mailing will be interrupted. You can resume the task by clicking Continue.

Kill task

You can stop the execution of the current task by opening this panel and clicking on Kill task. This will stop the mailing if you use cronjob or local pseudo cronjob.