Copyright 1999, 2000, 2001 Oliver W. Schulz
Contact: Oliver W. Schulz
(scripting@ulices.com)

Thank you very much for choosing @News Wizard.
Please read this documentation carefully. It contains all of the information which is necessary to install and run @News Wizard on your server.

If you only see an empty screen just after you started @News Wizard, please contact us !

Features
Advantages
Installation
  Creating your own subscribe forms
  Changing to a different language
  Changing the system message texts
Usage
  Subscriber lists
  Confirmation request option
  Autosend option
  Personalize newsletters
  Newsletter texts
  Autoresponder
  Subscription process
  Unsubscription process
  Sending newsletters
License Agreement and Disclaimer
Your Suggestions and Critics

• Multilist Management - unlimited lists
• Multi Newsletter Management - unlimited newsletters
• Plain ASCII text or HTML messages
• Customizable auto-personalization of messages
• Anti-spam security (double opt in)
• Logs subscription date
• Logs IP addresses
• Automatically sends your newsletter to your new confirmed subscribers (optional)
• Allows for easy unsubscription with just a click
• Recognizes re-subscribers
• Checks for data dupes
• Checks for correct email address
• Automatically sends an error-report on invalid subscribers
• Automatically addresses your newsletter in a personalized way considering name and gender of your subscribers
• Offers complete password protected administration over the internet
• Allows for uploads of new newsletters and entire address-lists, etc.
• Allows for online editing of your newsletter text
• Allows for online editing of the subscription autoresponder text
• Takes care of mailing your newsletter to all subscribers
• Allows for selecting your recipients according to a subscription date range
• Automatically sends a journal with statistics after completion of every mailing session
• No time-out-errors while sending thousands of newsletters !!!

You might ask: "What's so special about mailing software ?" Of course, there are many ways to get your messages and newsletters mass-mailed to your customers. But one of the advantages of server-side mailing software like the @News Wizard is that you do not necessarily have to operate from your own computer in order to manage your mailings and customer data while you are, let's say, on a business trip. You need not carry your data with you and you can use virtually any machine that offers you access to the internet. You do not need your personal equipment to keep in touch with your customers. It's certainly one of the most effective, flexible and cost-cutting ways of doing your mailings.

Just logon to your @News Wizard on your website and edit your subscribers list or update your newsletter instantly. If you feel urged to inform all of your customers about any news and if you wish to address every customer in a personalized way, just logon and let @News Wizard do the job for you. With very few clicks everything is done in a few seconds - from wherever you are... anywhere... anytime.

"...There's a lot of free stuff out there. So, why should I purchase the @News Wizard ?"

Correct ! There are many mailing list programs out there. And some of them have really nice features. But to enjoy all of these features it would be necessary to run several of those programs on your website. Each for every feature you like to use. @News Wizard combines them all in one.
Besides that, unlike many other "mass" mailers @News Wizard offers an efficient means to avoid time-out-errors while you send thousands of newsletters.

Please read this section very carefully. Unlike previous versions of @News Wizard this version comes with one additional script "setup.cgi" which takes care of setting the respective variables and which offers you a web form to set all the values. You no longer need to edit the scripts themselves except for the very first line of every script: This first line indicates the location of PERL on your server. By default this value is set to "#!/usr/local/bin/perl". If your script does not execute due to an incorrect setting here you may modify this line and try "#!/usr/bin/perl" instead.

The paths and directories you will see when calling the setup script for the first time are examples only. However, they are fully operational if you choose to setup your @News Wizard using the suggested paths and values.

Note:
@News Wizard has extensively been tested on UNIX style servers. @News Wizard has also been installed and run on Windows NT servers with "windmail" as default mail program. However, when running @News Wizard on an NT server, some modifications may become necessary. UNIX style directory/file separators (forward slash) '/' may have to be replaced with '\' (escaped back slash --> double back slash). Besides, all messages / newsletters may need to have a single dot all by itself in the last line right before the end of the document you wish to send using "windmail".

After you unzipped all packages proceed as follows:

