Jax Newsletter v2.1
Manual
Basics
Sign in- / Sign out
Application and integration of the scripts
Manual Administration of mailinglists
Posting Newsletters
Important Security
Notes
How to change colors and fonts?
How to define the sender address?
How to manage multiple mailinglists with
same script?
How to store more user information?
How to change file access permissions on
webserver?
How to define what user data are
required?
How to switch of national
flags in sign in form?
How
many entries Jax Newsletter can handle?
How to help to support this project?
Where to get informations about Updates and
Changes
| Projekt: | Jax Newsletter (Online Mailinglist Management) | |
| Version: | 2.1 | |
| Interpreter: | PHP 4.3+ | |
| Code: | Andreas John | |
| Design: | Andreas John | |
| Homepage: | www.jtr.de/scripting/php/newsletter/ | |
| Lizenz: |
Copyright (C) 2001-2004, Andreas John [ Jack (tR) ] This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version. A copy of this license you can find
in the added text file gpl.txt or on the website of the Free Software
Foundation under: http://www.fsf.org/copyleft/gpl.html Please note, that I can give NO WARRANTY FOR DAMAGES CAUSED BY DIRECT OR INDIRECT USE OF THE PROGRAM... |
I want to say a very big Thank You to all people who support this and many other Open Source projects by their hints, translations, affectionate adaptions and links on their websites...
My personal credits go to:
| Andrej | |
| Edward Brüheim | http://www.bruheim.net |
| Giovanni Scopel | |
| Jan-Ruben van Schie | http://www.jrwebdsign.nl |
| Hardy Hünteler | |
| [KB]BuzzDee | http://www.buzzee.de.vu |
| Liesel Knorr | |
| Manfred Stumpf | |
| Martin Sondermann | http://www.kunstphotografie.de |
| Michal Letko | |
| Mr Who | http://www.mrwho.homeip.net |
| Pawel Wagner | http://www.gry.skokinarciarskie.com |
| Richard Heyes | http://www.phpguru.org |
| Roland Freimüller | http://www.top-solution.at |
| Sabine Trautmann | |
| Susanne Müller | http://www.netz-konzept.de |
| Tamas Herczeg | http://www.soft-trans.hu |
| Thomas Bjørnseth | http://www.bjornseth.net |
| Wojciech Dorosz | http://www.serwisy.net |
| Wolfgang Liehr | |
| InteractiveTools.com (resp. developers of HTMLarea) |
Jax Newsletter is an online malinglist management system that enables you to administer mailinglists (Mailinglist Manager) and to send mails (Newsletters) to the recipients.
The mailinglist administration process is completely automated. Visitors can sign in our sign out from mailinglist using a form on your website.
A working demo version of Jax Newsletter you find under: http://www.jtr.de/scripting/php/newsletter/newsletter/index.php
Jax Newsletter comes along with typical features of an online mailinglist managment system. Additionally it brings some special features. Particularly worth mentioning is the very flexible support of multiple data sources. This makes it possible to use the Newsletter system both - with a simple text file and a mySQL database system.
Following you find a summary of all important features of Jax Newsletter:
Jax Newsletter was written in PHP 4, a server-side programming language that produces dynamical generated web pages! (If unsure, ask your web space provider for PHP support!)
Jax Newsletter is able to save data into both, simple text files and into a mySQL-data base system - that means Jax Newsletter also works without mySQL-database-connection!
Jax Newsletter and its components are published under the conditions of the
GPL - General Public License in der
This license allows you to use and copy this software freely and to develop improvements. Furthermore you are bound not to touch the copyright notes resp. to set a link to the original script (http://www.jtr.de/scripting/php/newsletter)!
Jax Newsletter contains the module htmlArea and HTMLMimeMail which are published under a BSD-like license. (consider that separately!)
Jax Newsletter was written in PHP 4, a server-side programming language that produces dynamical generated web pages! (If unsure, ask your web space provider for PHP support!)
Jax Newsletter is able to save data into both simple text files (csv files) and into a mySQL-data base system - that means Jax Newsletter also works without mySQL-database-connection!
If you already have PHP support please do the following:
Jax Newsletter was designed to be able to save data to both - simple text files and mySQL database tables. Running a big mailinglist with many thousands of entries mySQL is expected to give you a better performance...
If you have mySQL support please do the following:
$data_source = "mysql"
$db_server = "mysqlserver2.mydomain.tld";
$db_login = "user152";
$db_database = "my_db";
$db_password = "hummel";
*table names have to be identically with these one in globals.inc.phpCREATE TABLE jnl_groups (
id int(11) NOT NULL auto_increment,
ml_id varchar(10) NOT NULL default '',
title varchar(128) NOT NULL default '',
grp_name varchar(128) NOT NULL default '',
subscribers int(11) NOT NULL default '0',
languages varchar(255) NOT NULL default '',
css varchar(128) NOT NULL default '',
archive varchar(128) NOT NULL default '',
sign_in_page varchar(128) NOT NULL default '',
sign_out_page varchar(128) NOT NULL default '',
validation_page varchar(128) NOT NULL default '',
senders varchar(128) NOT NULL default '',
PRIMARY KEY (id)
) TYPE=MyISAM;
CREATE TABLE jnl_queue (
id int(11) NOT NULL auto_increment,
start_time int(16) NOT NULL default '0',
xid VARCHAR(32) NOT NULL default '0',
groups varchar(255) NOT NULL default '',
archive_entry int(1) NOT NULL default '0', mail_subject varchar(128) NOT NULL default '',
PRIMARY KEY (id)
) TYPE=MyISAM;CREATE TABLE jnl_recipients (
id int(11) NOT NULL auto_increment,
email varchar(128) NOT NULL default '',
hash varchar(32) NOT NULL default '',
mail_format char(1) NOT NULL default '',
gender char(1) NOT NULL default '',
nick varchar(64) NOT NULL default '',
mode varchar(4) NOT NULL default '',
groups varchar(255) NOT NULL default '',
PRIMARY KEY (id)
) TYPE=MyISAM;CREATE TABLE jnl_records (
id int(11) NOT NULL auto_increment,
action varchar(4) NOT NULL default '',
time varchar(32) NOT NULL default '',
ip varchar(10) NOT NULL default '',
email varchar(255) NOT NULL default '',
hash varchar(32) NOT NULL default '',
mail_format char(1) NOT NULL default '',
gender char(1) NOT NULL default '',
nick varchar(64) NOT NULL default '',
mode varchar(4) NOT NULL default '',
groups varchar(255) NOT NULL default '',
age varchar(4) NOT NULL default '',
profession varchar(64) NOT NULL default '',
nationality varchar(32) NOT NULL default '',
PRIMARY KEY (id)
) TYPE=MyISAM;CREATE TABLE jnl_subscribers (
id int(11) NOT NULL auto_increment,
date varchar(16) NOT NULL default '',
email varchar(128) NOT NULL default '',
hash varchar(32) NOT NULL default '',
mail_format char(1) NOT NULL default '',
gender char(1) NOT NULL default '',
nick varchar(64) NOT NULL default '',
groups varchar(255) NOT NULL default '',
PRIMARY KEY (id)
) TYPE=MyISAM;CREATE TABLE jnl_archive_eng (
id int(11) NOT NULL auto_increment,
timestamp int(16) NOT NULL default '0',
xid varchar(16) NOT NULL default '',
mail_subject varchar(255) NOT NULL default '',
PRIMARY KEY (id)
) TYPE=MyISAM;
CREATE TABLE jnl_archive_ger (
id int(11) NOT NULL auto_increment,
timestamp int(16) NOT NULL default '0',
xid varchar(16) NOT NULL default '',
mail_subject varchar(255) NOT NULL default '',
PRIMARY KEY (id)
) TYPE=MyISAM
INSERT INTO jnl_groups VALUES (1, '00', 'Jax Newsletter', 'German', 1, 'de', 'default.css', 'jnl_archive_ger', 'sign_in.php', 'sign_out.php', 'validate.php', '<Postmeister> postmaster@%!this_domain!%');
Jax Newsletter consists of four parts:
1. Scripts for automated sign in/out of recipients:
The scripts index.php, sign_in.php, sign_out.php and validate.php are for demonstration purporses only. They demonstrate how to include the corresponding .inc.php-modules from directory forms..
All scripts of Jax Newsletter (inclusively admin scripts) obey the following call scheme:
http://..../index.php?ml_id=01&language=English
ml_id
tells the script what mailinglist/recipients group to use! You can use the admin
program to create as many mailinglists as you want. For every ml_id
key the script requires an entry in group list file mailinglists/jnl_groups
. ml_id can be any alphanumerical value
(letters-number-combinations as well).
language
defines what language to use for system and status messages of the newsletter
system. For any selected language there has to be a template file in directory
languages! Otherwise the default language (defined
in newsletter.settings.inc.php) is selected automatically.
2. Viewer script for archived news
Additionally to the sign in/out scripts there is the script archive.php, giving you an index of all posted and archived newsletters. This is also only an example file demonstrating how to include modules/archive.inc.php
3. Administration scripts
This block contains all scripts behind the script admin/index.php, excepted the script mailservice.php.
navigation.php is the administration menu (requires
JavaScript!!!)
list.admin.php serves for displaying and deletion of mailinglist entries.
groups.admin.php allows you to Create, Modify or Delete Mailinglists.
posting.php is the send form for newsletters.
archive.admin.php supports you deleting entries from newsletter archiv.
admin.php helps you to change entries in
newsletter.settings.inc.php..
4. scripts for sending email
The script mailservice.php is for time triggered sending of e-mails. It takes the emails from send form posting.php and puts it into a mail queue. Later it sends the mails to the recipients on specified time respectively on next possible time.
If someone signs in or out from mailinglist the entered data is saved in a log file (by default the file jnl_records) Additionally a pseudo-random key is generated and saved together with e-mail address to the file jnl_subscribers.
To make sure nobody enters or removes someone else's email-address from the list the real "owner" of the e-mail address receives a confirmation mail by the script sign_in.php. This e-mail contains a hyperlink to the script valitate.php. The recipient has to click on this link to confirm sign in to or sign out from mailinglist.
Example:
http://.../newsletter/validate.php?ml_id=0&do=sign&uid=3et60c4i45....
do
says if user signs in or out
uid
contains the key generated by sign_in.php. The
script validate.php compares this key with the
key stored in file jnl_subscribers. If identically
the entry is moved from jnl_subscribers to the
mailinglist file jnl_recipients...
The scripts can be linked as described above. You can use your own sign in/out forms, but you have to make sure that there is at least the form field "email". The program index.php is another demonstration page that shows how to integrate a combined sign in/out form directly into your website. If entered email it leads to the seperated and more detailed forms sign_in.php and sign_out.php.
For administration of the mailinglists there are a bundle of administration scripts you can call via the script index.php in directory admin. Please remember to protect this directory via passwort protection! The language of the administration program you can set as usually via parameter language:
http://.../admin/index.php?language=English
To send a mail to the list call the script admin/posting.php (or better use the links in section posting in administration system). Choose the recipients group, type your message and press send.
Important:
To make sure all messages are sent, you have to keep "open" the
browser connection. You may not close the browser window or press close button
before you get a confirmation that all e-mails have been sent! If the connection
breaks the email is kept in mailqueue and you can resume sending the remaining
messages from the point of break...
Jax Newsletter has no active password protection! So you have to make sure that nobody but you has access to the admin scripts (admin/index.php) directory. Usually you can do this by setting directory protection using your webspace configuration frontend!
If you are using Jax Newsletter in CSV mode you should disable the Automatic Directory Index of your webserver and rename your .csv-files so that visitors are not able to look into your protocol and mailinglist files! This problem does not occur in MySQL mode!
To change outer appearance there are some predefined CSS stylesheets in directory css. You can change them using a simple texteditor.
By default the sender's address is set to postmaster@ihredomain.tld. If you want to change it manually then you have to modify newsletter.settings.inc.php
$newsletter_admin_email = "postmaster@".$SERVER_NAME;
e.g. to:
$newsletter_admin_email = "jack@jtr.de";
Additionally you can define an email address for each mailinglist using the group admin tool (Mailinglists/Overview)
Data structure for Jax Newsletter version 2.0 has been completely redesigned and now the script supports multiple mailinglists by default.
Simply create a new mailinglist using the administration program "Mailinglists/Create". If you want to use your own sign in scripts based on include files in /forms-directory, make sure you enter the name of your scripts under "Sign in page", "Sign out page" and "Validation page".
By default Jax Newsletter saves the e-mail-Address and IP-Address and the content of the form fields profession, age and nationality as given in sign_in.php.
If you want the script to store additional data (e.g. birthday of the signer's kitchen ;-) simply choose the following lines in validation.inc.php:
if ( $log_signings )
{
$log = array();
$log[ "action" ] = "+";
$log[ "time" ] = $time_now;
$log[ "ip" ] = $REMOTE_ADDR;
$log[ "email" ] = $email;
$log[ "profession" ] = $profession;
$log[ "age" ] = $age;
$log[ "nationality" ] = $nationality;
$log[ "kitties_birthday" ] = $kitties_birthday;
$logbook->append( $log );
}
After this you have either to kill the .CSV-file for logging (jnl_records) - then the script generates automatically a new head at next call - or (if you want to keep your current data) you simply expand the first line with the name of the variables:
"action","time","ip","email","profession","age","nationality","kitties_birthday" "+","2002-03-03 21:14:47","127.0.0.1","jack@jtr.de","Webmaster","1978","Deutsch"
If you use a MySQL-database, you have to enhance the table for the logs:
ALTER TABLE `jnl_records` ADD `kitties_birthday` VARCHAR(30) NOT NULL;
Important Hint:
If you extend Jax Newsletter to register more data from your signers, please
observe local and global laws of civil data protection.
In Germany (and European Union) for example there are some laws to protect the citizens against the data-greediness of people running (most often commercial) websites to trade with personal data.
You should always observe the principle of registering only user data which are absolutely nescessary for running the service. Not nescessary for running a mailing list are data which let you draw conclusions from of the person itself (e.g. confession, sexuality, health state and so on...)
Statistical data (like topics of interest, profession, and age) are perhaps important to fit the newsletter to your customers without touching their personality. To avoid trouble with data protection laws you should keep back and decide thoroughfully what's important and what's not...
There are some special controls at the end of the Basis Settings form [Basic Settings/Change]. Using this controls you can define what inputs have to be displayed in sign in form and whether this data fields are required or optional. If you select an input field as "required" you force the user to enter additional data.
By default Jax Newsletter shows a flag for each language in sign in form.
On special (German) wish I had to change this feature to be optional. If you want to avoid national signs (e.g. as you have only one list, and think the flag symbol in this case is a little bit too "proud"! ;-) change variable
$show_national_flags = false;
in newsletter.settings.inc.php.
If your webserver runs on Unix (Apache) you have to use the Unix command chmod to change the file access permissions. (How to do this conveniently using your FTP client is described below)
Syntax of chmod is:
chmod rwxrwxrwx
filename
r = read
w = write
x = execute
The command expects three 3-digit tupels representing the access permissions
for the single "groups" : [rwx][rwx][rwx]
The groups: (from right to left)
all users
all users in same group as owner
owner only
in binary notation:
chmod [rwx][rwx][rwx]
is equivalent to
chmod [111][111][111]
resp. in hex notation with
chmod [7][7][7]
thats all - here you have the chmod command to allow "all" access
to files:
chmod 777 jnl_recipients
(the required access permissions depend on webservers configuration. If you
are suspiciously and do not want to give script all access (777), try to increase
rights step by step until the script works!)
Most FTP clients, as WS-FTP
support chmod-command conveniently from their user interface. Using WS-FTP
you only have to click with right mouse button on a file (in remote window)
and then you have to klick on chmod and so on...
Currently I am running the Newsletter system on one of my websites with more than 5100 emails in CSV mode. Theoretically the script is able to handle several 1000 entries (depending on your webservers capacity and data source). For running larger mailinglists mySQL is recommended...
Jax Newsletter saves only one entry, resp. it always shows the same
entry!
You probably have not set up the database using the sql dump (in admin-directory)
and forgot to create the field "id" (very important!!)
I am using Lycos as Internet Provider. If a user signs into the newsletter he gets the mail containing the activation link. But the link is leading to an invalid page...How to solve it?
On Lycos-Webspace sometimes the PHP-variable $SCRIPT_NAME is not set correctly. In this case you have to change the line (377 ?) in validation.inc.php from
$script_url = "http://" . $SERVER_NAME . implode("/",$script_path_dummy ) . '/' ;
to the correct URL:
$script_url = "http://members.lycos.de/fuzzy/newsletter/";
If the data stream to the browser is interrupted during the sending process (e.g. because of a Proxy-Timeout), the sending is broken and not all users receive the email. Sending to big mailinglists needs a lot of time.
I have no really solution for this at the moment, but I have coded a workaround (since v1.4) which saves the state of timeout so that you can resume the posting process later.
If you have found any errors or have questions or suggestions for improvement then please don't hesitate to contact me directly!
Berlin, 13 March 2004 - Jack (tR)