Newsletter Studio

https://www.newsletterstudio.org/documentation/
Admin
Newsletter Studio provides useful information on how to get started and customize its email campaign...
Tokens:47,502
Snippets:774
Trust Score:7.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Umbraco Forms Extension

Source: https://www.newsletterstudio.org/documentation/package/extensions/umbraco-forms

Install the Newsletter Studio Umbraco Forms extension using the .NET CLI. This enables integration with Umbraco Forms.

```bash
dotnet add package NewsletterStudio.Plugins.UmbracoForms
```

--------------------------------

### Configuration using Code

Source: https://www.newsletterstudio.org/documentation/package/getting-started/configuration

Provide Newsletter Studio configuration programmatically by implementing INewsletterStudioOptionsAccessor. This example shows a custom implementation for setting workspace options.

```csharp
public class SiteNewsletterStudioOptionsAccessor : INewsletterStudioOptionsAccessor
{
    private readonly NewsletterStudioOptions _options;

    public SiteNewsletterStudioOptionsAccessor()
    {
        _options = new NewsletterStudioOptions();
        _options.Workspaces = new List<NewsletterStudioWorkspaceOptions>()
        {
            new NewsletterStudioWorkspaceOptions()
            {
                BaseUrl = "http://www.foobar.com",
            }
        };

    }

    public NewsletterStudioOptions Value => _options;
}

// register:

services.AddSingleton<INewsletterStudioOptionsAccessor,SiteNewsletterStudioOptionsAccessor>();

```

--------------------------------

### Install Mailjet Extension

Source: https://www.newsletterstudio.org/documentation/package/extensions/mailjet

Install the Mailjet extension for Newsletter Studio using the .NET CLI. This enables Mailjet integration for sending emails.

```bash
dotnet add package NewsletterStudio.Plugins.Mailjet

```

--------------------------------

### Update Plugin and Theme Folder Names

Source: https://www.newsletterstudio.org/documentation/package/other/linux-and-mac

This example shows how to rename plugin and theme folders to adhere to camelCase naming conventions required for Linux/Mac environments.

```bash
mv App_Plugins/MyPlugin/NewsletterStudio/Themes/MyTheme/Views App_Plugins/myPlugin/newsletterStudio/themes/myTheme/views
```

--------------------------------

### Install Newsletter Studio NPM Package

Source: https://www.newsletterstudio.org/documentation/package/develop/backoffice-extensions

Install the NPM package containing TypeScript types for creating Newsletter Studio extensions. This is a development dependency.

```bash
npm i -D @newsletterstudio/umbraco

```

--------------------------------

### Update Folder Name: App_Plugins/NewsletterStudioExtensions

Source: https://www.newsletterstudio.org/documentation/package/other/linux-and-mac

This example shows the required change for the extensions folder to comply with case-sensitive file system naming conventions on Linux/Mac.

```bash
mv App_Plugins/NewsletterStudioExtensions App_Plugins/newsletterStudioExtensions
```

--------------------------------

### Update Plugin, Theme, and Control File Names

Source: https://www.newsletterstudio.org/documentation/package/other/linux-and-mac

This example demonstrates renaming a specific view control file within a theme to follow the camelCase convention for Linux/Mac compatibility.

```bash
mv App_Plugins/MyPlugin/NewsletterStudio/Themes/MyTheme/Views/Controls/Button.cshtml App_Plugins/newsletterStudio/myPlugin/newsletterStudio/themes/myTheme/views/controls/button.cshtml
```

--------------------------------

### EmailSendingHandler Example

Source: https://www.newsletterstudio.org/documentation/package/develop/notifications

Implement a notification handler to intercept and modify email sending events. This example shows how to change the subject of an email before it is sent, handling both legacy MailMessage and MimeMessage types.

```csharp
public class EmailSendingHandler : INotificationHandler<EmailSendingNotification>
{
    public void Handle(EmailSendingNotification notification)
    {
        // The Message-parameter, of type object, will be different 
        // concrete type depending on which EmaiL Service Provider that is used.
        if (notification.Message is MailMessage legacyMessage)
        {
            legacyMessage.Subject = "Glenn";
        }

        if (notification.Message is MimeMessage mimeMessage)
        {
            mimeMessage.Subject = "Glenn";
        }
    }
}
```

--------------------------------

### Implement Custom Render Task to Add Attachments

Source: https://www.newsletterstudio.org/documentation/package/develop/render-tasks

Implement the IRenderTask interface to create a custom render task. This example shows how to add an attachment to each email.

```csharp
using NewsletterStudio.Core.Rendering;
using NewsletterStudio.Core.Rendering.Tasks;
using NewsletterStudio.Core.Sending;

namespace Demo.Web.Extensions.RenderTask;

public class AddAttachmentRenderTask : IRenderTask
{
    public void Process(RenderTaskProcessingResult result, RenderingUniqueContext context)
    {
        context.EmailMessage.Attachments.Add(GetAttachmentFor(context.Recipient));
    }

    private EmailAttachment GetAttachmentFor(IRecipientDataModel recipientDataModel)
    {
        using var stream = File.OpenRead("c:\\temp\\invoice.pdf");

        return new EmailAttachment("Invoice123.pdf", stream);
    }
}

```

--------------------------------

### Register Custom Merge Field Provider

Source: https://www.newsletterstudio.org/documentation/package/develop/merge-field-providers

Example of registering a custom merge field provider during application startup using IComposer.

```csharp
public class MySiteComposer : IComposer {
    public void Compose(IUmbracoBuilder builder)
    {
        builder.NewsletterStudio().CampaignMergeFieldProviders.Append<InMemoryMergeFieldProvider>();
    }
}
```

--------------------------------

### Example Macro Content Rendering

Source: https://www.newsletterstudio.org/documentation/package/develop/macro

This cshtml code demonstrates how to render dynamic content within an email macro. It accesses recipient data, merge fields, and transactional models.

```cshtml
@model NewsletterStudio.Core.Editor.Controls.Macro.EmailMacroViewModel

<p>Demo cshtml-Macro Rendering</p>

<strong>Email</strong><br/>
@Model.RecipientDataModel.Email

<strong>Merge Fields</strong><br/>
<ul>
    @foreach (var field in Model.RecipientDataModel.MergeFields)
    {
        <li>
            @field.Placeholder: @field.Value
        </li>
    }
</ul>

<strong>Transactional Model</strong><br/>
Has Model: @(Model.TransactionalModel == null ? "No" : "Yes")

@if (Model.TransactionalModel != null)
{
    <text>Model Type: @Model.TransactionalModel.GetType() </text>
}

@* Example of how to look for a given Transactional Model if the macro needs to read data from the model *@

@if (Model.TransactionalModel is ForgotPasswordModel data)
{
    <p>Data from model: @data.Data.Name</p>
}


```

--------------------------------

### Custom Tiptap Configuration Source

Source: https://www.newsletterstudio.org/documentation/package/develop/rich-text-editor

Implement the `NsTiptapConfigurationSource` interface to provide a custom configuration for Tiptap within Newsletter Studio. This example shows how to modify the default toolbar configuration.

```typescript
import { UmbPropertyEditorConfigProperty } from "@umbraco-cms/backoffice/property-editor";
import { NsTiptapConfigurationSource } from '@newsletterstudio/umbraco/extensibility';

export default class DemoNsToolbarSource implements NsTiptapConfigurationSource {

  /**
   * Provides an array of editor config properties for Tiptap when used inside Newsletter Studio.
   * @param defaults The default configuration for Newsletter Studio
   * @returns 
   */
  async getConfiguration(defaults: UmbPropertyEditorConfigProperty[])
  {
    // In here, we can return a fresh array of configs or modify the defaults.
    
    let configs = [...defaults];
    let toolbar = configs.find(x=>x.alias == 'toolbar')!;
    toolbar.value = [
      [
        [
          "Umb.Tiptap.Toolbar.SourceEditor",
        ],
        [
          "Ns.Tiptap.Toolbar.StyleMenu",
        ],
        [
          "Umb.Tiptap.Toolbar.TextAlignLeft",
          "Umb.Tiptap.Toolbar.TextAlignCenter",
          "Umb.Tiptap.Toolbar.TextAlignRight"
        ],
        [
          "Umb.Tiptap.Toolbar.BulletList",
          "Umb.Tiptap.Toolbar.OrderedList"
        ],
        [
          "Umb.Tiptap.Toolbar.Link",
          "Umb.Tiptap.Toolbar.Unlink"
        ]
      ]
    ]

    return configs;
  }

  destroy() {}

}

```

--------------------------------

### Update Folder Name: App_Plugins/NewsletterStudio

Source: https://www.newsletterstudio.org/documentation/package/other/linux-and-mac

When running on Linux/Mac, ensure folder names are in lowercase or camelCase. This example shows the required change for the main plugin folder.

```bash
mv App_Plugins/NewsletterStudio App_Plugins/newsletterStudio
```

--------------------------------

### Custom In-Memory Recipient List Provider Example

Source: https://www.newsletterstudio.org/documentation/package/develop/recipient-list-providers

This C# code demonstrates a custom Recipient List Provider using hardcoded in-memory data. It implements the IRecipientListProvider interface and registers itself for use in Newsletter Studio campaigns. Inject dependencies like IUmbracoContextFactory in the constructor.

```csharp
using NewsletterStudio.Core.Infrastructure.MailingLists;
using NewsletterStudio.Core.Rendering;
using Umbraco.Cms.Core.Web;

namespace Demo.Web.Extensions.RecipientListProvider;

/// <summary>
/// A Demo provider that uses in memory recipients.
/// </summary>
public class InMemoryRecipientListProvider : IRecipientListProvider
{
    private readonly IUmbracoContextFactory _umbracoContextFactory;

    public string DisplayName => "In Memory Provider";

    /// <summary>
    /// Enter a name or a localization key like ex_my_key. You need to make
    /// sure that these translations are loaded in to the backoffice.
    /// </summary>
    public string DisplayNameLocalizationKey => "In Memory Provider";

    public string Prefix => "ex";

    public InMemoryRecipientListProvider(
        IUmbracoContextFactory umbracoContextFactory
        )
    {
        // You can inject dependencies in the constructor if needed.
        // Providers are created as Singletons, keep this in mind when
        // injecting your dependencies.
        _umbracoContextFactory = umbracoContextFactory;
    }

    /// <summary>
    /// Called when we present available lists to the users, e.g. in the
    /// last step before sending a campaign.
    /// 
    /// Should return a list of available lists that this provider exposes.
    /// Examples:
    ///   Built in provider = Mailing Lists,
    ///   Umbraco Members = List of groups
    /// </summary>
    /// <param name="workspaceKey"></param>
    /// <returns></returns>
    public List<RecipientList> GetLists(Guid workspaceKey)
    {
        /*
         * Note here that each item in the list has a RecipientListIdentifier
         * This identifier is used to uniquely identify the list and will be
         * passed to other methods in this class to retrieve details.
         */
        return new List<RecipientList>()
        {
            new RecipientList()
            {
                // Replace 1 with a unique identifier (int, guid etc.) of your list.
                Identifier = new RecipientListIdentifier(Prefix, 1),
                Name = "Demo list 1",
                Subscribers = 25
            },
            new RecipientList()
            {
                Identifier = new RecipientListIdentifier(Prefix, 2),
                Name = "Demo list 2",
                Subscribers = 21
            }
        };
    }

}
```

--------------------------------

### Newsletter Studio Theme Structure in RCL

Source: https://www.newsletterstudio.org/documentation/package/concepts/themes

Example structure for organizing themes within a Razor Class Library (RCL). Themes should be placed under the wwwroot/App_Plugins/newsletterStudio/themes folder to be recognized by Newsletter Studio.

```text
├── wwwroot
│   └── App_Plugins
│       └── newsletterStudio
│           └── themes
│               └── myTheme
│                   ├── views
│                   │   └── controls
│                   │       └── button.cshtml
│                   └── theme.json
```

--------------------------------

### Minimum Theme Configuration

Source: https://www.newsletterstudio.org/documentation/package/concepts/themes

Use this minimal configuration to create a new theme. It only sets the theme name.

```json
{
  "name": "My New Theme"
}
```

--------------------------------

### Register Custom Render Task During Startup

Source: https://www.newsletterstudio.org/documentation/package/develop/render-tasks

Register your custom render task by appending it to the RenderTasks collection in your IComposer implementation.

```csharp
using NewsletterStudio.Core.Composing;
using Umbraco.Cms.Core.Composing;

namespace Demo.Web.Extensions.RenderTask;

public class MySiteComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.NewsletterStudio().RenderTasks.Append<AddAttachmentRenderTask>();
    }
}

```

--------------------------------

### Configure Campaign Content Types Using IComposer

Source: https://www.newsletterstudio.org/documentation/package/develop/sending-from-content-section

Programmatically add document type aliases to enable the 'Campaigns' tab using an `IComposer` during application startup.

```csharp
using Umbraco.Cms.Core.DependencyInjection;

public class AppStart : Umbraco.Cms.Core.Composing.IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        NewsletterStudio.Core.Public.NewsletterStudioService.ContentAppDocumentTypeAliases.Add("myDocumentTypeAlias");
    }
}

```

--------------------------------

### Create Block-Based Email Campaign from Code

Source: https://www.newsletterstudio.org/documentation/package/develop/sending-campaigns-programmatically

This snippet demonstrates how to construct a block-based email campaign entirely from code. It requires building rows, columns, and controls programmatically. Ensure `INewsletterStudioService` and `ICampaignEmailService` are injected.

```csharp
public class CreateBlockBasedCampaign
{
	private readonly INewsletterStudioService _newsletterStudioService;
	private readonly ICampaignEmailService _campaignEmailService;

	public CreateBlockBasedCampaign(
		INewsletterStudioService newsletterStudioService,
		ICampaignEmailService campaignEmailService
	)
	{
		_newsletterStudioService = newsletterStudioService;
		_campaignEmailService = campaignEmailService;
	}

		public void CreateBlockBased()
    {
        var mailingList = _newsletterStudioService.GetMailingList(Guid.Parse("10e650af-b90a-4792-82d4-b11069a9ec56"));
			
        var campaign = CampaignEmail.Create("Block based from Code", mailingList);

        campaign.ThemeAlias = "Default";
        campaign.Sender = new EmailAddress("info@my-company.com", "Company Inc");
        campaign.Subject = "Hallo World-campaign";
        campaign.Content.Rows = new List<EmailRow>();
        campaign.Content.Rows.Add(new EmailRow());
        campaign.Content.Rows[0].Columns = new List<EmailColumn>();
        campaign.Content.Rows[0].Columns.Add(new EmailColumn()
        {
            Columns = 4 // indicate that this column takes of 4/4 of the grid columns.
        });
        campaign.Content.Rows[0].Columns[0].Controls = new List<IEmailControl>();
        campaign.Content.Rows[0].Columns[0].Controls.Add(new TextEmailControlData()
        {
            Html = "I was created from code",
            Padding = new Padding(10)
        });
        
        campaign.ScheduledSendDate = new DateTime(2023, 01, 30, 16, 20, 00);

			var result = _campaignEmailService.Save(campaign);

			if (!result.Success)
			{
				Console.WriteLine("Could not create campaign: " + result.Message);
				foreach (var error in result.ValidationErrors.Errors)
				{
					Console.WriteLine($"Validation error: {error.Property} {error.ErrorAlias} {error.InternalDescription}");
				}
			}


	}
}

```

--------------------------------

### Add NewsletterStudio Package

Source: https://www.newsletterstudio.org/documentation/package/getting-started/installation

Use this command to add the main NewsletterStudio package to your project via the .NET CLI.

```bash
dotnet add package NewsletterStudio

```

--------------------------------

### Remove Core Render Tasks

Source: https://www.newsletterstudio.org/documentation/package/develop/render-tasks

Remove or inactivate core render tasks by using the Remove method in your IComposer implementation. This example removes tracking-related tasks.

```csharp
public class MySiteComposer : IComposer {
    public void Compose(IUmbracoBuilder builder)
    {
        builder.NewsletterStudio().RenderTasks.Remove<AddTrackingPixelRenderTask>();
        builder.NewsletterStudio().RenderTasks.Remove<AddClickTagsRenderTask>();
    }
}



```

--------------------------------

### Configure Debug File Path

Source: https://www.newsletterstudio.org/documentation/package/develop/debugging

Specify the directory where debug files should be created. The default path is `c:\temp`.

```json
  "NewsletterStudio" : {
    "Debug" : {
      "LogCampaignLinks" : true,
      "DebugFilesPath" : "c:\\temp",
    }
  }


```

--------------------------------

### Update Subscription Statuses

Source: https://www.newsletterstudio.org/documentation/package/develop/front-end-api

Use this snippet to update the subscription status for recipients across multiple mailing lists. Ensure you have the necessary GUIDs for recipients and mailing lists.

```csharp
var recipientKey = Guid.Parse("1495412D-538C-480E-BAF2-C747D33A3E8B");
var mailingList1Key = Guid.Parse("5EC42DB0-E46D-4966-A5B4-3B4C3C578B98");
var mailingList2Key = Guid.Parse("A7D0BDAF-7BC9-4035-B65E-DDF81816103E");
            
var request = AddOrUpdateSubscriptionsRequest.Create()
    .Set(recipientKey,mailingList1Key,SubscriptionStatus.Subscribed)
    .Set(recipientKey,mailingList2Key,SubscriptionStatus.Subscribed)
    .Build();

var result = _newsletterStudioService.AddOrUpdateSubscriptions(request);
```

--------------------------------

### Implement Custom Merge Field Provider

Source: https://www.newsletterstudio.org/documentation/package/develop/merge-field-providers

Example of a custom merge field provider implementing ICampaignEmailMergeFieldProvider. This provider defines custom fields like CompanyName, City, and BirthYear.

```csharp
public class InMemoryMergeFieldProvider : ICampaignEmailMergeFieldProvider
{
    public string Alias => "inMemory";
    public string DisplayName => "In memory";

    public List<MergeField> GetFields(Guid workspaceKey)
    {
        return new List<MergeField>()
        {
            new MergeField()
            {
                Text = nameof(InMemoryRecipient.CompanyName),
                Placeholder = "companyName",
                GroupText = "In Memory"
            },
            new MergeField()
            {
                Text = nameof(InMemoryRecipient.City),
                Placeholder = "city",
                GroupText = "In Memory"
            },
            new MergeField()
            {
                Text = nameof(InMemoryRecipient.BirthYear),
                Placeholder = "birthYear",
                GroupText = "In Memory"
            }
        };
        
    }

    public List<MergeFieldValue> ExtractValues(CampaignMergeFieldValuesRequestModel request)
    {
        var list = new List<MergeFieldValue>();

        if (request.RecipientProviderRecipientDataModel.Model is InMemoryRecipient recipient)
        {
            list.Add(new MergeFieldValue("companyName",recipient.CompanyName));
            list.Add(new MergeFieldValue("city",recipient.City));
            list.Add(new MergeFieldValue("birthYear",recipient.BirthYear.ToString()));
        }

        return list;

    }

}
```

--------------------------------

### Render Signup Form Partial View

Source: https://www.newsletterstudio.org/documentation/package/develop/signup-form

Use this partial view to render a basic signup form on your Umbraco page. It serves as a starting point for creating custom forms.

```cshtml
<partial name="NewsletterStudioSignup" />

```

--------------------------------

### Enable Campaign Link Logging

Source: https://www.newsletterstudio.org/documentation/package/develop/debugging

Activate logging for all links in sent emails and errors from TrackingControllerActions. Configure this in `appSettings.json`.

```json
  "NewsletterStudio" : {
    "Debug" : {
      "LogCampaignLinks" : true
    }
  }


```

--------------------------------

### Update Theme Folder and File Names

Source: https://www.newsletterstudio.org/documentation/package/other/linux-and-mac

All theme-related folders and files must use camelCase for compatibility with Linux/Mac file systems. This example demonstrates renaming a theme view control.

```bash
mv App_Plugins/NewsletterStudioExtensions/Views/Controls/Button.cshtml App_Plugins/newsletterStudioExtensions/views/controls/button.cshtml
```

--------------------------------

### Configure Campaign Content Types in appSettings.json

Source: https://www.newsletterstudio.org/documentation/package/develop/sending-from-content-section

Specify content type aliases that should display the 'Campaigns' tab for sending newsletters. This is done in the `appSettings.json` file.

```json
{
    "NewsletterStudio" : {
        "CampaignContentTypes" :  "myCampaignContentTypeAlias,anotherCampaignContentTypeAlias"
    }
}

```

--------------------------------

### Add Recipient Programmatically

Source: https://www.newsletterstudio.org/documentation/package/develop/front-end-api

Demonstrates how to add a recipient to a mailing list using the INewsletterStudioService and the AddRecipientRequest fluent API. This example shows setting first name, last name, custom fields, and subscribing to a list.

```APIDOC
## POST /examples/add

### Description
Adds a new recipient to a mailing list and subscribes them. This endpoint utilizes the `INewsletterStudioService` and the `AddRecipientRequest` builder to construct the recipient data.

### Method
GET

### Endpoint
/examples/add

### Parameters
#### Query Parameters
None

#### Request Body
None (Data is built using the `AddRecipientRequest` class in the controller)

### Request Example
(Controller code provided in source)

### Response
#### Success Response (200)
Returns a `ContentResult` indicating success or failure.
- **Success**: "Subscribed"
- **Failure**: "Error: [Error Message]"

#### Response Example
Content("Subscribed")

### AddRecipientRequest Fluent API Methods:
- **Create(string email)**: Initializes a new AddRecipientRequest with the specified email.
- **WithName(string fullName)**: Sets the full name, attempting to parse first and last names.
- **WithFirstname(string firstName)**: Sets the first name.
- **WithLastname(string lastName)**: Sets the last name.
- **SubscribeTo(Guid mailingListUniqueKey)**: Subscribes the recipient to the specified mailing list.
- **ForWorkspace(Guid workspaceKey)**: Assigns the recipient to a specific workspace (optional, used for multiple workspaces).
- **WithCustomField(string alias, string value)**: Sets a custom field value for the recipient. The alias must match a configured field.
- **WithSource(string source)**: Sets the source property for the recipient (e.g., "Website", "Footer form").
- **Build()**: Finalizes the AddRecipientRequest object.
```
Tokens:
Raw