Sesaame Documentation

Welcome
Installation
Configuration and Personalization
The List Files
Putting Credits to Work
Usage Notes

1. Welcome

Welcome to the documentation for sesaame, your new touch-and-go viral email marketing script.

2. Installation

You can see the script in action immediately by performing the following steps.

Find or prepare a spot on one of your pages for the script's user interface. Making sure the page has the extension .php (or other extension configured with php), paste the following code into that spot.

<?php include('sesaame.php'); sesaame(); ?>

Upload the file sesaame.php into the same folder as that page, and you're done. The script will automatically create the required 'data' folder and database files within it, and also a .htaccess file denying access to the data folder. If the directory and files are not created automatically, you must create them:

Create a directory called 'data' in the same folder as your sesaame-enabled page.
Within that directory, create three empty text files named 'list.txt','refs.txt', and 'invites.txt'

When you view the page, the script automatically generates a dynamic user interface that may include messages, a form, and navigation links.

3. Configuration and Personalization

If you already took a look at the output of the script, you will have noticed that it already contains instructional and email text. These are just demonstration messages and are intended to be changed by you.

To edit the texts and other configuration options, open sesaame.php in a text editor. All of the messages are located at the top, along with some other options, in a series of defines.

Notice first the defines named SESAAME_GREETING_... These messages appear on each page of the interface and are intended to contain instructional and inspirational marketing-type text, and anything else you want on that particular page.

Make sure you edit subjects and messages that will be used for invitation and verification emails. ESPECIALLY make sure to edit the SESAAME_VERIFICATION_FROM email address. This is the address email verification requests will be sent from.

Some of the messages can contain special variables. They are %from%, %to%, %url%, and %refs%, and are only supported within certain messages. Instances of those variables will be replaced before the message is displayed. You should get an idea of how to use them by referring to the default texts I have entered.

As of this release there are two additional behavioral options:

SESAAME_REQUIRE_VERIFICATION -- If set to TRUE, users who join without being invited will have to follow an activation link supplied to them in a verification email before they are added to your list. If set to FALSE, their account will be automatically activated when they sign up.
SESAAME_KEEP_INVITES -- If set to FALSE, the script removes invitation data from the (invites.txt) database after the invitation/verification code has been used. You may wish to keep used invitation data if you want a record of who invited a user. On the other hand, after the file grows it may cause concern for disk space and system performance when referencing the list.
SESAAME_REMOVE_REFS -- If set to TRUE, when an end user requests an email address be removed it will be removed from both the verified email list (list.txt) and the referral stats (refs.txt). Otherwise the referral stats are not removed.

The output of the script is intended to be easily styled using CSS. The script output will consist of the following stylable elements:

The entire interface is wrapped in <div id="sesaame">
Every page contains information and text wrapped in <div id="sesaame_greeting">
A page generated after an error may contain an error description wrapped in <div id="sesaame_error">
On many pages there is one <form> element, containing one or more <input type="text"> elements and one <input type="submit"> element
Every page contains a dynamic set of navigation links wrapped in <div id="sesaame_nav"> and containing several <a> elements

4. The List Files

As the system is used, required information is kept in .txt files in the 'data' folder. It's important that you understand that only email addresses in the file 'list.txt' are verified/agreed emails for use in your mailings.

The three database files and their purposes are described below.

list.txt -- Contains email addresses of members who have joined. If SESAAME_REQUIRE_VERIFICATION is set to TRUE, these are your verified email addresses.
refs.txt -- Stores how many referral credits each member has earned.
invites.txt -- Stores information about pending invitations and sign-up requests, including a unique identifier, the pending user's email address, and the referring member's email address.

It's important that you protect the 'data' folder, such as with .htaccess, as if a user had access to invites.txt they may manually verify email addresses using the verification codes therein.

5. Putting Credits to Work

The number of credits earned by a member can be retrieved easily using the sesaame_refs() function, as illustrated in the following code which prints the number of credits user $email has earned.

<?php
include('sesaame.php');
print sesaame_refs($email);
?>

6. Usage Notes

When mailing the verified subscribers it is lawful to include an unsubscribe link at the bottom of the email. In the examples shown below, replace "www.example.com/example.php" with the usual path to your page which has the sesaame code pasted into it.

Example 1: Manual, gives you an opportunity to change the member's mind on-site! (SESAAME_GREETING_REMOVE)

<a href=http://www.example.com/example.php?action=remove>Unsubscribe<a>

Example 2: Automatic. Make sure you replace example@email.com with the specific user's email address.

<a href=http://www.example.com/example.php?action=remove&email=example@email.com>Unsubscribe<a>