• Open sendnews.cgi, editnews.cgi, upload.cgi and setup.cgi with your favorite text editor and edit the very first line to reflect the location of PERL on your server (just like I explained in the introduction to this chapter).
  If the interpreter is at /usr/bin/perl, then this line should be #!/usr/bin/perl. You can get this information with the command "which perl" or "where perl" on the command line once you have telnetted to your account. Check with your system admin if you're not sure.
   
• Now open the two forms edit-news.htm and news-form.htm and change the "<FORM> - tag so that it points to editnews.cgi on your domain. It should look something like:
  
  <form ACTION="http://yourdomain.com/cgi-bin/editnews.cgi" METHOD=post>.
   
• Login to your server account and create the following directories. Tree 1 and 2 may serve as examples where tree 1 represents the most typical directory structure on many webservers with the 'cgi-bin' (many times also called 'cgi-local' or 'bin', etc...) directory under your 'web space directory' (often times found as 'public_html' or 'www' or 'htdocs' or 'httpdocs').
  Another commonly found structure is the one of tree 2 with the 'cgi-bin' directory directly under your 'root directory'.
   
  

  Tree 1	Tree 2

  
  Set the following permissions:
  data  rwxrwxrwx CHMOD 777
  temp rwxrwxrwx CHMOD 777
   
• Copy all four cgi-files into your cgi directory on your server and set the the proper permissions: CHMOD 755.
  Also copy the important "setup.dat" and "(languge).lang" files into this directory (along with the cgi's) and set the permission of these files to CHMOD 777.
  CAUTION: Upload all files in ASCII (text) mode !!!
   
• Now simply copy the rest of the files into their directories:
  
  nwswiz:
  All the files which you found in the nwswiz directory when you unzipped the package. They also contain the two forms which you had edited earlier, remember? :-)
  CAUTION: Upload all files in ASCII (text) mode except for the two GIFs (binary mode) !!!
   
  nwswiz/data:
  All the files you found in the nwswiz/data directory when you unzipped the package. Set their permissions to CHMOD 777.
  CAUTION: Upload all files in ASCII (text) mode !!!
   
  nwswiz/temp:
  You may leave it empty. This directory is used by @News Wizard to temporarily store data when doing his job.
   
• Once all files are up you can now call the setup.cgi through your web browser and determine all the necessary information. If you chose the default directory structure you probably need not change anything except for one thing: the location of "sendmail" on your server.
  By default, the location is set to '/usr/sbin/sendmail -t'. If you experience that @News Wizard is not sending any messages it is most likely that your sendmail-path is somehow incorrect or your sendmail may be allocated somewhere else on your server. In this case try the following commonly used locations:
  
  /usr/sbin/sendmail -t
  /usr/bin/sendmail -t
  /usr/lib/sendmail -t
   
  Never forget the -t switch !!!
  Again, check with the system admin if you can't figure out where "sendmail" is on your server.
  

Do not forget to copy the index.php files into each of the directories as well. This will prevent your files from being displayed to the people who type the directory name into the location field of their browsers.

- Customizing the HTML output for your website

This part of the configuration refers to the html output of all response pages. These are the pages which your subscribers will see when they un/subscribe to your newsletter. So, you can determine the colour of several items like page background, text, table header, etc....

The setup script allows you to determine the generic properties of the response pages like the background color or background image or the color of the page and font.
But the way in which system messages are displayed to your subscribers is determined by the template "response.dat". You are free to create your very own design and layout in order to match your website's design. You only need to place placeholder- variables to let the messages appear in your design. These are the following:

[SYS_TEXT]          - Displays the system message
[BASE_URL]          - Displays the Homepage link
[BACK_BTN]         - Displays a Javascript Back Button


- Creating your own subscription form

The delivered subscription form "news-form.htm" is an example only. Since the form is the only static element of this package on your website it has to be edited manually everytime you set up a new list or modify your old lists.
You would certainly want this form to fit into your website's design and therefore may create your very unique and individual form. You may also create more then one form and place them all over your site.
You can also remove some fields if you don't need them but keep in mind that you need to provide the list number information if you remove the list selection tag. The 'select' tag must then be replaced by a 'hidden' tag which carries the value of the list number in order to let @News Wizard know which list the subscriber wishes to subscribe to when he submits the form. The name of this tag remains the same: name="list_nr"
 

