A better way to opt-in
by namesuppressed
coding by Kohan Ikin (aka SyneRyder)
web: http://www.namesuppressed.com/
email: support@namesuppressed.com
Before attempting to install the script, please ensure that you have the following system requirements:
Not sure if you have everything? Ask the administrator of your web server, they'll know how to check.
After you have tried this script to see if it suits your needs, you are encouraged to purchase it. You can do so from the WebScriber webpage using credit card, postal money order or cash. After purchasing you will receive an unlocking code that will disable the "unregistered" message that WebScriber puts at the bottom of emails it sends.
At the time of writing, version 1.0 costs $69.95 for a personal / single site license, and $149.95 for use on an unlimited number of sites (eg for web designers managing sites for many clients). Website developers working only for non-profit organisations need only pay the $69.95.
The fastest way to get started is to upload all the files in the archive into a new subdirectory of your server's cgi-bin, and edit the config.txt file as required. You can run the script by loading the email.php file in your web browser. The script will tell you when something is wrong and needs to be changed.
Be sure to upload the files into the correct directories! (You should preserve the directory structure of the files in the zip archive file.)
To upgrade from previous versions of WebScriber, you should first backup your config.txt file, and all the files in the logs, email and html directories. You should then replace the email.php file, and all the files in the classes directory. There are new settings in the new config.txt file, so you should replace the config.txt file and re-enter your settings.
It is not recommended that you attempt to upgrade from previous 0.1.x versions of WebScriber / wbSLM. Version 1.0.0 was rewritten so completely that the configuration files, log file formats and template tags have all changed. However, you may find it useful to make backups of your config.txt file and email/html template files for reference purposes.
If you need further assistance or would prefer to do things step by step, the following indepth instructions will help you.
WebScriber is different from many PHP scripts because it is designed to run in a web server's CGI-BIN directory. Although it will work in other directories if PHP Safe Mode is disabled, the CGI-BIN directory offers some extra security features.
Running the script from the CGI-BIN may require a small modification to the script, as it needs to be told where PHP is installed. To do this, you should now unzip the archive on your local machine where you can edit the files. Be sure to preserve the file directory structure!
Look at the email.php file now. The first line of this is called the
Shebang line, and tells the script where it can find PHP. By default
this is set to #!/usr/local/bin/php, but it may need to be
changed for your system. If you use a Linux/Unix web server, log into
it and type whereis php at the command line. It will
return the path to several files - look for one with /bin/ in the path -
that is what you should use on your Shebang line. Replace the
/usr/local/bin/php part with this path.
You will also need to find where the ezMLM binaries are stored on your
server. You can do this by typing whereis ezmlm at the
command line. This will likely give a response like
/usr/local/bin/ezmlm or /usr/local/ezmlm-idx/bin - take note of this, this is the Path
To Ezmlm.
If you are unable to log in to an account on your web server, your website administrator should be able to tell you the full path to PHP and the full path to ezMLM.
At this point, choose where you would like to install the main script on your webserver. You must install it into your cgi-bin directory, although it can be in a subdirectory of cgi-bin if you wish. This will be the location you call the script from in your web browser. I recommend installing the main script files into a subdirectory of your cgi-bin with a very short name, such as "lists".
Some people prefer to store log files and templates outside of the cgi-bin. In this case, you should create a non-public directory on your server to store these files. This should not be in your WWW directory!
If you have an account with FutureQuest, you should have access to a
directory called /big/dom/xexample/ where "example" is the
name of your domain. You could create a subdirectory here called
"protect", and a subdirectory within that called "webscriber".
This will be where you store your protected files.
If you prefer to keep your log files and templates in the cgi-bin, it is easiest to store them in subdirectories of the Main Script Directory.
Open the config.txt file in a text editor. Now we have to set some configuration variables. Change the SCRIPT_URL value to the URL of the Main Script Directory you chose above. Be sure to leave the "email.php" part at the end. Next, change the PATH_TO_EZMLM value to the Path To Ezmlm you found above.
Set the BASEDIRECTORY variable to be the Protected File Directory
you chose above, including the subdirectory you are storing your files
in - something like /big/dom/xexample/protect/webscriber/
or /big/dom/xexample/cgi-bin/lists/.
The list LIST_BASEDIR is slightly trickier - this is the directory where
your ezMLM mailing lists are stored (each in their own subdirectory). On
servers hosted by FutureQuest Inc, this is typically
/big/dom/xexample/username/ where example is your domain
and username is your username.
To send emails, WebScriber needs to know the name of the SMTP server it should send email to. This could be localhost, your domain name, mail.example.com, smtp.example.com or something completely different. If you're not sure which address to use you can ask your web site administrator or your ISP. The name of the SMTP server goes next to the SMTP_HOST_NAME variable.
Depending on how the mail server is set up, you may need to provide your SMTP_USERNAME and SMTP_PASSWORD. These are the username and password that you use to send and check email. You may also need to set the SMTP_REALM, which is usually your domain name. You only need to fill these values in if the script won't send email, but if you have problems and don't know the right values to use, ask your website administrator or your ISP.
If you're still having problems with the script not sending emails via SMTP, you can try setting SMTP_DEBUG=on and sending the debugging information that is displayed to your website administrator or another tech guru. If you've tried everything and it still won't work, you can set USE_BUILTIN_MAIL=on to use the default PHP mail system. This is more likely to work, but can cause problems on some servers when sending many emails at once - please use it only as a last resort.
For some tasks, a script password is required. Change the PASSWORD value to anything you like, however it must be a minimum of 6 characters long. For security reasons, you are not allowed to keep the "default" password.
Set the SENDER_NAME variable to the name of the person administering the mailing list - in many cases this will be your own name. You should also set the SENDER_EMAIL to a support address where you can receive questions from subscribers with problems.
Set DEBUG_MODE to off. This is used to log debugging information to a file that you can send to namesuppressed support. However it can fill up very quickly, so you should turn this off unless required. Similarly, you should leave TESTING_MODE set to off, as this prevents all emails from being sent out.
SINGLE_OPT_OUT allows subscribers to unsubscribe from a list without having to confirm the unsubscription action. You should leave this turned on to prevent complaints - people who are unsubscribing want to do it as quickly and easily as possible. In some cases they may not have access to their email accounts anymore, so they couldn't click the confirmation emails anymore. Turning this off will prevent others from unsubscribing people without their permission, though.
You can use the BANNED_DOMAINS and BANNED_EMAILS variables to prevent specific addresses from subscribing to any of your mailing lists. If you only want to ban a specific address, add it to the BANNED_EMAILS variable - you can separate multiple addresses using commas. If you want to ban a whole website (eg all AOL users), you can add that to the BANNED_DOMAINS list. You can use commas to separate the domains as well.
At the end of the config.txt file you will find a list of pre-configured mailing lists. The general format is as follows:
[listID]
NAME="List name here"
DESCRIPTION="Description here"
PRIVATE="false"
SUBSCRIBE="default-subscribe@example.com"
UNSUBSCRIBE="default-unsubscribe@example.com"
Try not to include a space or a return at the end of these lines as it can potentially cause problems.
You need one of these entries for every mailing list you want subscribers to be able to manage directly (ie lists they can unsubscribe from using the web based interface). Find the ezMLM name for each of these lists, and replace "listID" with this name. You can write a more lengthy, human readable name for the list in place of "List name here". You should also write a description of the list, describing how frequently it receives emails and the topic of the list.
The Private setting allows you to set up lists that people can unsubscribe from if they are already subscribed, but which won't be listed to anyone who is not a subscriber (and hence, won't let them subscribe). This is useful for lists where you want to control who is subscribed, such as a mailing list for registered users of a software program.
Now the part where the action happens: uploading the files to your server.
Ensure your FTP program is set to upload files in ASCII mode, then copy the following files into your Main Script Directory (being sure to keep the "classes" files in their subdirectory):
Next upload all the files in the email, html and logs subdirectories to your Protected Files Directory. Be sure to keep them in their subdirectories too. (If you use a drag and drop FTP program like SmartFTP, just drag the email, html and logs directories across - don't bother highlighting each individual file and dragging it across one by one).
If everything went to plan, you've now installed the script! You should now be able to call it from your SCRIPT_URL location (eg http://example.com/cgi-bin/lists/email.php). You will probably want to make changes to the template files stored in your Protected Files Directory however....
WebScriber is heavily template driven - there are templates for all the confirmation emails sent to subscribers, and the look of the web-based interface can be configured using HTML templates. The HTML templates are split into Header & Footer files (which are displayed at the top and bottom of every HTML page respectively) and several other templates covering every circumstance. You can even customize the email subject lines from within the config.txt configuration file.
The following is a list of tags you can add to your templates. When the HTML is displayed (or the email is sent out), the following tags will be replaced with their corresponding values:
| &&ACTION&& | The action that the user has taken, such as "Subscribe" or "Remove". When confirming an action, the action being confirmed is placed here. |
| &&CONFIRMURL&& | The URL a subscriber needs to click on to confirm their subscription (or unsubscription). |
| &&DATESTAMP&& | The exact date and time a subscribe request was initiated, right down to the second. |
| &&EMAIL&& | The email address to be subscribed/unsubscribed. |
| &&ERROR&& | A text explanation of the error that occurred. |
| &&EXPIRYDAYS&& | The number of days that a confirmation email is valid for. After this many days, the confirmation URL will not work. |
| &&IPADDRESS&& | The IP address of the user submitting the subscription request. |
| &&LISTDESCRIPTION&& | A full textual description of the mailing list the user wishes to subscribe to. |
| &&LISTNAME&& | The full name of the mailing list, as defined in the config.txt file. |
| &&LISTSUBSCRIBE&& | The email address that prospective subscribers can send mail to in order to subscribe to a list via email using ezMLM (instead of using WebScriber's web based methods). Not recommended, but it's there if you want it. |
| &&LISTUNSUBSCRIBE&& | The email address that subscribers can send mail to in order to unsubscribe from a list via email (instead of using WebScriber's web based methods). Not recommended, but there if you want it. |
| &&NOTE&& | The note associated with a batch subscription, used to indicate how the recipients email address was obtained (eg "ticked box on mail order form", "gave address to Kurt at namesuppressed booth of Expo 2003") |
| &&SCRIPTURL&& | The full URL to the script on your server - this address can be used by subscribers to manage their subscriptions. |
| &&SENDEREMAIL&& | The email address of the person/organization maintaining the mailing lists and their subscriptions. This email address may also receive enquiries from subscribers unsure of the process, or who have complaints. |
| &&SENDERNAME&& | The real name of the person or organization maintaining the mailing lists and their subscriptions. That's probably you! |
| &&SUBSCRIPTIONSFORM&& | A table that can be inserted into HTML pages listing a user's subscriptions and providing them with the option to modify their subscriptions. Intended for use in the manage.html template only. |
| &&TASKLIST&& | A list of changes that are being made to a visitor's subscriptions. This is particularly useful in email confirmation messages, where you can tell the subscriber exactly which changes were made to their subscriptions. |
| &&USERAGENT&& | Details of the web browser used to submit a subscription request. |
A user can manage their subscriptions to your mailinglist by calling
the script directly in their web browser, eg by visiting the link
http://example.com/cgi-bin/lists/email.php. This address
will of course vary depending on where you have installed the main
script and your domain name.
From there, the user can enter their email address, and the script will show which mailing lists they are currently subscribed to. They can then choose to subscribe to more lists or unsubscribe from lists by checking the checkboxes next to each list.
You can add a subscribe form for a single mailing list to your site using the following HTML code:
<!-- Begin WebScriber Mailing List Web Form -->
<form action="email.php" method="post">
<table>
<tr><td align="center">
<input type="hidden" name="list" value="listname" />
<input type="text" name="email" value="" />
<input type="submit" value="Send" />
</td></tr>
<tr><td align="center">
Subscribe
<input type="radio" name="action" value="subscribe" checked="checked" /> |
<input type="radio" name="action" value="unsubscribe" />
Unsubscribe
</td></tr>
</table>
</form>
<!-- End WebScriber Mailing List Web Form -->
You will need to modify the code before it will work on your site. Firstly, change "listname" to the name of the mailing list you want people to signup for. (eg if you have an ezMLM list called newproduct, change "listname" to "newproduct"). You will also need to change "email.php" to the full URL where the email.php file can be found on your webserver. (eg if you have installed the script in your cgi-bin directory, the URL might be "http://www.example.com/cgi-bin/lists/email.php".
Occasionally, someone may subscribe to your list by out-of-band methods - they might tick a box on a paper form asking to be added to your list, or maybe you receive notification from your reseller that a customer wants to subscribe. For these cases, you can "trigger" a confirmation email to be sent, so the subscriber can confirm their subscription and have the proof of this stored in the same place as that of your other subscribers.
To do this, you may first wish to edit the content of the batchsubscribe.txt email template, as it is this message that will be sent to each prospective subscriber. Then, you should create an HTML page with the following form on your local computer or in a secure section of your site (eg password protected using .htaccess, it doesn't need to be on an SSL secure server):
<html>
<head>
<title>WebScriber Batch Subscription Form</title>
</head>
<body>
<!-- Begin WebScriber Batch Subscription Form -->
<form action="email.php" method="post">
<input type="hidden" name="action" value="multi">
<input type="hidden" name="list" value="listname">
<input type="hidden" name="pw" value="default">
<table>
<tr>
<td>Note:</td>
<td><input type="text" name="note" size="70" /></td>
</tr>
<tr>
<td>Addresses:</td>
<td><textarea name="email" cols="75" rows="8"
wrap="virtual"></textarea></td>
</tr>
<tr>
<td colspan="2"><input type="submit" value="Send"></td>
</tr>
</table>
</form>
<!-- End WebScriber Batch Subscription Form -->
</body>
</html>
This is similar to the form for subscribing email addresses and needs to be configured in the same way - replace "listname" with the name of your mailing list, replace "email.php" with the full URL of the script on your server. You also need to replace the password "default" with the password you have set in your config.txt file. Please note that the default password cannot be accepted for security reasons.
This form also provides a text field for writing notes. This lets you record extra information about how you obtained the person's email address (eg "Address provided in phone call"). A confirmation email will be sent to the subscriber, but it will have your IP address and Useragent details - this is why the Note field is helpful, it explains why your IP address is listed in the logs and not that of the subscriber. When the subscriber confirms their subscription, the note will be stored together with the proof of confirmation.
This script is brand new, so there aren't many questions yet. Be sure to send any questions to support@namesuppressed.com!
Yes it does. I prefer to call it Confirmed Opt-In, however. "Double Opt-In" is a term promoted mostly by spam marketers, designed to make people think it is more than is needed to confirm a subscriber has opted in. The word "double" suggests that the confirmation step is unnecessary - however the confirmation step is the only way to ensure the email address recipient wishes to receive mailings.
If you are using WebScriber on a pre-existing email list, check that the addresses have been converted to lowercase. We have found that users often forget the CaPiTaLiZaTioN they used when subscribing their email address, so WebScriber now converts all addresses to lowercase. If there are any pre-existing addresses on your list with capitals, WebScriber won't be able to unsubscribe them... so convert your list to lowercase!
Nope, your subscribers can still choose to use the built-in ezMLM subscription methods (ie sending emails to a specific subscribe address) and you can still submit email addresses using the ezMLM command line tools, or the CNC if your site is hosted by FutureQuest.
However, please note that using the CNC, the command line tools or the email methods will not allow WebScriber to record those actions to a logfile, and so you will not have any proof they occurred. This script does not allow subscribers to confirm their subscribe/unsubscribe action by email - they must follow a weblink to do the confirmation.
Not at this time, and it's unlikely to be added any time in the near future - sorry.
Perhaps, but I have no idea how to go about coding such a thing at this stage. It's on the wishlist but a low priority. If you have any idea how I could code such a mechanism, let me know!
No! If you don't want to use those templates, remove everything in those files so that they are empty. You can then paste whatever text you like into the other template files, and the header & footer templates won't interfere with them.
First you should backup your wbSLM files, so that you have a copy of all your template files and most importantly all your confirmations. However you then need to delete your wbSLM installation and install WebScriber as if it were a new program. Sorry, the two programs just aren't compatible. You can also find more details on how to uninstall wbSLM on the namesuppressed website.
Hmm, not sure. I intended to use features of Cascading Style Sheets to help me create plain-text versions from the HTML original, but it appears my browser ignores stylesheets when saving text files (yes, it even ignores the TTY media type). I intend to keep this readme in HTML because eventually WebScriber will develop its own Web UI for configuration - at that point, an HTML readme will make more sense.
<FilesMatch "\.txt$">
Order Allow,Deny
Deny from all
</FilesMatch>
I am working on a fix for this.
This is a list of those who help by contributing code, by testing early versions, or by making cool suggestions that I choose to include.