PLUGIN README
Newsletter Builder - Email newsletter software
-------------------------------------------------------------------------------

*** UPGRADE INSTRUCTIONS CAN BE FOUND AT THE BOTTOM OF THIS README FILE ***

BASIC SETUP
-------------------------------------------------------------------------------
To get started, first confirm everything works by following these steps:

NOTE: Follow these steps to do a run-through before adding your customer email list to the program!

1) Upload the plugin files to your CMS folder under: /plugins/newsletterBuilder/.

2) Install and activate the "Newsletter Builder" plugin in the CMS under: Admin > Plugins.

3) Go to: Admin > General Settings > Background Tasks
    - Check the "Recent Activity" log to see if background tasks are running (there should be one a minute)
    - If the tasks aren't running, follow the instructions on the page to set them up.

4) Go to: Admin > Code Generator
    - Create a newsletter archive page and save it to your server.
    - Create a newsletter manage page and save it to your server.

5) Click on "Newsletter Builder > Settings".
    - Update the "From" name and email address that will be used to send your newsletter.
    - Make sure the "From" email is a valid email address and is checked regularly.
    - Set "Archive Url" to the pages you just created.
    - Set "Manage Url" to the pages you just created.
    - Enter some "test emails", one per line.  Set "test emails" to users who will review your
      newsletter before it is sent to your full list.
    - Don't make any changes to the other fields.  You can do that after testing.

6) Click on "Newsletter Builder > Lists" and create a mailing list named "Newsletter"
    - Enter the "List Name" and click "Save"

7) Go to the "Manage Page" you created in your browser and subscribe to the newsletter.
    - Click the confirm link in the email you receive.

8) Go to "Newsletter Builder > Messages" and create a new message.
    - Don't change any of the content, just send it to your test list.
    - Confirm that your test message is received by your test email address.

9) Once you receive your test message, modify the newsletter message and send it to the full list.
    - View the message list and confirm that the "Status" says "Sending (0 of 1)"
    - This script will send the message and give you instructions on setting up a cronjob.
    - After mailing, reload the message list and confirm "Status" now says "Sent (1)".

10) Go to the "Archive Page" you created in your browser and confirm the web archive works.


CUSTOMIZATIONS & IMPORTING
-------------------------------------------------------------------------------
Once you've confirmed that Newsletter Builder is properly set-up and working, follow these steps:

1) Newsletter Settings - Customize the default content to suit your preferences, and email your messages.

2) Manage & Archive Pages - Modify the HTML as needed to match the look and feel of your site.

3) Background Mailer - The background mailer lets you "delay" the sending of mail if your host
    has limits on how much mail they allow sent per hour or day.  You can find these settings
    at the top of newsletterBuilder.php and modify them as needed.  They look like this:

    $GLOBALS['BACKGROUND_SEND_MAX']   = 500; // max messages to send every minute, eg: 60 messages a minute is 3600 an hour
    $GLOBALS['BACKGROUND_SEND_DELAY'] = 0;  // second to wait after sending each message

    To send all your messages as soon as possible, set SEND_MAX to 1000.  This will send messages
    as fast as your mail server can handle them (up to 60,000 an hour).  Note that a second mailing
    process won't start if one is already running.

4) Import Emails - To import a previous mailing list go to: Admin > Plugins > Newsletter Builder > Import Emails.
    - Copy and paste each email address into the box, one per line.
    - For extra large lists, you can copy and paste blocks of emails in one at a time.
    - The importer will skip any emails already imported, and notify you of any invalid email addresses.
    - Users who are imported in this manner will be deemed as "Confirmed" and will not need to click a confirm link.


TRACKING AND REPORTING
-------------------------------------------------------------------------------
On the "Messages" menu you will see some aggregate stats:

Opens - This is number of users who have "opened" a particular newsletter message.
We use the industry standard method of tracking "opens" which is to included
a transparent 1x1 GIF image in the content of the HTML message.  We use a PHP script
to generate this image, and when it is loaded a log entry is added to the database
that the user "opened" the image.  Note that some email clients don't show images
unless the users clicks "View images" so the "opens" number may be less than the
actual number of users who have seen your message, but it's a good indicator.

One method to encourage your users to click "View Images" is to include images in
your newsletter content.  Also note that "opens" by users who receive the "test email"
messages are logged, but won't be shown in these totals.

Clickers - The is the number of users who have clicked on a link in the newsletter.
All links are transparently rewritten to point to a redirect script so that they
can be tracked (except for unsubscribe and confirm subscription links).  Note that
"clicks" by users who receive the "test email" messages are logged, but won't be
shown in these totals.

Clicks - This is the number of total clicks from all users, except "test email" users.


QUESTIONS, SUPPORT & HELP
-------------------------------------------------------------------------------
For any questions, support or help with this plugin, please contact us through
our website or post in our forum.  Thanks!


UPGRADING TO 3.00
-------------------------------------------------------------------------------
Here's how to upgrade previous versions of this plugin to v3.00:

- Make sure "Background Tasks" are enabled in the CMS under: Admin > General Settings > Background Tasks
  - Link: admin.php?menu=admin&action=general#background-tasks

- Click a database backup by clicking "Backup" under: Admin > General Settings > Backup & Restore

- Download a backup of your CMS folder including:
  - all plugins (/plugins/) and backup files (/data/backups/).
  - download your "Manage Url" page and "Archive Url" pages (listed under: Newsletter > Settings)

- Disable any previously setup cronjobs that run the old background-mailer.php script (this is no longer used).

- Update your "Manage Url" page and "Archive Url" page with a message "We're updating this page, check back
  later" so that no one will get a broken page while you are performing upgrades.

- Upload the new plugin files overtop of the old plugin files.  Compare the settings at the top of the old
  plugin and update the new plugin with the same settings as needed.

- Create a new mailing list under "Mailing Lists" named "Newsletter"
  - Save the list, then modify it again and click "Add all subscribers")
  - This will be your new "main" list.

- Create any other lists you would like to have.
  - You can either allow users join lists from the signup/manage page
  - ...or you can add emails to your list by clicking "Add Subscribers By Email" to import lists you already have

- Click: Admin > Code Generator and recreate the "Manage" and "Archive" pages.
  - Either replace your existing pages or compare the code and update as needed.
  - You can find the urls to your manage and archive pages under: Newsletter > Settings
  
- Test everything very thoroughly (subscribe, unsubscribe, etc).
  

-------------------------------------------------------------------------------
end of file.
