Page 1 of 20
Newsletter Studio Documentation
Newsletter Studio is a easy to use newsletter-package for Umbraco CMS. It helps you to build stronger relations to your visitors/customers. The installation and setup is super easy and you'll be ready to send newsletters in minutes.
Main features
Send newsletters from the Umbraco back office
Unlimited number of subscribers and newsletters in full version Easy to create content using the same rich text editor as Umbraco Can include dynamic content from Umbraco content nodes
Nice analytics and charts on opens and clicks
Connects to other systems using "Subscription providers" Handles bounces and lets you edit bounced subscribers Powerful feature to import subscribers
Ships with Razor-templates to integrate into the website front end Supports multiple smtp-servers and throttling
Hooks to extend the rendering process
Page 2 of 20
Content
Newsletter Studio Documentation ... 1
Main features ... 1
Content ... 2
Getting started ... 3
Installing Newsletter Studio ... 3
Setting up the settings ... 3
Outgoing e-email settings ... 3
Other settings for outgoing email ... 4
Application settings ... 4
Google Analytics Tracking ... 4
Bounce handling ... 5
Using a fake-smtp ... 5
Render tasks ... 6
Create a custom render task ... 6
Parameters to render tasks ... 7
Subscription Providers ... 8 How to implement ... 9 Configuration changes ... 10 Skins... 11 Custom markup ... 11 Mailing lists ... 12 Add/remove/edit a subscriber ... 12 Importing subscribers ... 12
Different file formats ... 12
From Microsoft Outlook ... 13
Sending to Umbraco members ... 14
Letting the user ignore newsletters ... 14
Creating Newsletters ... 15
The editor ... 15
Templates ... 15
Custom fields ... 15
Insert url content ... 16
Sending the letter ... 16
Analytics ... 17
Front end API ... 18
Release History ... 19
Page 3 of 20
Getting started
Installing Newsletter Studio
The installation is extremely simple, just go to the developer section of your back office, click packages/packages repository and search for Newsletter Studio. Once you find it, just click install.
The installation will automatically take care of all the setup and configuration the only thing you need to do is to insert you mail-server settings in the settings section of Newsletter Studio.
Setting up the settings
If you perfer you could set all your settings directly in the web.config-file in the Newsletter Studio folder or use Settings-section in the back office.
Outgoing e-email settings
Newsletter Studio supports multiple SMTP-servers and will spin over all of them during send out.
Host - The SMTP-server for outgoing e-mail Port - Default is 25.
Username - Username for server if required Password - Username for server if required
Enable SSL - If checked an secured connection will be used.
If you want Newsletter Studio to "fall back" on the SMTP configured in the root we.config, just open the "web.config" file in /umbraco/newsletterstudio/ and remove all smtp-servers from the list. This will for example enable you to use the Pickup Directory feature of ASP.NET.
Page 4 of 20 Jump to next server after - This option specifics the number of emails to send on
each sever before jumping to the next.
Throttling enable - Use throttling to hold the send out for x seconds. This could be used to prevent your server from being flagged as a SPAM-server. Only needed in very email intense applications.
Throttling messages per batch - Number of messages before holding send out Throttling scounds beetwen batches - How long should the send out pause?
Application settings
These settings effects the application and sets up your default settings.
Force unsubscribe - If checked the render engine will force the editor to insert a link for unsubscribing in the message body.
Settings only for admins - This will hide the settings tree from all non-admins. TinyMCE DataType Id - Must be an Integer with the DataTypeId of the rich text editor to render. This will be set up automatically but you could change it if you need.
Unsubscribe confirmation url - The URL where you would like Newsletter Studio to send subscribers that just clicked the unsubscribe link. If not set a generic message will be shown.
Send failures before unsubscribing - When a email bounces for x times the subscriber will be set as unsubscribed.
Google Analytics Tracking
When using the tracking Newsletter Studio has good preconfigured values for the tracking urls, but you can override them if you want to. The default way to use Google Tracking is to just leave the fields medium, source, name and content blank - this will give you the default settings.
Enable Google Analytics Tracking - Check this to enable the tracking. This will add Google Analytics tracking to all urls pointing to the internal site. External links will stay untouched. Source will be "NewsletterStudio", medium "email" and the Campaign name will be the same as the newsletters name.
Medium (Optional) For utm_medium-querystring to identify a medium such as email or cost-per- click. Example: utm_medium=cpc, utm_medium=email
Source (Optional) For utm_source to identify a search engine, newsletter name, or other source. Example: utm_source=google
Name (Optional) For utm_campaign to identify a specific product promotion or strategic campaign. Example: utm_campaign=spring_sale. If you leave this blank the name of the current email will be inserted.
Page 5 of 20 Content (Optional) Use utm_content to differentiate ads or links that point to the
same URL. Examples: utm_content=logolink or utm_content=textlink. If you leave this blank the subject of the current email will be inserted.
Bounce handling
The bounce handler uses a POP3 e-mail account to receive all the replies from subscribers that aren't available for some reason. The handler will figure out the problem based on the reply and it will delete the replay and put the subscribers
status to "error", after many bounces the subscriber will be unsubscribed depending
on the settings in application settings.
Activate bounce handling - If checked the bounce handler will run as a scheduled task every 15 minutes.
Bounce e-mail - The address to be the "sender" of all newsletter and also the receiver of any bounce responses.
Bounce server - The address or IP to POP3 server. Server port - The port to use. (Default is 110) Bounce mailbox username - Username for mailbox Bounce mailbox password - Password for mailbox
You can check your bounce mailbox settings by clicking on the "Test connection"-button.
Using a fake-smtp
When testing the product and while developing you solution it's great to have a "fake smtp server". We recommend Papercut that can be found at codeplex.
Page 6 of 20
Render tasks
Using a render task an developer can hook into the rendering process of the email and make changes to the message body/subject. This can be done both on an overall level and on each individual email (ie. personalization). This feature could for example be used to replace [sometext] inside the message with a value from some other source. All rendering that happens inside Newsletter Studio is build with render tasks and they are all configured inside the web.config.
Create a custom render task
Creating a custom render task is very straight forward. Just inherit the base class " NewsletterStudio.RenderTasks.RenderTask" and override these three methods:
• ProcessPreRender
This method will be invoked when a newsletter is about to be sent. Only once per letter - this could be used to make changes on an over all basis. Ie. It's here we replace relative links, add clicktracing, render url content, insert unsubscribe-links and so on.
• ProcessPreview
This method is the equivalent to PreRender but is only used when the letters is previewed. Here we exclude clicktracking, replace unsubscription with a # to prevent the unknown newsletter editor from trying to
unsubscribe.
Note. If this method is not overridden the base class will call PreRender instead so if it has the same code, no need to implement both.
• ProcessUniqItem
Will be called on each uniq render of an email. Here we replace [name] with the real name, we merge other personal fields into the content.
When you have your class ready, just put the DLL inside the bin-folder and add you render task to the list in web.config.
Page 7 of 20
Parameters to render tasks
The render tasks are passed parameters for you to use in the creation of your task. You can use them in different ways, one way could be to add extra headers to the message that are sent, this is done in the "ProcessUniqItem"-method.
This video show a demonstration http://www.youtube.com/watch?v=Qp3SMrD4bjc
public class AddCustomMailHeaders : RenderTask {
...
public override void ProcessUniqItem(RenderResult renderResult,
RenderTaskUniqItemParameters parameters) {
parameters.MailMessage.Headers.Add("Custom", "Header"); }
Page 8 of 20
Subscription Providers
Can be used to hook into other systems or data sources. Newsletter Studio will use the providers to fetch the needed information about the receivers. All current subscriptions options (Newsletter Studios native mailing list and Umbraco members) are build with providers and it's easy to implement you own.
As you can see the subscription providers make is possible to connect to any source, you could for example create a mailing list for all customers in the e-commerce that hasen't placed any others the past 4 months and the send them an offer. These filters are configured inside your custom subscription provider, or if you need multiple your subscription providers.
Page 9 of 20
How to implement
To create your own subscription provider you need to create a new class and inherit the abstract class NewsletterStudio.Bll.Providers.SubscriptionProviderBase.
This class contains some properties and methods that you must override: • UniqName
A string that contains a uniq name for your custom provider. Use comapnyname, projectname or whatever. Must be uniq.
• DisplayName
A friendly name of your provider that will be shown in dropdowns and other display areas. Ex. "eCommerce Customers"
• GetListItems
This method should return all your lists of subscribers, the provider can have as many lists as you like but must contain at least one. Here we can use ie, "All customers" , "Customer inactive (4 months), New customers (last week)".
• GetSubscribersForSendOut
This method will go and accualy fetch the subscribers for you course. The ListItems value property will be sent as parameter and for you to use for filtering.
• Unsubscribe
If your source supports unsubscribing put the logic here. • CanEditSubscriber
Used in the error-list on the analytics page, if your source has some kind of edit-page for the receivers', set this property to true.
• GetEditUrl
If "CanEditSubscriber" is set to true, Newsletter Studio will try to fetch the edit url from this method if needed.
When you have created your providers, put the dll in the bin-folder and add the right assembly information to /umbraco/newsletterstudio/web.config.
Page 10 of 20
Configuration changes
It's good to know what happens when a package is installed and Newsletter Studio changes some files in your system.
• /Web.Config
Increases the executionTimeout and the maxRequestLength.
• /conifg/ClientDependency.config
Increases the version on the root node to reset the cache. • /config/tinyMceConfig.config
Adding commands for new features in TinyMCE-editor and allowing the Template and the custom Newsletter-plugin to run.
• /umbraco/config/lang/en.xml
Adding language settings for the package.
<httpRuntime requestValidationMode="2.0" executionTimeout="600" maxRequestLength="102400" />
Page 11 of 20
Skins
In the settings section you'll also find the "Skin"-tab. A skin is like master page for the newsletter and can contain headers, standard footer and so on. The skin and the message content will be merged by the rendering engine.
The default skin is only a reset of mail clients style sheet settings based on the boilerplate from http://www.emailology.org/
Custom markup
There are a couple of tags that you can use in your skins/messages to make is a little more dynamic.
[content] - This is the placeholder for the content from the Newsletter. This is the only tag that's mandatory in all skins.
[name] - Will be replaced with the subscribers name. [email] - Will be replaced with the subscribers e-mail.
[unsubscribe] - Will be replaced with the URL to unsubscribe. [readonline] - Will be replaced with a URL to read the letter online.
Name, email, unsubscribe and readonline can also be used in the rich text editor when composing the newsletter.
If you need something else, like a tag for other personal information or a maybe to render product information when [product:23544] appears, consider implementing your own render task.
Page 12 of 20
Mailing lists
Newsletter Studio lets you handle lists of subscribers using different mailing lists but it also supports sending newsletters to members in the Umbraco membership-section.
Add/remove/edit a subscriber
It's easy to add/remove/edit subscribers using the dashboard found by clicking on a subscription in the tree. The filter pane is used to searching and for showing bounces by clicking the "Only bounces"-checkbox.
Importing subscribers
If you have a list of subscribers that you would like to import into Newsletter Studio, click the import-button in the toolbar go show the "Import Subscribers" dialog.
Different file formats
E-mail comma-separated
email@company.com, email@company.com, email@company.com....
E-mail separated with semicolon
Page 13 of 20 One e-mail per row
email@company.com --line break-- email@company.com --line break--
Name and e-mail. One per row separated by semicolon
First Last;email@company.com --line break-- First Last;email@company.com Name and e-mail. One per row separated by comma
First Last,email@company.com --line break-- First Last,email@company.com (Outlook) First name, last name, e-mail. One per row separated comma Explained below.
From Microsoft Outlook
It's very easy to import contacts from Microsoft Outlook, just follow these steps. Outlook 2007
1. Click File/Import and export and choose "Export to file" and click next. 2. Choose the option "Comma separated values (Windows)" and click next. 3. Select "Contacts" and click next.
4. Browse your computer and save the CSV-file somewhere. Give it a name and click ok, then click next.
5. Important
6. Scroll the list to the left and find "First name", "Last name" and "E-mail", when finding one of them click them, hold the mouse button and drag them over to the right hand side. Make sure that they are sorted in the correct order. First name, Last name and E-mail. Click ok when you're ready.
! Now click the "Map Custom Fields" button, in the dialog click "Clear mappings" on the right hand side.
7. Now click on finish.
8. Go back to the import dialog in Newsletter Studio, browse for the new file and select "Outlook...." as the format and the click Import.
Outlook 2010
1. Click File/Options in the new dialog click "Advanced" on the left hand panel and click on "Export" in the Export group.
2. Choose "Export to file" and click next.
3. Follow the steps for Outlook 2017, start at step nr 2. Goodie: This guide will show you the process
Page 14 of 20
Sending to Umbraco members
Newsletter Studio can also use the members of the site as receivers of an newsletter. When the newsletter is going to be sent, just choose one of the Member Groups in the list.
Letting the user ignore newsletters
By default Newsletter Studio will send the newsletter to all the members of a certain group but if you want to make it possible for the administrators and maybe the user self to choose you need to add a generic property to the Member Type used for your members.
It's important that you call the new property "newsletter" and set it to data type "True/False".
Page 15 of 20
Creating Newsletters
To create a new Newsletter just right click the newsletter icon in the tree and click "Create", or if you have existing letters, right click them and choose "Create new from this" to use the old newsletter as a template.
The editor
Newsletter Studio uses the same rich text editor as the rest of Umbraco which means that you are already familiar with the editor. You can access all your media items and all your content-nodes as if you where editing content on your site.
Because the editor is just a regular Umbraco Data Type you can access it in the developer-section and choose which plug-ins to show/hide. Default name of the data type is "Rich text Editor Newsletter Studio".
Templates
In the toolbar menu you'll find a lot of useful features. Templates is one of them. Clicking this button will show you a dialog with pre defined templates that you can choose to start from.
These template list can be extended by adding new file to the "/umbraco/newsletterstudio/templates"-folder and adding them to the tempates-list found in "/config/tinyMceConfig.config".
Custom fields
The custom fields are the same as the tags explained in the skins-section on page 5. Basically this means that you can add dynamic content to the newsletter.
Page 16 of 20 This feature is very handy when you want to insert dynamic
content into the newsletter. This can be a list of blog posts, news headlines, latest post in the forum or even content from an external source.
Adding a Url content placeholder in the newsletter will render that url into the letter at preview and send out.
To use this with the your own Umbraco site you may need to create newsletter specific templates to render out the nodes that you need to display as this feature will take all HTML that's returned from the source. Ex. you could insert googles start page in the letter by typing google.com in the url-field.
This video shows a demonstration http://www.youtube.com/watch?v=a4Ei7HyLLpg
Sending the letter
When you are done editing the newsletter it's time to send it. Click the "Send e-mail" button in the toolbar. This brings up the "Send newsletter dialog".
Here you can choose to • Send out a test
Sends a test to one e-email • Send the newsletter now
Sends the letter right away to the selected receivers.
• Schedule the send out
Tells Newsletter Studio to send the letter at a specific date/time.
Page 17 of 20
Analytics
Newsletter Studio doesn't send the message out in the blue. It tracks everything that happens. If it's opened by the
receiver, if any links where clicked or if the receiver decided to unsubscribe. You can even see the number of open letters hour per hour during the first week after send out.
All newsletter that are sent gets moved to the "Sent"-folder in the tree. When the message is older than 90 days it gets moved to the "Archive". Clicking on a newsletters brings up the analytics dashboard.
Page 18 of 20 To interact with Newsletter Studio from the
front end we provide a very simple API in the static class NewsletterStudio.Api. This class has several methods for adding and removing subscribers both from the built in subscriptions and from Umbraco's member section (it won't delete anything but it changes property values).
public static bool IsValidEmail(string email)
Helper that checks if a string contains a valid e-mail address public static bool Subscribe(string email)
Adds a subscriber with only email to the default mailing list public static bool Subscribe(string email, string name)
Adds a subscriber with email and name to the default mailing list. public static bool Subscribe(string email, int mailinglistId) Adds a subscriber with only email to a given mailing list.
public static bool Subscribe(string email, string name, int mailinglistId) Adds a new subscriber to a given mailing list
public static bool Subscribe(Dictionary<string, string> subscribers, int mailinglistId)
Adds a collection of names/addresses to a give subscription public static bool UnSubscribe(string email)
Removes an subscriber from all subscriptions in the database.
If its email from members section, it tries to set the newsletter-property to false. public static bool UnSubscribe(string email, int mailinglistId)
Removes an email from a given mailing list in the database.
Page 19 of 20
Release History
Version 1.1
• Improved SMTP-connection tester.
• New button to Newsletter Analytics to ”Copy to new”. • Added sender email and subject to Newsletter Analytics.
• Removed some dependencies from the class that holds the sending thread.
• Added button to ”clear” filter when editing mailing lists.
• UI imporoved when sending e-mail. Added confirm step at immediate mail out.
• Minor changes in boilarplate-skin.
• Introduced the concept of RenderTasks, will be extensible in future releases.
Version 1.1.2
• Fixes issues with the "Test connection"-feature. Version 1.1.3
• When using Umbraco members as subscribers the [name]-tag will no be replaced with the members name instead of login name. (The
memberObject.Text-property)
• Added a RenderTask to replace relative URLs. Now links to the media section and other parts of the site will start with the full domain-name. • Fixed bug that added to // in URL when tracking clicks.
Version 1.1.4
• Fixed bug in the connection tester that will prevent send out from working. Version 1.2
• Introduced rendering tasks that will enable developers to hook into the rendering process of an email.
• New status for subscribers (unsubscribed). A setting will enable editors to decide how many send out errors that are allowed before flagging the user as unsubscribed
• Changed UI for working with subscribers. Filter on status and added possibility to change status of an subscriber.
• Implemented support for multiple SMTP-servers and throttling.
• Moved settings to web.config file in the newsletterstudio-folder. Updated UI for settings as well.
• Importing lists won't resubscribe and unsubscribed email. • Support for Google Analytics Tracking with configuration
Page 20 of 20 be used for news lists, blog feeds, both internal content and external.
• Memory optimization for the send out class which handles memory even more beautiful.
• Bug fix. Too many slashes in the unsubscribe url. Version 1.2.1
• Bugfix in API, re-subscribing will now change subscriberstatus-to active • Typo in settings.aspx
Version 1.2.2
• Bugfix in API, adding new subscribers won't throw error • Added support for MySQL. (Se MySQL instructions-kit) Version 1.2.3
• Small bugfixes Version 1.2.4
• Small bugfixes Version 1.3.0
• NOT Compatible with previous versions, to upgrade. Please install 1.3.0 and look at database changes and so on
• Introduced the SubscriptionProvider model • Breaking changes to the RenderTask API
• Added "MailMessage"-object to render task for adding extra headers, attachments etc.
• Changes in the database
• Fixed issue with e-email address validation.
• Reordered render tasks to add tracking pixel inside html-tag
• Prepared underlying logic for upcoming release of "Send out providers" to send out emails using APIs and webservies.
