WordPress Newsletter Plugin Documentation (v2.x branch)

1. WordPress 2.0.x or higher (Tested on WP v2.0.7)
2. WordPress 2.1.x or higher (Tested on WP v2.1.2)
3. WordPress 2.5.x or higher (Tested on WP v2.5.0)

If you are upgrading, please see the Upgrading section

1. Extract the st_newsletter folder from the ShiftThis-WP-Newsletter.zip file.
2. Upload the st_newsletter folder into the following WordPress directory: /wp-content/plugins/
3. Access the Plugin Panel in your Admin Panel, scroll down through the list of Plugins to find ShiftThis | Newsletter and click on the Activate link to turn the Plugin on.
4. Click on the new Newsletter Tab in your Admin Menu.
5. You may need to set your Options on the Newsletter Options page before some features will be available to you.

If you are upgrading from a previous version:

1. Extract the st_newsletter folder from the latest .zip file available on the My Paid Plugins Page
2. Upload the st_newsletter folder into the following WordPress directory: /wp-content/plugins/ overwriting the previous files.
3. Go to Newsletter > Options and check for any new features and set them to your preference, then save.
4. You are now officially upgraded!

Access via the Newsletter Tab > Options.

• Minimum User Level - This sets the minimum user level allowed to create and edit your newsletters. Default is set to Editor (7)
• Default Newsletter Template: - Sets the default template for your newsletter, this can be overridden within the Newsletter Editor.
• Max Number of Side Boxes - This sets the default amount of Side Box fields in your Newsletter Editor for the amount of Side Boxes needed. 1 should suffice for most templates, though more complex layouts may require the use of multiples.
• Show Meta Box for Newsletter - Enables the Meta Box textarea within the Newsletter Editor.
• Ability to Include Pages - Enables the ability to include pages as well as posts within the Newsletter Editor - these are added to the Include these Posts area.
• Subscribers Per Page Amount - sets the amount of Subscribers to show per page on the Subscribers tab.
• Maximum Newsletters to show per page in the Newsletter archive - This sets the amount of Newsletters to list per page on your Newsletter Archive Page via the newsletter_page() function.
• Default Message when no Newsletters are available in the Archive - This is the text displayed when there are no public newsletters available to view in the archive via the newsletter_page() function.
• Optional Pre-Subject - This text will appear before your newsletter title in the subject line. Can also be left blank.
• Flood Protection Batch - Set the quantity of emails to send in a batch - Gmail’s Max is 50.
• Flood Protection Pause - Set the time to wait between batches.
• Images - Two settings available for handling images within your newsletter:
  • Load From Site - This will load all image via http from the email client of your users. This allows users to choose whether to view images or not and will lower the size of your newsletter email for faster delivery and less bandwidth usage.
  • Embed Local Images into Email - This will embed all images located locally within your site to the email as an attachment. This will force the display of all local images for your newsletter but will also raise the size of your newsletter email which may result in slower delivery and higher bandwidth usage.
• Subscribe Page - Select the page containing your subscription form (st_mailinglist_subscribe()) so we know where to send subscribers who want to change their options.
• Subscribe Form URI Override - Set the action url of the Subscription form if the automated setting causes problems.
• Show Categories - Show Category Selection on Subscribe Page (generally used to hide the categories when you only use 1 category)
• Subscribe Fields - These are the fields you wish to display with your subscription form. You may add more fields using the Add New Field button and setting the Field Name in the empty text box and selecting whether it should be required or not. You can remove fields using the X button in front of the custom field. The Email field is not removable.
• Required Text - HTML text to appear next to any required fields to indicate that they are required.
• Visual Editor - Select the visual editor to use when creating your newsletters. Options include QuickTags, TinyMCE or FCK Editor.
• Disable WordPress Filters - This will disable Wordpress’s “the_content” filter which automatically adds formatting tags to your Newsletter content.
• Slash Fix - This will switch the directory slash for the admin plugin within your WP Admin. This is generally only required when you are testing the plugin locally on a Windows Server and receiving “Fatal error: Cannot redeclare…”.
• Error Log - This will display an error log upon sending for troubleshooting sending issues.
• Send From Email - This is the email you wish your newsletter to be sent from.
• Send From Name - This is the name you wish to use to send your newsletter from.
• Send To Name - This is the email name you wish to send to - you can use user information fields here as well or a custom name.
• Bounce Address - If an email bounces a notice will be sent to this address. You may want to set-up a separate account for bounce detection.
• Send Using - Select whether to send you newsletters via Swift SendMail (recommended) or Swift SMTP (slower) or Native Mail (not recommended). Note: Only your newsletters will use this setting, all subscription related emails use WordPress’s default wp_mail function for sending.
• SMTP Settings - Only necessary if Swift SMTP is selected in your Send Using setting.
  • Server - set to your email SMTP server setting (smtp.yourhost.com).
  • Username - set to the username used to login to your SMTP account.
  • Password - set to the password used to login to your SMTP account.
  • Should we use TLS or SSL? - If your server required TLS or SSL select the appropriate setting, otherwise set to No.
  • Port - Enter the port needed. (Gmail SMTP uses Port 465.)

