<h3>Newsletter Made Simple (NMS)</h3>
<h4><strong>What does it do?</strong></h4>
<p>Enables you to have a e-mail newsletter system inside CMS Made Simple.</p>
<p>Features:
<ul>
  <li>Allows for public (users can subscribe and unsubscribe at will) and private (admins maintained) lists</li>
  <li>Allows for email confirmation of subscription and unsubscribe activities</li>
  <li>Allows for disabling certain users</li>
  <li>Import and export of users</li>
  <li>Create custom fields to allow gathering and associating different data with each user</li>
  <li>Allows displaying archived messages in the frontend</li>
  <li>Complete template driven messaging system</li>
  <li>Messages can be stored and re-used</li>
  <li>Allows for embedding images into emails</li>
  <li>Allows attaching files to emails</li>
  <li>Supports pretty urls</li>
  <li>Sends emails in the background (using CGJobMgr)</li>
  <li>Supports dynamically generating lists by executing PHP code.</li>
  <li>Lots more</li>
</ul>
</p>
<div class="warning">
   <p><strong>Note:</strong> The 2.8 version breaks backward compatibility in some ways (particularly the confirm, subscribe, unsubscribe, and usersettings templates. See the changelog.</p>
</div>
<div style="border: 1px solid red; margin: 2em; padding-left: 1em; padding-right: 1em;">
<h4 style="color: red; ">READ THIS FIRST</h4>
<p>This is an EXPERT tool, designed for use by bulk emailing experts.  It is not designed for use by people that don't have intimate knowledge of the advantages and pitfalls of sending HTML emails.  If you don't have the required knowledge you should seriously consider NOT using this package.</p>
<p>This module can be used for sending bulk emails.  This can be a problematic and error prone process, and you should do considerable research before using this module.  Things you should research include:
<ul>
  <li>How to Send bulk emails so that they will not be interpreted as spam</li>
  <li>Repeatedly sending spam, or sending spam to a large amount of email addresses could get your domain blacklisted, and possibly all of the domains hosted by your ISP. <strong>Use extreme caution.</strong></li>
  <li>How to send HTML emails so that your clients will be able to read them</li>
  <li>Your hosts policy and limitations about email sending</li>
  <li>How to research removing your ISP from various blacklists as a result of implied spamming</li>
  <li>If sending bulk email using an address list you acquired or purchased from others there may be legal rammifications for sending unsolicited email.</li>
</ul>
<br/>
<p>This module can and will require significant additional resources on your host.  The minimum CMS Made Simple requirements <strong>are probably not sufficient</strong>.  You should be prepared to debug issues, and contact your host to increase limits such as memory limit and timeouts before using this module.  This module is best used on a host where you have complete control of the php settings.</p>
<p>The developers and supporters of this package assume no risk or responsibility for its improper use. <strong>Use At Your Own Risk.</strong></p><br/>
</div>
<h4>How do I use it?</h4>
<ol>
<li>Install the module (which you have probably done by this point).</li>
<li>Ensure that the CMSMS mail settings are properly configured and that the test function works as expected.</li>
<li>Grant appropriate permissions to the groups that will manage your lists. these include:
	<ul>
	<li>Manage NMS Lists &mdash; Add, remove mailing lists</li>
	<li>Manage NMS Users &mdash; Add, remove users in the database</li>
	<li>Manage NMS Messages &mdash; Add, edit, remove messages but not send them</li>
	<li>Manage NMS Jobs &mdash; Send messages and perform other 'job' functions</li>
	</ul>
</li>
<li>Create a list</li>
<li>(Optional) Add the {NMS} to a page to enable web site visitors to sign up for your list.</li>
<li>(Optional) Add users to your list manually with the Users tab in the admin system</li>
<li>Create a message to be sent as part of a job</li>
<li>Create a job. You will select a message to send and a list to send it to.</li>
<li>Start the job and your message will be sent
    <p><strong>Note:</strong> NMS will only send messages to 'confirmed' users.  You need at least one confirmed user in at least one list.</p>
</li>
</ol>
<p><strong>Note:</strong> On low traffic websites, it is recommended that you use a cron job to trigger the asynchronous processing at least every few minutes.  See the CmsJobMnager help for instructions about this.</p>

<h4>Basic Syntax:</h4>
<p>{NMS}  </p>

<h5>Further options:</h5>
<p>See below for a complete list of available parameters and their options.</p>

<h5>Display unsubscribe form:</h5>
<p>{NMS mode='unsubscribe'}</p>

<h5>Display the user settings page:</h5>
<p>{NMS mode='usersettings'}</p>

<h5>Display an archive of past newsletters:</h5>
<p>{NMS action='archivelist'}</p>
<ul>
<lh>Optional parameters for the archive:</lh>
<li>limit='#' where <code>#</code> is the number of past newsletters to show. If omitted, all are shown</li>
<li>sortby='date' &mdash; <code>date</code> (default), <code>id</code> (message ID), or <code>subject</code></li>
<li>sortorder='DESC' &mdash; either <code>DESC</code> (descending order, default) or <code>ASC</code> (ascending order)</li>
</ul>

<h4>Dynamic Lists:</h4>
<p>This feature allows creating a list whos membership is dynamic.  A User defined tag <em>(UDT)</em> is associated with the list, and executed when a job using that list is started.  The UDT returns an array of email addresses.</p>
<p>This functionality can be used to (for example) read email addresses from a remote database, from another CMSMS module, or from a CSV file stored on the server.</p>
<p>The output of the UDT needs to be an array.  The elements of the array can either be a single email adddress, or a hash containing a &quot;email&quot; field, and an optional &quot;username&quot; field.  See below for some simple examples.</p>
<p>The following example outputs an array of hashes containing email addresses and usernames.</p>
<pre>$out = array();
$out[] = array('email'=>'user1@somedomain.org','username'=>'Some User Name');
$out[] = array('email'=>'user2@somedomain.org','username'=>'Some Other User Name');
return $out;
</pre>
<p>The following example outputs a single array of email addresses.</p>
<pre>$out = array('user1@somedomain.org','user2@somedomain.org');
return $out;
</pre>
<h4>Importing users from CSV Files:</h4>
<p>This module supports importing users from an ASCII CSV format file. It supports merging information for existing users, creating lists, and creating custom fields.  Here is an example CSV format file.</p>
<pre># email,username,f::full_name,f::gender,f::salutation,l::test1,l::test2
"user1@somedomain.com","username1","John Doe","m","Mr.",1,
"user2@somedomain.com","username2","Jane Doe","f","Mrs.",1,1
</pre>
<ul>
<li>The header line begins with a # and defines the order of the fields in each line.</li>
<li>The email field is required.</li>
<li>Custom field columns begin with an f:: and define a custom field name.  The field name must contain only alphanumeric characters, and the underscore.</li>
<li>List columns begin with an l:: and define a list.  The list name must contain only alphanumeric characters, and the underscore.</li>
<li>In data rows, strings may be enclosed in double quotes... particularly if the field contains the , delimiter.</li>
<li>Multi-line contents are not supported (i.e: textarea fields)</li>
<li>Blank lines are ignored.</li>
<li>Other than for the header line, the # character indicates the start of a comment.  Anything further on that line is ignored.</li>
</ul>

<h4>Import users from the Front End Users database:</h4>
<p><strong>Note:</strong> You must have a property defined in FEU that stores the users' email address. It can be named whatever you want.</p>
<ol>
<li>Choose Extensions &gt; Newsletter Made Simple</li>
<li>Activate the Users tab</li>
<li>At the bottom, click Import Users from FrontEndUsers</li>
<li>Select the FEU field that contains the users' email addresses</li>
<li>Specify whether to copy the FEU user name to the NMS user name field. This is what would be output in your message if you included the {<span>$</span>username} placeholder.</li>
<li>Select the list to import to.</li>
<li>Click Submit.</li>
</ol>
<p>You will receive a report of the users processed, those already in your NMS database, those already on the list, and those that were added and subscribed. Users are not duplicated so there should be no harm in running an import periodically.</p>

<h4>Message variables:</h4>
<p>These are covered elsewhere, but added here for completeness. If you add these to your message, they will be replaced at sending time with the appropriate true values.</p>

<ul>
<li>{<span>$</span>username}  &mdash;  The user's name</li>
<li>{<span>$</span>email}  &mdash;  The user's email address</li>
<li>{<span>$</span>fields} &mdash; An array of the users custom fields. <em>(is not set if no fields exist for the user)</em></li>
<li>{<span>$</span>unsubscribe}  &mdash;  A URL that can be used to display a page for unsubscribing</li>
<li>{<span>$</span>preferences}  &mdash;  A URL that can be used to display a user preferences page</li>
<li>{<span>$</span>confirmurl}  &mdash;  A URL that can be used to confirm subscriptions</li>
<li>{<span>$</span>msg_permalink} &mdash;  A URL that can be used in each message to allow people to view an on-line copy of the message.
</ul>
<h4>Bounce Processing:</h4>
<p>The built in bounce processing capabilities allow reading a pop3 mailbox and searching the mails in that inbox for matching messages.  If the user can be properly detected, the 'bounce count' for that user will be incremented.  Once the 'bounce limit' is reached, the user will be disabled.</p>
<p><strong>Note:</strong> The bounce processing relies on finding the various headers that NMS includes in each message inside the bounced message.  If those headers cannot be found then bounce processing cannot proceed.</p>
<p><strong>Note:</strong> Your hosts email server configuration may be such that you don't receive bounce notifications in your pop3 mail box.  You may have to work with your hosting provider to ensure that this functionality works for you.</p>
<p>It is strongly recommended that you configure your sending email address to be the same as your pop3 email account, and that you use this account only for bounce processing.</p>

<h4>Message Template Tips:</h4>
<h5>Styling:</h5>
<p>For maximum results when sending html email messages do not refer to external stylesheets, or to external images.  Most email clients will not read external stylesheets, and will block links to external images.</p>
<h5>Content Blocks:</h5>
<p>The following special smarty tags are avaiable for use in NMS message templates.  The use of these smarty tags in your template will enable different content blocks or functionalities when defining or editing message:
<ul>

<li><strong>{nms_content name='block name'}</strong>
    <p>This tag defines a content block.  When editing a message a text area will be provided for each nms_content tag in your template.</p>
    Options:<br/>
    <ul>
    <li><em>wysiwyg='false'</em> : disable the wysiwyg for this content area</li>
    <li><em>oneline='true'</em> : provide a text input field instead of a text area</li>
    <li><em>prompt='name'</em> : Specify text for the prompt for this field when editing a message that uses this template.
    <li><em>assign='var'</em> : Specify the name of a smarty variable to receive the results of the function.
    </ul><br/>
    </p>
</li>

<li><strong>{nms_attachment name='block name'}</strong>
    <p>This tag defines a reference to an attached file (usually not an image).  When editing a message, a dropdown will be provided to allow the message editor to select a file that has already been uploaded to your website.  Upon sending a message, this file will be attached to your message.  Any references to this block will be replaced with links to the embedded file.
    Options:<br/>
    <ul>
    <li><em>prompt='name'</em> : Specify text for the prompt for this field when editing a message that uses this template.
    <li><em>urlonly=1</em> : Optionally return only the URL of the attachment.</li>
    <li><em>assign='var'</em> : Specify the name of a smarty variable to receive the results of the function.</li>
    </ul><br/>
    </p>
</li>

<li><strong>{nms_image name='block name'}</strong>
    <p>This tag defines a reference to an attached image.  When editing a message, a dropdown will be provided to allow the message editor to select an image that has already been uploaded to your site.  When the message is sent, this image will be embedded into your message, and all references to it will be replaced with links to the embedded image.
    Options:<br/>
    <ul>
    <li><em>prompt='name'</em> : Specify text for the prompt for this field when editing a message that uses this template.
    <li><em>src='image_name'</em> : Specify an image filename.  If this parameter is set there will be no prompt in the message edit form to supply a value for this field.  The file name specified must exist relative to the image uploads path.</li>
    <li>You can also specify other attributes for this tag, including alt, width, height, class, id, etc.  Anything that is XHTML valid.</li>
    <li><em>dir='directory'</em> : Specify the name of a directory to build a list of images from, relative to the uploads path.</li>
    <li><em>urlonly=1</em> : Optionally return only the URL of the image.</li>
    <li><em>assign='var'</em> : Specify the name of a smarty variable to receive the results of the function.</li>
    </ul><br/>
    </p>
</li>
</ul>
</p>

<h3>Support:</h3>
<p>This module does not include commercial support. However, there are a number of resources available to help you with it:</p>
<ul>
<li>For the latest version of this module, FAQs, or to file a Bug Report  please visit <a href='http://dev.cmsmadesimple.org/projects/newsletter/' target='_blank'>http://dev.cmsmadesimple.org/projects/newsletter/</a>.</li>
<li>Additional discussion of this module may also be found in the <a href='http://forum.cmsmadesimple.org' target='_blank'>CMS Made Simple Forums</a>.</li>
<li>The author, Robert Campbell, can often be found in the <a href='irc://irc.freenode.net/#cms'>CMS IRC Channel</a> (username: calguy1000).</li>
<li>Lastly, you may have some success emailing the author directly.</li>
</ul>
<p>As per the GPL, this software is provided as-is. Please read the text
of the license for the full disclaimer.</p>
<h3>Copyright and License</h3>
<p>Copyright &copy; 2008, Robert Campbel <a href="mailto:calguy1000@cmsmadesimple.org">&lt;calguy1000@cmsmadesimple.org&gt;</a>. All Rights Are Reserved.</p>
<p>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.</p>
<p>However, as a special exception to the GPL, this software is distributed
as an addon module to CMS Made Simple.  You may not use this software
in any Non GPL version of CMS Made simple, or in any version of CMS
Made simple that does not indicate clearly and obviously in its admin
section that the site was built with CMS Made simple.</p>
<p>This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Or read it <a href="http://www.gnu.org/licenses/licenses.html#GPL">online</a></p>