title | description |
---|---|
Front end API |
Documentation about how to use the front end API in Newsletter Studio |
Some of the most common interactions with the Newsletter Studio-API is gathered in an interface called INewsletterStudioService
.
With this you can for example:
- Add recipients
- Subscribe recipients to mailing lists
- Unsubscribe recipients
Just use the built-in IOC-container to get an instance of the interface by injecting it as a dependency in the constructor of your controller.
The package ships with a simple macro to add a recipient to a list, you can find this in:
\App_Plugins\NewsletterStudio\Views\MacroPartials\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:
public class SubscribeSurfaceController : SurfaceController
{
private readonly INewsletterStudioService _newsletterStudioService;
public SubscribeSurfaceController(INewsletterStudioService newsletterStudioService)
{
_newsletterStudioService = newsletterStudioService;
}
public ActionResult Subscribe(SubscribeModel model)
{
var defaultMailingListKey = Guid.Parse("ff104e5c-a0c3-4a5b-a0eb-959685036b18"); // Replace with your mailing list key
var request = AddRecipientRequest.Create("john.doe@foobar.com")
.ForWorkspace(Guid.Parse("606D0954-DDAE-4ADF-BCB6-DD113ADD915E")) // Optional, only used with multiple workspaces
.WithFirstname("John")
.WithLastname("Doe")
.WithSource("Website")
.WithCustomField("city", "London")
.SubscribeTo(defaultMailingListKey)
.Build();
var result = _newsletterStudioService.AddRecipient(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:
- WithName(): Expects a full name and tries to parse it into first/last name.
- WithFirstname(): Sets the first name
- WithLastname(): Sets the last name
- SubscribeTo(): Subscribes the new recipient to a given Mailing List. (Tip: Use the Mailing List Picker property editor in the backoffice UI if this needs to be a setting).
- ForWorkspace(): Sets the Workspace for the new recipient. Only needed when the solution has multiple workspaces.
- WithCustomField() Sets a custom field value for the recipient. The alias must match a configured field alias (Workspace settings)
- WithSource() Sets the source property for the recipients. Used to track where recipients subscribe, could be i.g "Homepage", "Footer form" or any string.
The service is also 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 = _newsletterStudioService.AddOrUpdateSubscriptions(request);
It's possible to create a custom page where you can handle the unsubscription-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 ParseUnsubscribeToken(string token)
-method of INewsletterStudioService
to get information about the recipient eg. the RecipientKey. Further down the process you can pass the RecipientKey to the "GetSubscriptionsFor()", "RemoveRecpient()" or "Unsubscribe()"-methods.
There is plenty of other useful methods on the INewsletterStudioService.
- SendMailMessage() - Sends a standard .NET MailMessage with the configured Email Service Provider.
- Unsubscribe() - Globally unsubscribes a recipient
- GetRecipientsByEmail() - Get's all recipient by the provided email. Note that one e-mail can exist multiple times if using multiple workspaces.
- GetSubscriptionsFor() - Get's all mailing list-subscriptions for a given recipient.
- IsValidEmail() - Checks if a string is a valid e-mail address.
- GetMailingListsForAllWorkspaces() - Gets all mailing lists for all Workspaces.
- RemoveRecipient() - Removes a recipient and makes tracking data anonymized.