Access via Newsletter Tab > Subscription Text

The subscription form text and emails can be customized from here. There are a number of Dynamic Tags available for use here.

• {presubject} - Displays the Pre-Subject set in the options above
• {list_name} - The Mailing List Name you set below
• {verify_link} - Displays the verification link needed to enable the subscription. This needs to be included somewhere in the Opt-In Message field or you won’t get any subscribers!
• {resend_link} - Displays the link needed to resend verification email. This can be used only in Duplicate Address (unverified) field
• {retrieve_account} - Link that will send account management email. This can be used only in Duplicate Address (verified)
• {account_link} - Link to the subscription account management page. This can be used only in Retrieve Account Link Message

You will also be able to your custom fields here as well. If you have a custom field named First Name, this can be used with the dynamic tag of {firstname}.

• Mailing List Name - The Name of your Mailing List.
• Opt-In Subject - Subject sent when user subscribes to your newsletter.
• Opt-In Message - Message sent when user subscribes to your newsletter. Note: The {verify_link} tag is required in this field, this is the only way for the subscriber to verify his address.
• Success Message - Message displayed on your site upon initial subscription.
• Duplicate Address (unverified) - Message displayed on your site if the email address has already been subscribed previously but has not yet been verified. Note: The {resend_link} tag is required in this field, this is the only way for the subscriber to resend the verification email to his address.
• Duplicate Address (verified) - Message displayed on your site if the email address has already been subscribed previously and verified.
• Retrieve Account Link Message - Message used to send account access link to subscriber. This sends him the link that is also included at the bottom of your newsletters for changing subscription settings or to unsubscribe.

If you have the WordPress Widgets Plugin installed, you can use the included ShiftThis Subscribe Sidebar Widget to add the subscription form to your blog. Just access the Presentation Tab > Sidebar Widgets page and drag the ShiftThis Subscribe box from the Available Widgets into the Sidebar box. See the How to Use Widgets page for more information on Widgets.

Insert <?php stnl_subscribe(‘Subscribe’); ?> into your theme template in either your themes sidebar template or a page template to display the subscribe form. This form can be styled to your needs easily within your themes styles.css stylesheet. You can also use a PHP Plugin such as Exec-PHP to allow you to place <?php stnl_subscribe(‘Subscribe’); ?> within a page or post via the Write Panel. ‘Subscribe’ is the default button text. You can replace the ‘Subscribe’ text with anything you like.

To create a page template that includes the Subscribe Form, you will need to be using a theme that includes the page.php file. If your theme does not include this file, you will need to create it (See WordPress Page templates).

1. In your current themes folder, duplicate your page.php file and rename it subscribe.php
2. Open subscribe.php and at the very top add the following code:

   <?php
   /*
   Template Name: Subscribe Form
   */
   ?>

3. Now find the_content function, generally looks something like:

   <?php the_content('<p class="serif">Read the rest of this page &raquo;</p>'); ?>

4. Place the following code above or below this:

   <?php stnl_subscribe('Subscribe'); ?>

5. Save the file and upload to your themes directory.
6. Create or Edit the Page you want the form to appear on and under Page Template select Subscribe Form
7. Save the page and make sure to set it in your Newsletter Options as well.

To display your archive of published public newsletters, simply insert <?php stnl_archive(); ?> into a page template or your sidebar template.

This plugin uses custom template functions similar to WordPress’s own theme system. The basic template is available in the "/wp-content/plugins/st_newsletter/template/" folder. The names should be pretty self explanatory:

