See also:

• Newsletter User Guide  (Download PDF version)
• Newsletter Developer Guide  (Download PDF version)

How to get started with Composite.Community.Newsletter

1. Create a mailing list (and add members to it if needed).
2. Create a newsletter template.
3. Create a newsletter.
4. Send the newsletter.
5. View its statistics.
6. To allow your website visitors to subscribe to, and unsubscribe from, public mailing lists, add the Subscribe and Unsubscribe forms to pages on your website.

Important Notes

1. To be able to send newsletters, make sure that you have configured an email host by editing ~/web.config and including the /configuration/system.net/mailSettings section.
2. It is highly recommended that you host your website on an SQL Server when using the Newsletter features.
3. If you use the Subscribe and Unsubscribe forms on a localized website, consider localizing these forms.

Creating Mailing List

1. In the Content perspective, select Newsletters and click Add New Mailing List (Subject) on the toolbar.
2. Specify the Title and Description in the dialog and click OK.

Adding Members to Mailing List

1. Right-click the subject-based mailing list and click Add Members in the context menu.
2. Type one or more email addresses and names in the wizard separating the address from the name with a comma and starting each address/name pair on a new line.
3. Click Next and click Finish.

Importing List from Data Type

In addition to creating a subject-based mailing list and adding members to it, you can import a list from an existing data type and thus create a data type-based mailing list. In this case, you will not need to add members manually. The data type must have a field named "Email".

1. In the Content perspective, select Newsletters and click Import List from Data Type on the toolbar.
2. Specify the Title and write the Description in the dialog.
3. Select a data type to import from and click Finish.

Note: Both dynamic and static data types are supported. You can create a mailing list from, for example, the Extranet users or the CMS Administrative Console users.

Importing List from Functions

You can also create a mailing list by importing members from a specific function. Currently XSLT and Razor functions are supported. The XSLT function may return XML or XHTML as its output type.

The functions should list members by using <Member /> element for each member. The <Member /> element must include the attribute named "Email" with a valid email address as its value. This element can also include custom attributes (fo example, Name, Company, etc).

For example: Expand code

<Members> 
  <Member Name="John Doe" Email="john.doe@contoso.com" /> 
  <Member Name="Jane Smith" Email="jane.smith@contoso.com" /> 
</Members>

Important: You cannot use an attribute named "Id" in the <Member />. The "Id" is a reserved attribute used internally.

To import the list from a function:

1. In the Content perspective, select Newsletters and click Import List from Function on the toolbar.
2. Specify the Title and write the Description in the dialog.
3. Specify the Function that meets the requirements described above and click Finish.

Important: If you later change the output of this function (for example, adding a new attribute "Company" to <Member/> elements), you must re-save the mailing list based on this function. You don't need to re-save the list if you have only added  new members.

Creating Newsletter Template

1. In the Layout perspective, select Newsletter Templates and click Add Newsletter Template on the toolbar.
2. Specify the Title and Description in the dialog and supply defaults for your newsletters such as Default From name, Default From email, Default Reply-To email, Default subject.
3. Select an Unsubscribe page where the recipients will be directed to when clicking the unsubscribe link in their newsletters and click OK.
4. Edit the contents of the newsletter template if needed and click Save. (Editing a newsletter template is similar to editing a page template.)

Note: If you need help designing newsletter templates, read about Rock Solid HTML Emails.

Creating Newsletter Confirm Template

If you want your subscribers to confirm their subscription by clicking the confirm link, you can create and use the confirmation templates. Every time the user subscribes to a mailing list, he or she will receive a confirmation email based on this template.

1. In the Layout perspective, select Newsletter Confirm Templates and click Add on the toolbar.
2. On the Template Info tab, specify the Template Name as well as Subject, From name, and From email
3. On the Content tab, edit the content of the newsletter confirm template if needed. (Editing a newsletter confirm template is similar to editing a page template.)
4. Click Save.

(You can choose what confirm template to use in the SubscribeForm function).

Creating Newsletter

1. In the Content perspective, expand Newsletters, select a mailing list and click Add Newsletter.
2. Fill or update the fields in the dialog where needed and click OK.
3. Edit the contents of the newsletter and click Save. (Editing a newsletter is similar to editing a web page.)

Adding Custom Fields to Newsletter

You can personalize the newsletter by adding custom fields related to a mailing list, e.g. Name or Email. They are replaced with their values in a newsletter each recipient receives individually. Datatype-based mailing lists might have more fields along with the Name or Email fields.

1. Edit a newsletter.
2. Click Insert, point to Field and click the field to insert where needed in the content.
3. Save the newsletter.