- Installing a new language module

@News Wizard is available in different languages. In order to change the language of all displayed text you need not reinstall an entirely new copy of @News Wizard. Just get the desired language module and place the "(language).lang" in your cgi-bin directory. Place the documentation file and the little flag (gif file) in your nwswiz directory and you are ready to go. Call your setup.cgi again and select the new language from the pulldown menu. That's it.
The language modules which include the translated documentation are available on our website: ulices.com
 

- Changing the text of the system messages

All system message texts are stored in the language file. If you wish to modify the texts in order to adapt them to the language or style of your website, just edit this text file with a simple ASCII text editor. All messages are stored as value of variables. To modify the text, only modify the value within the quotation marks. Never change the variable names!

  
If you wish the installation to be done by us, please feel free to purchase our installation service.

If you only see an empty screen after you started to run this script, please contact us !

Everything you need to do to control and maintain your @News Wizard can be done from the administration level. Just call your edit-news.htm page and enter your passcodes. The following administration screen is almost completely selfexplaining.

The newsletter subscription form is called news-form.htm.
To access the administration of the @News Wizard call edit-news.htm.
By default the administrator's name is admin. The default password is password. You should use your own access codes
 

- The Subscriber Lists

The subscribers list files recipientsx.dat (where 'x' is the number of the list) contain your subscribers data in the following format:

Status|Email|Form of address|Name|Familiy name|DD|MM|YYYY|xxx.xxx.xxx.xxx 

Example:

A|john@smithis.net|Mr.|John|Smith|23|10|1999|200.200.200.200
P|mary@humba.com|Mrs.|Marilyn|Monroe|27|10|1999|200.200.200.200
... etc.

Please note that you need the pipe-sign  " | "  to be the delimter of the data-elements.
You may either upload your list with the built-in quick&easy upload function or upload it manually via FTP. Just make sure then that you use ASCII mode and that the permissions are set correctly then (all writable CHMOD 777).

It is most likely that you would like to use your old list to work with @News Wizard. Very probably it does not carry the additional data which @News Wizard needs in order to treat every subscriber in a personal way (form of address, name, etc....).
In that case you will have to convert the list to the required format.
If you upload a new list you must first formally create that list in the admin section prior to actually uploading it.
If you use your old list keep in mind that the list file has to be named recipientsx.dat where x is the number of the list.

@News Wizard comes with his own built-in list converter. Just upload your old address list which carries only an email address per line. Once you have uploaded this list just press the "Convert!" button. That's all you have to do !
@News Wizard has now converted your list to the required format, assigning the current date as the subscription date and setting the status of every subscriber to "A" (A= Active, P=Passive):

A|john@sampledomain.com|-|-|-|01|01|2001

"A" at the beginning sets the subscriber to an "Active" status which means that she will actually receive your newsletter when you start your mailing session. "P" will set this entry to "passive" and will cause @News Wizard to skip this entry when sending out the newsletter next time.

Once in use, @News Wizard takes care of the list and subsequent subscribers are listed automatically in the correct format.

IMPORTANT:
The address list is the vital part of a mailing list porgram. Make sure that the list contains only pure ASCII characters and no tabs, etc...
Be absolutely sure that your list shows exactly the required format !  If this is not the case your list will prevent the program from working properly and most likely will cause server errors.
Should your program cause a server error and you are sure that your script configurations are all correct, you have a 99% probability that a somehow incorrect list format caused that error. Please revise your list and pay special attention to the correct format of the email-addresses contained in your list !
It is most recommended that you let @News Wizard convert your list.
So, just make sure your email-addresses have a valid format (No empty spaces, etc.!).
Depending on your server's performance, we do not recommend to use lists with more than 20.000 entries.
 

- Confirmation requirement option

This is a very strong feature in several aspects. If set to "on" @News Wizard will send a confirmation request to every new subscriber which needs to be confirmed before he/she will actually be added to the list. This is a very usefull option because it ensures two things:

1.)
The email address is formally correct and valid. Otherwise the confirmation request would not have reached the subscriber. Thus it is guaranteed that you do not collect "dead" addresses keeping your list clean and building up a valuable stock of addresses.

2.)
It ensures that the subscriber really is the subscriber thus protecting other people from being spammed when somebody decides to enter the email-address of somebody else.
 

- Newsletter autosend option

This option is yet another automation feature of @News Wizard.
If set to "on", your subscribers will be added to the database and automatically be delivered the current issue of your newsletter immediately upon their successfull subscription. No manual intervention is required in order to satisfy your subscribers' demands immediately.
If set to "off", your subscribers will be added to the database but will not receive the newsletter until you start your next mailing session.

- Personalization of your messages

@News Wizard is able to individualize each and every newsletter you send out automatically. This seems to be one the greatest features since your subscribers would not receive a rather generic, unpersonal email but a personally addressed newsletter.
On the configuration page you determine how @News Wizard will proceed to personalize your messages:

To personalize a salutation, @News Wizard can replace the following placeholders:

The field "Default newsletter salutation" defines the generic salutation employed whenever @News Wizard is unable to personalize the newsletter due to insufficient information provided by the subscriber.

The field "Personalized salutation" defines the template for the personalized salutation substituting the placeholders by the subscribers' provided information.
Example:
Given that your subscriber's name was John and you defined the template as "Dear [1NAME]". In this case @News Wizard will replace the [1NAME] by "John". The result is "Dear John". If John did not provide his name when he subscribed, @News Wizard will use the generic salutation which you had defined instead.
The same procedure applies to [2NAME] and [ADDRESS].

The "Personalize if given" field lets you select the personal information that must be provided by your subscriber in order to have @News Wizard make use of the personalized salutation which you defined in the field "Personalized salutation". When you wish to address your subscribers with their first name only, check the box "First name". In your defined personal salutation the placeholder [1NAME] will then be replaced by the subscribers name he had given when he subscribed to your newsletter.
IMPORTANT:
Make sure that your template contains the placeholders you checked as required info !

Finally, if you whish your newsletter to actually carry the salutation at all (means: in order to actually display any salutation in the newsletter), just add the placeholder [SALUTE] to your newsletter text file. You can place it anywhere in the text you wish. [SALUTE] will be replaced with the generated personalized or generic salutation discussed earlier.

To add the subscription link to your autoresponder text, just place [START] anywhere in the text. This link will allow your subscribers to actually confirm and subscribe to your newsletter and be added to the list.

If you add the placeholder [END] to the end of your newsletter, your subscribers will automatically receive their personal unsubscription link appended to their newsletter. You should always offer your subscribers an option to unsubscribe.

You may take the delivered demo newsletters as samples to see how newsletters can be arranged.
 

- The Newsletter Texts

The newsletter text files newsletterx.txt (where 'x' is the number of the letter) may be plain ASCII text or HTML files.
@News Wizard maintains an unlimited number of newsletters. You can edit your text online or upload a prepared document with the built-in upload function.
Every newsletter carries its own message-type and subject line information.
The administration level allows you to set the autosend option. This option determines whether new subscribers receive the current issue of your newsletter immediately upon confirming their subscription. If set to "Yes" they will automatically receive your newsletter. If set to "No" their data (subscription) will be stored in the database but they will not automatically be sent your newsletter unless you start a mailing session.
 

- The Autoresponder Text

The autoresponder text file autoresponder.txt can also be a pure ASCII text or an HTML file.
You can edit this text online. This is the text that will be sent to the people who fill out the subscription form on your website. This message asks the subscriber to confirm his subscription (if you have set the confirmation requirement option to "Yes"). You may also add special information and announcements. The autoresponder is generic and will be sent to the subscribers of all lists.
 

- The Subscription process