• st_newsletter.php - This is your main template file that is used to call the following templates:
• st_header.php - This is the Header file for your template. Can be called using <?php st_header(); ?>.
• st_sidebar.php - This is the Sidebar file for your template. Can be called using <?php st_sidebar(); ?>.
• st_header.php - This is the Footer file for your template. Can be called using <?php st_footer(); ?>.
• st_posts.php - This is the Template for displaying your posts in the newsletter - Must be called using <?php st_posts(); ?>.

Below are the template tags and how to use them within the Template files:

• st_the_title() - This displays the title of your newsletter.
• st_the_date() - This displays the date your newsletter was published.
• st_the_sidebox(‘idnumber’) - This returns one of your Sidebar Boxes, specified by the id number. Example:: <?php echo st_the_sidebox(1); ?> will display the contents of only Sidebar Box 1.
• st_the_content() - This displays the main content of your newsletter.
• st_the_metabox() - This displays the metabox for your newsletter. Usually contains copyright info, etc.
• st_unsubscribe('{before}', '{after}', '{linktext}') - This displays the link to unsubscribe from your newsletter. Defaults to If you do not wish to receive this newsletter, <a href="http://www.yourblog.com/?unsubscribe=”>click here</a> to unsubscribe or edit your settings.
• st_view_online() - This displays the link to view your newsletter online. Defaults to If you experience issues with the display of this newsletter, <a href="http://www.yourblog.com/?unsubscribe=”>click here</a> to view it in your web browser.

The Post Template (st_post.php) uses regular Wordpress Template Tags to display your posts in the newsletter.

Access via the Newsletter Tab > Create

You can also use your custom fields here as dynamic tags. If you have a custom field named First Name, this can be used with the dynamic tag of {firstname} inserted in the Content, Sidebar Boxes or Metabox.

• Newsletter Title/Email Subject - This is your subject line and title that will display in your Newsletter Archives. (if you set a pre-subject in your options it will display before this)
• Content - This is the main body of your newsletter.
• Sidebar Box 1-10 - Depending on how many you set in your options page, this is the sidebar contents of your newsletter.
• Metabox - Generally used for copyright or other meta values.

Side Column:

• Date - The date of your Newsletter - mainly used for ordering within the Newsletter Archive.
• Category - The category of subscribers the newsletter is intended for.
• Include These Posts - Select the posts you wish to include within your Newsletter. They are displayed according to your posts.php template file. Use Ctrl to select multiple posts.
• Custom Post Order - Place the ID numbers of the posts you selected for inclusion separated by a space in the order you want them to display in your newsletter.
• Send Newsletter as - Set whether you’d like the newsletter to be sent as a multi-part (Text/HTML) email - this is the default recommended option as HTML enabled subscribers will get the HTML version and everyone else will get a text-only version - HTML only or Text Only (Note: Text only will send your template as text so be sure to alter it to strip out all HTML.
• Newsletter Archive Status - Set to Draft to hide from all view on the archive page. Set to Private for only you to view on the archive page, public will be unable to view. Set to Published to display publicly for all.

Saving the Newsletter will not actually send anything. Sending is done within the Preview/Send Section.

Access via the Newsletter Tab > Categories.

Here you will have the default category of General listed. You can add, edit or delete a category here as well. Make sure you always have at least one category or no one will be able to subscribe.

Access via the Newsletter Tab > Manage. Here you will have a list of all your created newsletters with the option to Edit or Delete individual Newsletters.

Access via the Newsletter Tab > Preview/Send Here you will have a list of all your created newsletters with the option to Preview/Send. This is where you can have a final look at your finished newsletter and then send it to your subscribers.

• Click the Preview/Send button on the Newsletter you wish to Send or Preview.
• A frame will appear containing your newsletter within your template.
• If satisfied with the newsletter, you can then choose whether to send to a category of subscribers or a single email.
• Send to Subscribers - This will send your newsletter to its current subscribers. This is based upon the newsletter category matching the subscribers category. If you would like to override this default setting, select an alternative category below or choose “send to all”.
• Send to Single Email - This will send your newsletter to a single email address in your subscriber base. If you would like to send it to yourself you will need to subscribe your address to the mailing list.

Click the SEND button under your option of choice to start sending. The time needed to send will vary depending on your server, the amount of subscribers and whether you use Swift Sendmail or SMTP.

Access via the Newsletter Tab > Subscribers. This will give you a list of all your current subscriber details and whether they are verified or not. You can delete a subscriber using the delete button next to there name, checking the box next to individual subscribers and clicking the Delete all checked button or by typing an email address into the Delete A Subscriber form.

You can now also manually add a Subscriber using the Add Subscriber area at the bottom of the page. This will add a subscriber as confirmed.

Accessed via the Newsletter Tab > Import/Export

The Export Subscribers feature creates a CSV file for you to download. Just click the Export to CSV File (comma-seperated values) button and right-click the link that appears underneath and save the file.

The Import Subscribers feature allows you to import a CSV file of values you can map to the correct fields for use within the Newsletter Plugin. This will set all imported subscribers as verified. I recommend splitting your data into separate files of 100 to prevent server timeouts or connection errors.

Your CSV file needs to have each line terminated with a line break and each field separated with a comma(,). You should be able to open your CSV file in Notepad and view it without any strange characters showing up.

If your CSV file includes headings in the first row, make sure to select the option to ignore the first row in the next step.

This shows how the text should look within Notepad or other text viewer in your CSV file of import values.

"fakeemail@mail.com"
"fakeemail2@mail.com"
"fakeemail3@mail.com"
"fakeemail4@mail.com"
"fakeemail5@mail.com"
"fakeemail6@mail.com"
"fakeemail7@mail.com"
"fakeemail8@mail.com"

To import the CSV file and read it’s contents, the plugin requires the following:

• Within your Options Panel under Miscellaneous, make sure your uploads folder is writable. This is where the csv file is temporarily uploaded to for importing.
• You will need fopen enabled to read the contents of the csv file and import.

1. Click the Browse button and select your CSV file of values to import and click the Import File Button. This uploads the file to the server for reading.
2. You should now have the Match Fields for Importing area visible.
   • Import First Row - Defaults to Yes, but if your CSV file contains Field Headings in the first row then select No.
   • Email - Select the Email value from the drop down.
   • Extras - Select the Extras value from the drop down
   • Categories - Select the Categories value from the drop down.
   • Continue for the rest of the values you may need. Leave unneeded fields as N/A.
3. Click the Import Values button.

Your subscribers should now be imported. If you had any problems or errors while importing, make sure your CSV file is setup correctly, try using the included example files as a test.

Access via the Newsletter Tab > Swift Test.

This plugin is currently using Swift Mailer v3.0.5. Swift is a fully OOP Library for sending e-mails from PHP websites and applications. It does not rely on PHP‘s native mail() function which is known for using high server resources when sending multiple emails. Instead, Swift communicates directly with an SMTP server or a MTA binary to send mail quickly and efficiently.

Before releasing your Newsletter upon the world, it’s recommended to make sure that your Swift setup is working properly. Below you will find a number of simple test emails to run for your website. You will need to edit the file ‘st_newsletter/Swift/tests/TestConfiguration.php’ and fill with the appropriate values. This will eventually use your Newsletter Options settings. Try using the Swift Sendmail option first as it is the quickest and easiest way to send email. If your server does not support the Sendmail Option, use the SMTP option.

To localize your plugin to your own language, do the following:

1. Open your wp-config.php file from your WordPress Installation and change - define (‘WPLANG’, ''); - to define (‘WPLANG’, ‘en_CA’); where en is the language (en=English) and CA is the Country Code (CA=Canada) for your region. Save and upload back to your server.
2. Download and install poEdit (http://sourceforge.net/project/showfiles.php?group_id=27043&package_id=18746&release_id=459538)
3. Run poEdit and open the st_newsletter/locale/WP-Newsletter.po file.
4. To make changes to the text, select the line, then in the bottom-left box translate the text to your language. The top-left box is the original text, and the two right-side boxes are for comments only.
5. Once you have made all the translation’s neccessary, choose File > Save As.. and name your file ‘stnl-en_CA’ except replace “en” with your language code, and “CA” with your Country Code that you set in step 1. Save the file in the same locale directory. (You may need to save twice to generate the .mo file needed).
6. Upload the stnl-[language]_[COUNTRY].mo file to your server to finish the translation.