Newsletter Studio Documentation


Full text


Page 1 of 24

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 like Umbraco content nodes

 Start send outs from the content section  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 24


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 ... 11 Custom markup ... 12 Mailing lists ... 13 Add/remove/edit a subscriber ... 13 Importing subscribers ... 13

Different file formats ... 13

From Microsoft Outlook ... 14

Sending to Umbraco members ... 15

Letting the user ignore newsletters ... 15

Creating Newsletters ... 16

The editor ... 16

Templates ... 16

Custom fields ... 16

Insert url content ... 17

Sending the letter ... 17

Sending from the content section ... 18

Enable the data type ... 18

Use a custom template for the newsletter ... 19

Analytics ... 20

Front end API ... 21


Page 3 of 24

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 prefer you could set all your settings directly in the /config/newsletterStudio.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 "/config/newsletterStudio.config" 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 24

Other settings for outgoing email

Default sender name A default name of the e-mail sender that will be added to any created newsletter.

Default sender e-mail A default sender e-mail that will be added to any created newsletter.

Force sender defaults If set to true, the editor will not have the option to edit the name and e-mail of the sender, the specified defaults will always be used.

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


Page 5 of 24 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.

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 24

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 built with render tasks and they are all configured inside the newsletterStudio.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:


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 overall basis. Ie. It's here we replace relative links, add clicktracing, render url content, insert unsubscribe-links and so on.


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


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.


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 /config/newsletterStudio.config.


Page 7 of 24

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

public class AddCustomMailHeaders : RenderTask {


public override void ProcessUniqItem(RenderResult renderResult,

RenderTaskUniqItemParameters parameters) {

parameters.MailMessage.Headers.Add("Custom", "Header"); }


Page 8 of 24

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 hasn'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 24

How to implement

To create your own subscription provider you need to create a new class that inherits the abstract class NewsletterStudio.Bll.Providers.SubscriptionProviderBase.

This class contains some properties and methods that you must override: • UniqName

A string that contains a unique name for your custom provider. Use company name, project name or whatever. Must be unique.


A friendly name of your provider that will be shown in dropdowns and other display areas. Ex. "eCommerce Customers"


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)".


This method will go and actually fetch the subscribers for you course. The ListItems value property will be sent as parameter and for you to use for filtering.


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.


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 provider, build it, put the dll in the bin-folder and add the right assembly information to /config/newsletterstudio.config.


Page 10 of 24 One thing to notice is that the provider will not generate a

new mailing list in the application tree, it will only add new options to the dropdown lists when sending the newsletter.

The new lists will only show when you are performing a send out, not in the application tree.

For examples and inspiration, have a look at the Newsletter Studio Contrib-project at GitHub:


Page 11 of 24

Configuration changes

It's good to know what happens when a package is installed and Newsletter Studio changes some files in your system.


Increases the executionTimeout and the maxRequestLength.


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.


Adding language settings for the package.

<httpRuntime requestValidationMode="2.0" executionTimeout="600" maxRequestLength="102400" />


Page 12 of 24 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

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 13 of 24

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,,

E-mail separated with semicolon


Page 14 of 24 One e-mail per row --line break-- --line break--

Name and e-mail. One per row separated by semicolon

First Last; --line break-- First Last; Name and e-mail. One per row separated by comma

First Last, --line break-- First Last, (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 15 of 24

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 16 of 24

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".


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 17 of 24

Insert url content

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 in the url-field.

This video shows a demonstration

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 18 of 24

Sending from the content section

If you want to use a content node as the source for your newsletter you can use the custom data type that was introduced in Newsletter Studio version 1.3.2. This can be very useful if you for example stores all newsletters as content on your website. This means that you don't have to copy and paste the text - just send it directly from the content section.

Or if you don't want to give your editors access the Newsletter Studio section, you could use the data type-approach and then remove their access to the section so they only send letters using the data type.

Enable the data type

To use the data type, open up the settings section and choose the document type that you want to use for sending the newsletters.

This is how the newsletter-tab will look on your document type.

Add a tab

A good practice is to add a new tab, ie. called "Newsletter" and then add a new generic property of the type "Newsletter Send Out" to that tab so that the newsletter data type will have its own tab.


Page 19 of 24

This is how you add the generic property to the new tab

Try it out

When you jump over to the content section you will now see a new tab when editing nodes of the modified document type. If you click the preview button you'll see that the content of the newsletter will be exactly the same as if you where to view the public webpage - but there is a good solution.

Use a custom template for the newsletter

The template used to render the e-mail is by default the same used for rendering the public webpage, but this can be overridden. Add a new template in you settings section, use the same name as template that you want to override but add "Newsletter" in the end. So a "Textpage" template, would be called "TextpageNewsletter". Newsletter Studio will now use the "Newsletter"-post fixed instead.


Page 20 of 24


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 21 of 24

Front end API

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. Works only with the default mailing lists in Newsletter Studio.

public static bool Subscribe(string email, string name, int mailinglistId)

Adds a new subscriber to a given mailing list. Works only with the default mailing lists in Newsletter Studio.

public static bool UnSubscribe(string email, string subscriptionAlias)

Removes an email from a given mailing list based on the subscription alias. That alias is build up using 1. The unique name of the provider and 2 the data provider key for the list item. So the default mailing lists in Newsletter Studio will have the alias "NewsletterStudioSubscriptionProvider_1". If you want to know more about the alias have a look at the newsletter table in the database to see how they are built


Page 22 of 24

Change log

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


• 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

• New RTE feature to render the response from any url into the email. Could be used for news lists, blog feeds, both internal content and external.


Page 23 of 24 • 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.

Version 1.3.1

• Skin editor will refresh on load (fix needed for Umbraco v4.9+)

• Reinstall Newsletter Studio after uninstall failed because db-tables where not droped. Added check.

• Edit links on the "delivery failed"-list will now be hidden if the underlaying e-mail has changed.

• Improved the null check and parseing in the subscriptionprovider for umbraco members


Page 24 of 24 Version 1.3.2

• Support for Umbraco 6 and new TinyMCE-implementation. • Name of the sender can now be set when sending a newsletter. • Added macro parameter type for choosing mailing list.

• Trail mode will never remove any data. • TinyMCE icons will now scroll as they should.

• New data type to start send outs from the content section. Version 1.3.3

• Send to multiple subscriptions/mailing lists at once • Moved configuration to /config-folder

• Defaults for sender name / e-mail

• Change e-mail validation algorithm to use .net MailAddress • Unsubscribe from "Read Online" now works

• Newsletter Data Type now supports nodes with absolute urls returned from library.NiceUrl().

• Fixed link-bug in the show error dialog

• Render URL Render Task now shows friendly errors inline instead of YSOD.



Related subjects :