Newsletter Studio Documentation

Transcription

1 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 The Newsletter Studio dashboard 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 1 of 20

2 Content Newsletter Studio Documentation... 1 Main features... 1 Content... 2 Getting started... 3 Installing Newsletter Studio... 3 Setting up the settings... 3 Outgoing e- settings... 3 Other settings for outgoing 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 Skins Custom markup Mailing lists Add/remove/edit a subscriber Importing subscribers Different file formats From Microsoft Outlook Sending to Umbraco members Letting the user ignore newsletters Creating Newsletters The editor Templates Custom fields Insert url content Sending the letter Analytics Front end API Release History Version Page 2 of 20

3 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- settings Newsletter Studio supports multiple SMTPservers and will spin over all of them during send out. Host - The SMTP-server for outgoing 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 3 of 20

4 Other settings for outgoing Jump to next server after - This option specifics the number of s 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 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 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 " " and the Campaign name will be the same as the newsletters name. Medium (Optional) For utm_medium-querystring to identify a medium such as or cost-per- click. Example: utm_medium=cpc, utm_medium= 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 will be inserted. Page 4 of 20

5 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 will be inserted. Bounce handling The bounce handler uses a POP3 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 - 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 5 of 20

6 Render tasks Using a render task an developer can hook into the rendering process of the and make changes to the message body/subject. This can be done both on an overall level and on each individual (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 . 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 6 of 20

7 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. public class AddCustomMailHeaders : RenderTask {... public override void ProcessUniqItem(RenderResult renderresult, RenderTaskUniqItemParameters parameters) { parameters.mailmessage.headers.add("custom", "Header"); } } This video show a demonstration Page 7 of 20

8 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 8 of 20

9 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 9 of 20

10 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. <httpruntime requestvalidationmode="2.0" executiontimeout="600" maxrequestlength="102400" /> /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. Page 10 of 20

11 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. [ ] - Will be replaced with the subscribers . [unsubscribe] - Will be replaced with the URL to unsubscribe. [readonline] - Will be replaced with a URL to read the letter online. Name, , 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 11 of 20

12 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 membershipsection. 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 comma-separated @company.com, @company.com, @company.com... separated with semicolon @company.com; @company.com; @company.com... Page 12 of 20

13 One per row --line break-- --line break-- Name and . One per row separated by semicolon First --line break-- First Name and . One per row separated by comma First --line break-- First (Outlook) First name, last name, . 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 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! Now click the "Map Custom Fields" button, in the dialog click "Clear mappings" on the right hand side. 6. Scroll the list to the left and find "First name", "Last name" and " ", 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 . Click ok when you're ready. 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 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 13 of 20

14 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 14 of 20

15 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 developersection 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. These tags will be replaced with the users name, or other dynamic parts. Page 15 of 20

16 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 google.com 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 " 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- 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 16 of 20

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

18 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 IsValid (string ) Helper that checks if a string contains a valid address public static bool Subscribe(string ) Adds a subscriber with only to the default mailing list public static bool Subscribe(string , string name) Adds a subscriber with and name to the default mailing list. public static bool Subscribe(string , int mailinglistid) Adds a subscriber with only to a given mailing list. public static bool Subscribe(string , 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 ) Removes an subscriber from all subscriptions in the database. If its from members section, it tries to set the newsletter-property to false. public static bool UnSubscribe(string , int mailinglistid) Removes an from a given mailing list in the database. Happy coding! Page 18 of 20

19 Release History Version 1.1 Improved SMTP-connection tester. New button to Newsletter Analytics to Copy to new. Added sender 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 . Added confirm step at immediate mail out. Minor changes in boilarplate-skin. Introduced the concept of RenderTasks, will be extensible in future releases. Version Fixes issues with the "Test connection"-feature. Version 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 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 . 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 . Support for Google Analytics Tracking with configuration Page 19 of 20

20 New RTE feature to render the response from any url into the . Could 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 Bugfix in API, re-subscribing will now change subscriberstatus-to active Typo in settings.aspx Version Bugfix in API, adding new subscribers won't throw error Added support for MySQL. (Se MySQL instructions-kit) Version Small bugfixes Version Small bugfixes Version NOT Compatible with previous versions, to upgrade. Please install 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- 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 s using APIs and webservies. Page 20 of 20