logo
logo

Notifications client

The SDK provides a Notifications client to manage and send notifications.

Note

The client variable in the following code examples refers to the IMClient instance. When using the Web SDK, the variable name can be chosen freely, but it is also called client at instantiation in the documentation.

E-mail templates

Mail template entities contain the templates for sending e-mails. The variables can be resolved at runtime.

IMailTemplate is a subtype of IEntity. It provides C# properties and methods for the members on the M.Mailing.Template entity definition.

The client provides extra getters for getting these mail templates, that are not available on the entities client. It allows fetching mail templates by name. However, every operation on an IEntity still applies to IMailTemplate. Saving and deleting IMailTemplate objects are still done through the entities client.

Getting an e-mail template

To get an e-mail template by name, for example the template for when a user has forgotten their password:

IMailTemplate template = await MClient.Notifications.GetMailTemplateAsync("ForgotPassword");

Note that it is still possible to get the mail template by id as well:

IMailTemplate template = await MClient.Entities.GetAsync(id) as IMailTemplate;

Creating an e-mail template

A simple hello world template could look like this:

CultureInfo enUs = CultureInfo.GetCultureInfo("en-US");
IMailTemplate template = await MClient.EntityFactory.CreateAsync(Constants.MailTemplate.DefinitionName) as IMailTemplate;
template.Name = "Hello world template";
template.SetSubject(enUs, "Hello there!");
template.SetBody(enUs, "Hello {{Username}}!");
var templateVariable = new TemplateVariable
{
    Name = "Username",
    VariableType = TemplateVariableType.String
};

template.SetTemplateVariables(new[] { templateVariable });

await MClient.Entities.SaveAsync(template);

Sending e-mail notifications

E-mails can be sent to users by username, user id or by a broadcast. There are three respective overloads to the SendEmailNotificationAsync. It accepts the following input:

  • MailRequestById: for specifying users by id.
  • MailRequestByUsername: for specifying users by username.
  • MailRequestBroadcast: sends to all users.

An e-mail broadcast could be sent using the template previously created:

var request = new MailRequestBroadcast
{
    MailTemplateName = "Hello world template"
};
request.Variables.Add("Username", "world");

await MClient.Notifications.SendEmailNotificationAsync(request);

This would send an e-mail, containing "Hello world!", to everyone.

Sending real-time notifications

Real-time notifications can be sent to users by username, user id or by a broadcast. There are three respective overloads to the SendRealTimeNotifcationAsync. It accepts the following input:

  • RealtimeRequestById: for specifying users by id.
  • RealtimeRequestByUsername: for specifying users by username.
  • RealtimeRequestBroadcast: sends to all users.

A real-time notification could be sent to the DemoUser:

var request = new RealtimeRequestByUsername()
{
    Title = "Your notification title",
    Link = new System.Uri("https://example.com")
};
request.Recipients.Add("DemoUser");
request.SetBody("Your description");
request.SetIcon("https://example.com/image.png");

await MClient.Notifications.SendRealTimeNotificationAsync(request);

The link is opened when the user clicks on the notification.

This real-time request interface is built on the standard notifications API: https://developer.mozilla.org/en-US/docs/Web/API/notification. This API uses an options object that contains all the notification information. This object is directly passed from the IRealtimeRequest.Options property. Some helper methods have been provided to help configure this options object, for example the body and the icon of the notification.

Sending confirmation e-mails

Important

For SendConfirmationEmailAsync to work, you need to set EnableConfirmationMail to true in the settings.

Sending confirmation e-mails to users can be done using ids or usernames:

await MClient.Notifications.SendConfirmationEmailAsync("DemoUser");

This will send an e-mail to the specified user containing a secure link to activate their account.

Can we improve this article ? Provide feedback