Managing Never Mail Me List

If a person does not want to receive any newsletters from you, add this person's email address to the Never Mail Me list:

1. In the Content perspective, right-click Newsletters and click to Never Mail Me List in the context menu.
2. Type one or more email addresses in the wizard starting each address on a new line.
3. Click Next and click Finish.

Exporting Members

1. Right-click a mailing list whose members you want to export and click Export members to XML in the context menu.
2. Select Save if prompted by the web browser and specify to the folder where you want your member list saved. The list saves as an XML file and you can view it in any XML viewer.

Sending Newsletter

1. Select the newsletter you want to send and click Send Newsletter on the toolbar.
2. Select one of the options - Send immediately or Schedule mailing - in the wizard.
3. If you have selected Schedule mailing, specify the date and time for the newsletter to be sent on.
4. Click Finish.

Other Sending Options

• Send Test: Before sending the newsletter to actual recipients, you can send the newsletter to some email address for test purposes.
• Send to New Members: Once the newsletter has been sent, you can only resend it to new recipients.
• Stop Sending: You can cancel sending the newsletter if it is being sent at the moment.

Adding Subscribe and Unsubscribe Forms to Web Page

1. In the Content perspective, edit a page you want to add the Subscribe form to.
2. Insert the Composite.Community.Newsletter.SubjectBased.SubscribeForm function or add the following code:
   Expand code

   <f:function name="Composite.Community.Newsletter.SubjectBased.SubscribeForm" xmlns:f="http://www.composite.net/ns/function/1.0"> 
     <f:param name="ConfirmEmailTemplate" value="c99a2b37-1b87-4b16-b24a-9cffb7895ab4" /> 
   </f:function>
3. If necessary, select a confirm template in the ConfirmEmailTemplate list to send confirmation emails to subscribers.
4. Save the page. Now the Subscribe area on the page will display the Name and Email fields and list all the mailing lists available for subscription.

Similarly, you can add the Unsubscribe form to a web page by using the "Composite.Community.Newsletter.UnsubscribeForm" function.

Viewing Statistics

Right-click the newsletter you want to view statistics for, and click Statistics in the context menu.

In the right pane, you can view the newsletter's statistics:

• Sent/Open: How many members the newsletter has been sent to and how many members have opened the newsletter or clicked links in it. 
• Links: What links have been clicked and how many times in total. 
• Domains by active users: The most active e-mail domains by the number of active users.
• Domains by links: The most active e-mail domains by the number of link clicks.
• Unsubscribe link clicks by members: list of email addresses of the members who have clicked the Unsubscribe link in the newsletter.
• Member activity: Email addresses of people whom the newsletter has been sent to with indication of whether a person have opened the newsletter and the number of point the person has gained. Each point is added if a person opens a newsletter or clicks a link in it.

Getting Newsletter ID

If you want to use a specific newsletter's ID (for example, by adding a link in the newsletter to publicly show the newsletter on a page on your website), you can create an XSLT function with a special parameter and use it in your newsletter to get the ID of the latter.

1. Create an XSLT function, for example, "Demo.Newsletter.ShowOnPage".
2. Add an input parameter of the String type to the function, for example, "Newsletter".
3. In the default value of this parameter, remove "Composite.Constant.String" and add the  "Composite.Utils.GetInputParameter" function.
4. In its "Parameter name" parameter, write "NewsletterId" (exactly as here).
5. On the Template tab, make use of this parameter's value, which is a GUID, the way you need.
6. Insert this function in the newsletter.

Now when the recipient receives this newsletter, it will contain its GUID.

Step 5 is up to you to implement. For illustration purposes, let's assume that you have a page ~/ViewNewsletter, which expected a query string parameter "Newsletter" with a newsletter's ID to show this particular newsletter. In the template of the function from our example, you can have this markup: Expand code

<a href="~/ShowNewsletter?Newsletter={/in:inputs/in:param[@name='Newsletter']}">View Online</a>

Localizing the Subscribe and Unsubscribe forms

The strings use on the Subscribe and Unsubscribe forms are stored in a resource file (.resx) in the App_GlobalResources folder and available for English (US) out-of-the-box.

To localize the forms:

1. Create a localization file for your language by:
   1. making a copy of ~/App_GlobalResources/Composite/Community/Newsletter.resx in the same folder
   2. and adding the code of the target language to the filename (before the extension .resx). For example, for Danish: Newsletter.da-DK.resx
2. Edit the localization file in Visual Studio.
3. Translate the Value of each string key-value entry.

Here is the list of strings available for translation: