Some of the most common interactions with the Newsletter Studio API are gathered in an interface called INewsletterStudioService.
With this, you can, for example:
Just use the built-in IOC-container to get an instance of the interface by injecting it as a dependency into your controller.
The package ships with a simple demo-view that shows how to add a recipient to a list. You can find it here:
\Views\Partials\NewsletterStudioSignup.cshtml
This showcases a simple way to add a recipient from the front end of your site. If you need to do this in your own controller, here is an example:
using Microsoft.AspNetCore.Mvc;
using NewsletterStudio.Core.Public;
using NewsletterStudio.Core.Public.Models;
namespace Demo.Web.Features.AddRecipient;
public class AddRecipientController : Controller
{
private readonly INewsletterStudioService _newsletterStudioService;
public AddRecipientController(INewsletterStudioService newsletterStudioService)
{
_newsletterStudioService = newsletterStudioService;
}
[HttpGet("examples/add")]
public async Task<IActionResult> Add()
{
var mailingList = (await _newsletterStudioService.GetMailingListsForAllWorkspacesAsync()).First().Lists.First();
var addRecipientRequest = AddRecipientRequest.Create("john.doe@foobar.com")
.ForWorkspace(mailingList.WorkspaceKey) // Optional workspaceKey, only used with multiple workspaces
.WithFirstname("John")
.WithLastname("Doe")
.WithSource("Website")
.WithCustomField("city", "London")
.SubscribeTo(mailingList.UniqueKey)
.Build();
var result = await _newsletterStudioService.AddRecipientAsync(addRecipientRequest);
if (result.Success)
{
return Content("Subscribed");
}
else
{
return Content($"Error: " + result.Message);
}
}
}
The AddRecipientRequest-class contains a fluent API to set data for the operation, here are some of the methods:
The service is also used when you want to send transactional emails. Please have a look at the transactional email guide for a complete example.
It's possible to update any subscription status from the service as well.
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 = await _newsletterStudioService.AddOrUpdateSubscriptionsAsync(request);
It's possible to create a custom page where you can handle the unsubscribe-process. This page can for example use the API in INewsletterStudioService to list the current subscriptions for the recipient.
First, configure the "Unsubscribe confirmation url" in the Settings under the Workspace.
When this is configured we'll route recipients that want to unsubscribe to this page and append a token to the URL.
https://www.mypage.com/custom-unsubscribe?token=acb123.....
When rendering this page you can use the ParseUnsubscribeTokenAsync(string token)-method of INewsletterStudioService to get information about the recipient, e.g. the RecipientKey. Further down the process you can pass the RecipientKey to the GetSubscriptionsForAsync(), RemoveRecipientAsync() or UnsubscribeAsync()-methods.
There are plenty of other useful methods on the INewsletterStudioService.