Smart tip: This handbook is also designed to be printed... set your printer's page orientation to landscape format, so there is enough space to place hand-written notes on the left and right margin easily.
 

In a common environment, we recommend to create a new sub-directory within the existing "cgi-bin" folder to separate the software from other already installed products.

Required "template.en" directory:

Inside the directory you desired for installation, please create a new sub-directory called "template.en". It's used to hold the content of "template.en" directory delivered with your software package.

Required "data" directory:

Inside the directory you desired for installation, please create a new sub-directory called "data". It's used to hold the content of "data" directory delivered with your software package.

Adjust path to Perl:

Open all program files (*.pl and *.cgi) in a text editor and change the first line "#!/usr/bin/perl" that it reflects the correct path to Perl 5 (or higher version) on your system. This is required to let your server know where the Perl interpreter is located.

Usage note: On most systems, /usr/bin/perl is already the default path to Perl and so no modifications are required.
 

Detailed file table: Scheme: [filename | suggested place to upload (short description); file permission]:
 

Filename...	Description...	Filename...	Description...
*	cgi-bin (program & data files); 755	template.en/*	template.en (templates); 666
		data/*	data (basic data files); 666

Important notes: Please double-check file permissions and transfer mode, otherwise the software may not work as intended. Depending upon the server configuration, different file permissions than the ones stated above may be necessary.

Smart tip: Our installation helper install.cgi makes it easier... just call it from your web browsing software (requires correct installation of this script) and it automatically checks your entire installation, adjusts permissions and fixes typical errors.
 

Before you proceed, it is highly recommended to set an administration password. After this is done, access to the admin panel is granted only by using "admin" as login together with the chosen password.

Now click on the button "Edit system parameters" and configure the shown parameters according your needs.

Usage note: Since all parameters are automatically filled with correct values, modifications on your side may not be required.

Directories and files:
 

Name of parameter to set...	Description...
CGI files directory Example: /usr/www/cgi-bin/ms	Absolute path to the location of MailingStar on your server.
"binarydata" directory * Example: /usr/www/cgi-bin/ms/bindata	Absolute path to the location that holds binary database content.

* Technical note: The software tries to create this directory at a web-accessible place (certain cgi-bin locations doesn't allow to deliver multimedia content). If you experience problems in content delivery, please move it manually to a suited location.

Platform specific settings:
 

Name of parameter to set...	Description...
Mailing program (for Unix only) Example: /usr/bin/sendmail	Absolute path to Sendmail (or compatible) application on your server.
SMTP server Example: smtp.sunnyscript.com	SMTP server for handling mails; when left blank, the default mail application is used. This setting is required for non-Unix systems, otherwise optional.
Don't use flock Example: Unchecked	"flock" is normally supported directly by the operating system; should it be unavailable for any reason (e.g. on Win9x, WinMe), mark this checkbox.
Don't use fork Example: Unchecked	"fork" is normally supported directly by the operating system; should it be unavailable for any reason, mark this checkbox.
Forked process respawn interval (seconds) Example: 60	Respawn interval for processes; recommended range: 30 to 60 seconds.
Admin e-mail address Example: admin@sunnycript.com	E-mail address of the system administrator (e.g. webmaster).

URLs:
 

Name of parameter to set...	Description...
Binary directory URL Example: http://www.sunnyscript.com/cgi-bin/ms/bindata	URL to the location that holds binary database content.
URL of CGI files directory Example: http://www.sunnyscript.com/cgi-bin/ms	URL to the location of MailingStar on your server.
URL of user's help document (optional) Example: http://www.sunnyscript.com/myhelp.htm	URL to an optional help document (not included); may also consist of an e-mail link (e.g. "mailto:support@sunnyscript.com").

Various parameters:
 

Name of parameter to set...	Description...
Authentication time (in seconds) Example: 10800	Time frame keeping user authentications active (after expiration, people must log in again); recommended range: 1 to 12 hours.

After you have verified all settings carefully, click on the button "Save parameters" to take over modifications to the system. It is also possible to bring back previous values with the "Let the script restore defaults" button.
 

Sending regular newsletters to existing and prospective clients will bind them to your company and product labels. In this way, people have always up-to-date product and service information and remember to your business for their next buying decisions.

Newsletters are also suited to improve internal communication streams within companies, e.g. by publishing a regular business mailing keeping employees informed about latest developments.

Is there anything I have to take care for newsletters ?

Never send too many mailings; your newsletter should stand out and it surely doesn't when reached daily; it mainly depends upon your product range and company structure. In short: High product (or customer) fluctuation -> more mailings.

It is very important to do mailings regularly and in an "eye-catching" way. And it's also recommended to use always the same content structure (headers and footers) as well as a clear, understandable layout (e.g. table of contents, strong headlines).

Another point is the used style of writing: This mainly depends upon your target group and customer structure ("Hey folks, we have new cool stuff to check out" may not work for conservative business people).

No one will read a mailing containing tons of text; take care to summarize long text blocks to short ones and provide links to your website where more detailed information should be available (use effectiveness tracking of MailingStar to log user activity).

If you are unsure about the layout of your newsletter, why not checking your competitor ones ? Of course, they also don't have invented "the solution", but sometimes doing so is a source of inspiration for own ideas.

And (probably most important) ask yourself whether you would like receiving your own newsletters or just find them boring.

How to attract people signing-up for my newsletters ?

The easiest way is to collect e-mail addresses from your customers (if you are unsure, you may invite them to join your mailing list instead of doing subscriptions without their knowledge).

Also don't miss to add the possibility to subscribe directly on your website. MailingStar can be easily integrated into an existing website keeping your original layout by using simple HTML forms - this will attract surely many people to join.

MailingStar plus offers the feature to import address lists and to grab new e-mail addresses from websites being invited or added directly to mailing lists (please refer to the chapter "Helpful hints and technical reference" for legal notes).

How to make my newsletter more interesting ?

Well, the possibilities are endless and mainly depend upon the type of your business and target groups. But it is a good idea to offer some kind of discounts for products / services exclusively for subscribers (e.g. buy one, get one free).

And why not allow a "view behind the scenes" by showing how your products are made or providing related news and business information. You can also build a series ("Next time we tell you more about..."), which makes your newsletter being an event.
 

A mailing list is used to group people with same interests and comes with its own mail settings and preferences; mailings can be sent either to one single list or multiple mailing lists at once.

What is the subscriber lounge ?

The subscriber lounge provides an interactive platform for your existing subscribers (members of mailing lists) to check and edit their current subscriptions, change their profile data and much more.

Additionally, the subscriber lounge is also the right place for people who are interested in your mailing lists. They just need to register first and can then join any of them. The registration procedure may be moderated, depending upon your settings.

For subscriptions accepted directly from websites, MailingStar provides a "quick subscription" feature without prior registration (in this way, a standard profile is created automatically).

What is a profile and does each subscriber need one ?

Yes, it is necessary. Each profile contains all information about the concerned subscriber (like the e-mail address, subscribed lists, language preferences as well as additional personal data).

Opt-in, opt-out, permission marketing - what in postage stamp's name is this ?

MailingStar uses a special opt-in verification scheme to prevent that anyone else than the original e-mail address owner can subscribe to your mailing lists by requiring a separate confirmation.

And once an e-mail address is subscribed, its owner should have the chance to unsubscribe again (opt-out) either by managing the concerned subscription profile online or clicking at a special link within received mailings.

Permission marketing summarizes both: People subscribed to your mailing lists are aware about this fact (opt-in) and able to unsubscribe at any time (opt-out). This is a legal requirement in many countries, fulfilled by MailingStar in all aspects.

By the way: You can freely decide by yourself how (and if overall) to use opt-in/opt-out methods. Please refer to the following chapters for more detailed information.
 

How to access the subscriber lounge (registered members area, user registrations):
 

The top menu line provides additional selections (depending on the current system status):
 

General settings:
 

Leads logging settings:
 

Security settings:
 

* Usage note: An unsubscription confirmation for people managing their accounts via the subscriber lounge is not required, because unsubscriptions can be only made after specifying the correct password (moderate such profile changes instead of).

Invitation mailing default settings:

Invitations are suited to ask users to become members of your mailing lists (please refer to the next chapter for details).
 

Subscription manager layout:

By modifying these settings, you can take influence to the top menu line shown within the subscriber lounge.
 

Data maintenance:

Each time data maintenance runs, the following actions are performed:
 

* Delete expired log entries and history records. * Handle undeliverable messages and maintain profiles. * Perform scheduled mailing jobs and do automatic mailings.

Important note: Executing data maintenance is required and needs "fork" function to be enabled (see "System parameters"). If it is disabled due to technical limitations of the server, please follow instructions below.
 

Data maintenance with disabled "fork" function:

Schedule the file cron_run.pl (the file is located in the software directory of MailingStar) to be ran regularly by your server (recommended scheduling: each hour). You may use Cron or your server's scheduling tool in order to manage this task.

Technical note: Even when starting data maintenance in this way, ensure to fill in the parameters above.

By the way: If you are new at scheduling server actions, please contact your webhoster for details or refer to available literature. Alternatively you may use the Cron editor we provide (call cron_edt.pl from the command line, e.g. "perl5 cron_edt.pl").

Data maintenance - auto-blocking of invalid e-mail addresses:

This feature is explained in the chapter "Advanced features in detail".

Automatic mailings:

This feature is explained at the part "Automatic mailings".
 

MailingStar is able to handle a primary and secondary language preference for each profile. So you can provide information in different languages automatically sent to the correct recipients.

Depending upon their language settings, MailingStar decides which subscribers of a particular list will receive your mailing; in this way, one list can host profiles with individual language preferences.

We have prepared a list of commonly used languages you may modify, delete or expand according your needs. Our system supports as many natural and artificial languages as you like.

How to create a new language entry:

Type in the abbreviation of the new language (e.g. "KL" for Klingon) and click on the button "Create new". Also add this code to the "Selectable languages" parameter (above on the same screen) to make the concerned language available for selection.

How to edit / remove a language entry:

Select the language from the list, click on "Delete" or "Edit" and follow the provided instructions.

Usage note: Instead of removing a temporarily unwished language completely from the system, use the parameter "Selectable languages" within "General settings" (see previous part of this chapter).

How to change the sorting of languages:

Select the one you wish to move around and click on either "Move up" or "Move down" button to change its position (this affects the language's position within the subscriber lounge).

How to disable language feature:

Either delete all languages from "Selectable languages" within "General settings" part (recommended way) or remove the fields primary_lang and secondary_lang from the table of registered users (be careful when doing so).
 

Charset settings:
 

Charset conversion:

You can perform character conversion for each language: Characters represented by hexadecimal codes (source) are converted into others also specified as hexadecimal values (target).
 

This database contains information about all mailing lists currently available. Each mailing list can have individual settings to control its behavior, so you are able to manage completely different lists with one software installation.

Add a new mailing list:

Click on "View/Add/Update/Delete lists" when you are in the main admin menu to see all existing lists. Now click on "Add" in the upper right corner of the screen.

Usage note: Most of these parameters are pre-defined with standard values for your convenience.
 

* These default parameters can be individually modified for each mailing job (see next parts of this chapter). Values here are used as standard ones for time-saving purposes.

Edit or remove a mailing list:

Click on "View/Add/Update/Delete lists" when you are in the main admin menu. You see all mailing lists currently available.

Now search for the desired list and click on a linked column (e.g. list name) and select "Edit" or "Delete" shown on the upper right corner of the screen. Just follow the instructions appearing now.

Important note: Once a list is removed, it cannot be recovered - so please be careful.

Technical note: Profiles are automatically updated in the case of list modifications and removements.

Show subscribers of a mailing list:

When browsing through the mailing lists, click on "subscribers" at the column "List ID" to see all subscribers currently available on a particular list. You can then view a profile more closer for being edited or removed.
 

This database contains all subscriber profiles currently existing on the system.

A profile is created for each e-mail address subscribed to mailing lists via the subscriber lounge. For quick subscriptions and imported addresses, a standard profile is established automatically by the system.

All fields used within this table can be included in registration & update forms on the subscriber lounge to request custom info from your users (doesn't require any template modifications (except mail templates), since pages are dynamically generated).

Helpful hint: Add custom fields to request personal information from your subscribers; use as many fields as you like (all field types like input boxes, drop-down lists and radiobuttons are supported).

Add, update and remove profiles:

You can add new subscriber profiles, update and remove existing ones (e.g. at user request) through the admin panel:

Please click on "View/Add/Update/Delete users" when you are in the main admin menu.

Click on "Add" (upper right corner of screen) to create a new profile or search for the desired profile you wish to edit or remove, click on a linked column (e.g. first name) and then select "Edit" or "Delete" from the upper right corner of the screen.

Helpful hint: Alternatively use the "Quick add" link located at the main admin menu to go directly to the addition form.

Default requested settings for creating a new profile:
 

The update screen looks similar; additionally it shows the date stamps of profile creation and last update as well as affiliate information (if YourAffiliates or a compatible application is configured for MailingStar).

Quick subscriptions, imported addresses and the subscriber lounge:

Profiles created by quick subscriptions and import actions are normally not intended to use the subscriber lounge. However for each record a randomly chosen password is set automatically:

In this way, it is possible for such subscribers to use the password reminder to receive their passwords to the registered e-mail address (then they are able to use the subscriber lounge instantly keeping security for this type of subscriptions).
 

Here is the heart of MailingStar - the ability to prepare mailing jobs as well as to schedule and execute them in various ways.

Invitations are similar to mailing jobs, however scanner output files or external address databases are used to invite people joining your mailing lists (e.g. through the subscriber lounge or via quick subscriptions).

Click on "Mailing and invitation manager" available on main admin menu. Alternatively you can click on "Job manager" on the upper left corner of the screen (where available). The following actions are available for existing jobs:
 

Technical note: Theoretically it is possible to run more than one job at a time. However since this may slow down the server dramatically, MailingStar will execute jobs sequentially (one job per time) and puts waiting jobs into a queue.

Add a new mailing job:

Select a mailing list (used to take over default settings) and then click on the button "Add mailing job" at the bottom of mailing list jobs. Now you can specify all parameters for a new job.
 

If all settings are done, click on the button "Process mailing" to save the job or preview the mailing first.

Sample message in TEXT format (with personalized elements):
 

Dear <!--$first_name--> <!--$last_name-->, you recently added your website <!--$URL--> to our database. If you would like to increase the popularity of your <!--$BUSINESSTYPE--> company, you should take a closer look at our valuable offers ! With kind regards, John Smith (my sample company).

Intelligent mail content delivery:

The most powerful feature is the delivery of intelligent message parts based on a record's content and "if/then/else" conditions. So a mailing can be written absolutely targeted, which leads to higher response rates and increased user convenience.

Important note: This works only with "Personalized" mailing method. "Quick" mailings will ignore intelligent message parts.

Each "intelligent message part" has the following structure:
 

<!--if <expression>--> Message delivered when <expression> is true. <!--else--> Message delivered when <expression> is false. <!--endif-->

Usage notes: "if" and "endif" tags are required, while the "else" part is optional. Recurrent tags may also be used.

<expression> can contain these operators:
 

Format of field values: $fieldname (field names are handled case-sensitive).

Sample applications (non-recurrent tags):
 

<!--if $gender eq "m"--> Ties for 5 Euro only. Just a limited time, buy now ! <!--else--> Parfums starting at 10 Euro. <!--endif--> <!--if $income < 20000 AND $intelligence_quotient <= 30--> Hi <$name>, participate in our "get rich fast" special offers ! This is your chance to live like the <rich & beautiful>. <b><i>So start acting now - start today.</b></i> <!--endif--> <!--if $index * 10 / $basetax + 0.03 == 2 AND $taxstatus eq "high"--> Save taxes by ordering our book "1001 (il)legal tax tricks". <!--else--> Increase your income by ordering our book "1001 ways to get wealthy". <!--endif-->

Usage notes: Second sample does not have an "else" tag, which means that a false result will lead into not displaying anything. Should a field value be unavailable (spelling error, non-existing field), then the argument is considered as being empty.

Technical note: It is also possible to use HTML and client-sided scripts (like JavaScript) within intelligent message parts.

Sample application (recurrent tags):
 

<!--if $gender eq "m"--> Special offer for <b>men</b> from our drug store: <!--if $age > 50--> Gray hair remover for just 9,99 Euro. <!--else--> Shaving foam - just 3,99 Euro. <!--endif--> <!--else--> Special offer for <b>women</b> from our drug store: <!--if $age > 50--> Wrinkle remover for just 9,99 Euro. <!--else--> Lavender bath salt - just 3,99 Euro. <!--endif--> <!--endif-->

Usage notes: Parts in green text belonging together. Do not forget to close all "if" tags avoiding malfunctions.

How to perform a test of personal and intelligent mailings:

In order to let the system process a sample message, click on the button "Send test message to admin". The system then generates a mailing, which is sent to the administrator under real life conditions.

And these default values are used: Numerical = 0; date/time related fields = actual date/time; URLs = http://test.<fieldname>/; e-mail addresses = test@<fieldname>.test; fields in general = test-<fieldname>.

Add a new invitation job:

Click on the button "Add invitation job" at the bottom of the invitation job list. Now you can specify all parameters for a new job.
 

If all settings are done, click on the button "Add job" to save the job or preview the mailing first. Now you can start the job at the job manager screen (see above within this chapter for details).

Advanced invitation possibilities:

The invitation feature is intended to allow interested people creating a profile by using the subscriber lounge.

However it is a matter of course that you can also forward them to any other destination, like your website containing a quick subscription form or to a page with more information about your company.

In this way, invitations can be made for an individual mailing list or just to welcome people to visit your website.
 

Another great feature of MailingStar is the ability to send mailings automatically to each new user. This way is especially suited for any kind of periodicals, like online learning courses.

Automatic mailings are handled apart from mailing lists, so it is not necessary to set up one for this purpose. People are just required to create own profiles at the subscriber lounge in order to receive automatic mailings.

Important note: Automailings are sent to each new subscriber. So if you wish to manage additional mailing lists without this feature, it is necessary to make two installations of MailingStar (you are required to buy another license for this purpose).

Pre-requisite for automatic mailings:

Maintenance interval: Ensure that a maintenance interval is specified. Please see screen "Table parameters", "Table automatic maintenance". Recommended range: 3600 to 43200 seconds (1 to 12 hours).

How to add an automatic mailing:

Click on the button "Edit MailingStar parameters" when you're in the admin menu and go to the section "Automatic mailings". Type in the name of the automatic mailing entry (e.g. "First lesson") and click on the button "Create new".

At the following screen, specify the mailing's content; please refer to "Add a new mailing job" for details.
 

If all settings are done, click on the button "Save parameters" to finally set up the automatic mailing.

By the way: Automatic mailings also supporting personalized mails (filled with data from registered users table) as well as intelligent mail content delivery. For more details, please refer to the part "Mailing and invitation manager".

How to edit / remove an automatic mailing:

Select the mailing from the list, click on "Delete" or "Edit" and follow the provided instructions.

How to change the sorting of automatic mailings:

Look for the one you wish to move around and click on either "move up" or "move down" to change its position in the list.
 

The system tables contain system related data, like subscriber profiles, mailing list settings, archived mailings, history info for list changes and effectiveness tracking. All system tables can be searched and modified according their specific applications.

You can access the system tables from the main admin menu. For each table, different selections are available.

Usage note: All modifications made to these tables take immediately effect to the subscriber lounge. Since most of these actions cannot be recovered, please be careful when altering data.

Table of registered users:

Please refer to the chapter "Mailing list management" for a close description of this table.

Moderate user actions:

If you have set permissions to moderate new profile creations (subscriptions) or changes in profiles (e.g. unsubscriptions or modifications), you can use the link "Moderate user actions" to approve or decline modification requests made by subscribers.

Technical note: Quick (un-)subscriptions cannot be moderated (use the security settings instead of).

Technical note: If you wish to modify records that are currently in moderation queue, mark the button "Remind to update" when approving these records. On the moderation result screen, you