Senders

Overview

Senders are used to represent the 'from' identity for email notifications.

A sender can reference a set of email templates to use for subscription-related actions within the same namespace. An example of this would be the confirmation email that is sent when a user first subscribes to a notification group.

How senders work

The sender that is chosen for a given subscription-related action is determined by matching on the namespace and transport type. If multiple matching senders exist, then the sender is selected at random out of those that match.

A sender may also have a set of redirect URLs that will be followed whenever this sender is used to generate notifications that contain links.

For example, consider the scenario where a user follows the unsubscribe link in an email generated by a particular sender. After following the link and after the Notification Service processes the action, the user will be redirected to the URL configured by either the UNSUBSCRIBE_SUCCESS or UNSUBSCRIBE_FAILURE redirect URLs. The URL redirection will be determined by the success or failure of the action.

Sender properties

When you create a sender, the following properties are supported:-

• _namespaces: A string array, which must contain a single item, which is the owning namespace for this sender. The user must have the create permissions in this namespace for the IRN: notificationsvc:sender:* ​​
• _name: An immutable user-friendly name that must be unique within the namespace.
• _description: An optional description.
• _templates: A map of templates to be used for internal subscription-related actions. Currently, only one action is supported - SUBCRIBE_VERIFY. This template is used to generate the initial notification that is sent to a device whenever a subscription is created to a group in the same namespace.
• _redirects: A map of redirect URLs which are followed after specific actions in notifications. The redirect URLs are as follows:
  • SUBSCRIBE_SUCCESS: Redirect after a subscription is accepted.
  • SUBSCRIBE_FAILURE: Redirect if a subscription could not be accepted.
  • UNSUBSCRIBE_SUCCESS: Redirect after a device is unsubscribed from a group.
  • UNSUBSCRIBE_FAILURE: Redirect if a device cannot be unsubscribed from a group.
  • UNSUBSCRIBE_ALL_SUCCESS: Redirect after a device is unsubscribed from all groups.
  • UNSUBSCRIBE_ALL_FAILURE: Redirect if a device cannot be unsubscribed from all groups.
• _transport: Currently, only EMAIL is supported.

The rest of the properties available for a sender depend on the value of the _transport property.

When '_transport' is EMAIL the following properties are supported:

• _email._address: The address from which emails are sent.
• _email._from: The friendly name that will appear in email clients.

Notes on email senders

When creating an email sender, the email address must be one that is enabled in the configured SMTP server for the environment.

Additional originating email addresses can be enabled in the environment's SMTP configuration.

The following properties can be edited once a sender is created:

• _description
• _templates
• _redirects
• _transport (and all transport-specific properties)

Using the Sender API

This section lists some useful examples of using the Notification Service API to perform operations with senders.

For a full reference to the Sender API, refer to the Sender Rest API page.

How to create an email type sender

To create an email type sender with an email address of do-not-reply@xyz_corp.com, refer to the sample code below.

const sender = await IafNotification.createSender({    _namespaces: project._namespaces,    _transport: "EMAIL",    _name: "sender_1",    _email: {      _address: "do-not-reply@xyz_corp.com",      _displayName : "Twinit.dev (INQA1)"    },    _templates: {        "SUBSCRIBE_VERIFY": {            _id: subscribeVerifyTemplate._id        }    },    _redirects: {        "SUBSCRIBE_SUCCESS": "http://example.com/subscribe-success",        "SUBSCRIBE_FAILURE": "http://example.com/subscribe-failure"    }}, ctx);

How to update a sender

To update the address of an email type sender, refer to the example code below. This code updates the email address of a given sender to inqa2-do-not-reply@xyz_corp.com.

const sender = await IafNotification.updateSender(sender._id, {    _email: {      _address: "inqa2-do-not-reply@xyz_corp.com",      _displayName : "Twinit.dev (INQA2)"    },}, ctx);

How to list senders

To list senders, you must provide a query. The query must include at a minimum, a set of namespaces for which the user making the API call, has READ permissions.

The following query properties are supported:

• namespaces
• name
• transport

Note: These properties map to the same properties used when creating or updating templates.

To list senders, refer to the sample code below.

const senders = await IafNotification.listSenders({    namespaces: project._namespaces}, ctx);

Delete senders

To delete senders, refer to the sample code below.

await IafNotification.deleteSender(sender._id, ctx);