When people subscribe to your newsletters they make use of the form news-form.htm selecting the list they wish to subscribe to and filling in the form fields. @News Wizard will use these informations to properly address the subscribers when they receive your messages. If the fields are left blank, @News Wizard will use the default salutation (which you can determine in the admin-section) instead.
Before a subscriber actually gets added to your list, @News Wizard will first send him the autoresponder message, asking the subscriber to confirm his subscription request. This is an efficient means to protect people from spam-attacks. His/her data will be stored in a temporary file. Once confirmed, @News Wizard will retrieve this temporary data and add the new subscriber to the requested list. The temporary file will then be deleted.

IMPORTANT:
Every list is associated with its corresponding newsletter. So, list 1 is associated with newsletter 1 and so on. If you have set up your subscription form offering 7 lists, make sure you have technically created 7 newsletters and numbered them accordingly. Otherwise your subscribers will receive an error message saying that the selected newsletter could not be found.

- The Unsubscription process

When people unsubscribe, @News Wizard will also request a confirmation to complete this process. Once confirmed, the subscribers data will be stored in a temporary list file.
Note: He will not be deleted from the list at this point. Only will he be set to status "P" (inactive).
This procedure will prevent your server from heavy workload because the list is not edited everytime a subscriber unsubscribes. Imagine you just sent your newsletter to 20.000 people and right upon receiving it, 2.000 of them wish to unsubscribe almost simultaniously. Editing the entire list 2.000 times would certainly bring your server down to the knees.
No, in order to prevent you from being kicked out by your host service provider for torturing his servers, @News Wizard gathers all unsubscribers in a separate list and edits the actual list only one time for all unsubscribers. This will happen when you press the overview button or start a mailing session the next time. @News Wizard will do this job in the background... you will not even notice it.

- Sending your Newsletters

When you're sending mail, the browser will constantly update the number of messages sent.
While the mailing is in progress do not close your browser unless you wish to stop your mailing session ! If you stop the mailing session, nothing will happen, but the script will stop sending mail wherever it happens to be.

Before you actually send your newsletters you can select the newsletter text as well as the recipients list. Please note that by default text 1 is associated to list 1 and so on. You may override this association and choose a different combination to send a newsletter to a different list. In this case @News Wizard will give you a warning message and will ask for your confirmation prior to actually sending the newsletters out.

- Miscellaneous

The administration level is mostly self-explaining and allows you to maintain and send your newsletters. The subscribers lists recipients(x).dat as well as the newsletter(x).txt textfiles can be edited online or uploaded in one piece. This feature allows for comfortable updates prepared offline on any machine and a simple upload of everything onto the server.
We think this is a real time and money saver.

@News Wizard also supports date-selective mailing.You can define a certain date range for your mailings. That means that you can choose a group of subscribers who have subscribed during a certain period of time to send your newsletter to. This is useful when you want to reach subscribers (e.g. for a special offer) depending on how long somebody has already been your customer.

As a registered user, you may alter or modify the @News Wizard Software as far as the
HTML output is concerned. Further modification of the script code require the notification of the author (Just drop us a short note at scripting@ulices.com)
You cannot give anyone else permission to modify the @News Wizard Software.
 
You are strictly prohibited from distributing copies of this software without prior permission.
You are specifically prohibited from charging, or requesting donations, for any copies, however made, and from distributing the software and/or documentation with other products (commercial or otherwise) without prior written permission !

The file 'upload.cgi' is Copyright (C) 1996 Jeffrey D. Carnahan and has been delivered to you free of charge and does not constitute a part of this commercial product.

DISCLAIMER OF WARRANTY
This software, the information, code and/or executables as well as the accompanying files provided are provided "as is" without warranty of any kind, either expressed or implied, including but not limited to the implied warranties of merchantability and fitness for a particular purpose.
In no event shall the author or seller be liable for any damages whatsoever inlcuding direct, indirect, incidental, consequential, loss of data, loss of business profits or special damages, even if the author or seller has been advised of the possibility of such damages.

Good data processing procedure dictates that any program be thoroughly tested with non-critical data before relying on it.
The user must assume the entire risk of using the program.