Email Notifications

The Sudo Platform Email Service sends push notifications on receipt of each email message to registered devices. These notifications contain metadata about the received email message encrypted using the public key registered with the email address that received the message.

There are three aspects to adding Sudo Platform Email Service push notification support to your application:

1. Notification registration This aspect records your application's interest in Sudo Platform Email Service notifications with the Sudo Platform Notification Service.

2. Notification configuration This aspect allows you to configure filtering of specific notifications. In particular, Sudo Platform Email SDK allows you to enable and disable transmission of message received notifications for particular email addresses.

3. Notification reception This aspect allows you to decrypt the push notification payload and decide how to render the information in a notification displayed to the user.

Notification Registration

Registering for notifications is performed using the Sudo Platform Notification SDK. Each platform has a slightly different way of doing this. See the platform specific descriptions below for the specific way required to integrate notifications for a particular language environment.

iOS

The Sudo Notification Platform SDK for iOS takes as input aNotificationFilterClient provided by each Sudo Platform service that an application will receive notifications for. Each service's SDK provides a service specific filter client for this purpose.

The Sudo Platform Email Service SDK for iOS provides the DefaultSudoEmailNotificationFilterClient . The following sample code shows how this is registered with the Sudo Platform Notification Client SDK for iOS.

import SudoNotification
import SudoEmail

let emailNotificationFilterClient = DefaultSudoEmailNotificationFilterClient()

let notificationClient = try DefaultSudoNotificationClient(
  userClient: userClient,
  notifiableServices: [emailNotificationFilterClient]
)

Android

The Sudo Notification Platform SDK for Android takes as input aSudoNotificationClient provided by each Sudo Platform service that an application will receive notifications for. Each service's SDK provides a service specific notification client for this purpose.

The Sudo Platform Email Service SDK provides the SudoEmailNotificationClient . The following sample code shows how this is registered with the Sudo Platform Notification Client SDK within the context of your android.app.Application:

import com.sudoplatform.sudoemail.SudoEmailClient
import com.sudoplatform.sudoemail.SudoEmailNotifiableClient
import com.sudoplatform.sudologging.AndroidUtilsLogDriver
import com.sudoplatform.sudologging.LogLevel
import com.sudoplatform.sudologging.Logger
import com.sudoplatform.sudonotification.SudoNotificationClient
import com.sudoplatform.sudouser.SudoUserClient

val logger = Logger("my-sudo-platform-application", AndroidUtilsLogDriver(LogLevel.DEBUG))

val sudoUserClient = SudoUserClient.builder(this)
    .setNamespace("my-sudo-platform-application")
    .setLogger(logger)
    .build()

val sudoEmailNotifiableClient = SudoEmailNotifiableClient.builder()
    .setContext(this)
    .setNotificationHandler(notificationHandler)
    .build()

val sudoNotificationClient = SudoNotificationClient.builder()
    .setContext(this)
    .setSudoUserClient(sudoUserClient)
    .setLogger(logger)
    .setNotifiableClients(listOf(sudoEmailNotifiableClient))
    .build()

The notificationHandler is an instance of a SudoEmailNotificationHandler that you will write to handle reception of Sudo Platform Email Service notifications. See Notification Reception for information on writing a SudoEmailNotificationHandler for your application.

Notification Configuration

Before your application will receive Sudo Platform Email Service notifications, you must enable them for the device's notification configuration. In addition to that you may choose to allow suppression sending of notifications for particular email addresses. Both of these tasks are accomplished with extensions to the Sudo Platform Notification SDK NotificationConfiguration class.

Enabling Sudo Platform Email Notifications

The .initEmailNotifications extension is used to ensure a NotificationConfiguration object includes registering interest in all the notification types sent by the Sudo Platform Email Service.

This operation is non-destructive if other services' notification configuration is also present. It is also non-destructive to any email address specific configuration that may already be present in the notification configuration object.

iOS

import SudoNotification
import SudoEmail

var configuration = NotificationConfiguration(configs: [])
do {
    configuration = try await sudoNotificationClient
        .getNotificationConfiguration(device: device)
} catch let error as SudoNotificationError {
    // Tolerate .notFound error
    guard case .notFound = error else {
        // Handle error
    }
}

// Ensure Sudo Platform Email Service notifications are enabled
configuration = configuration.initEmailNotifications()

let services = sudoNotificationClient.notifiableServices.map { $0.getSchema() }

do {
    configuration = try await sudoNotificationClient.setNotificationConfiguration(
        config: NotificationSettingsInput(
            bundleId: "<bundle-identifier>",
            deviceId: "<device-identitifier>",
            filter: configuration.configs,
            services: services
        )
    )
} catch {
   // Handle error
}

Android

import com.sudoplatform.sudonotification.SudoNotificationClient

val configuration =
    try {
        // Retrieve this device's current configuration and ensure it is
        // initialized to receive email notifications
        sudoNotificationClient
            .getNotificationConfiguration(deviceInfo)
            .initEmailNotifications()
    } catch (e: SudoNotificationClient.NotificationException.NoDeviceNotificationException) {
        // If there is no current configuration, set default configuration which enables
        // all notifications
        NotificationConfiguration(configs = emptyList())
            .initEmailNotifications()
    }

sudoNotificationClient.setNotificationConfiguration(
    NotificationSettingsInput(
        bundleId = "<bundle-identitifier>",
        deviceId = "<device-identifier>",
        services = listOf(sudoEmailNotifiableClient.getSchema()),
        filter = configuration.configs,
    ),
)

Managing notification configuration for specific Sudos

Whether or not notifications for email addresses associated with a particular Sudo are sent by the Sudo Platform Email Service can be controlled by adjusting the notification configuration for the device.

Whether or not notifications are currently enabled for a particular Sudo can be determined as follows for each platform:

iOS

import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

if configuration.areNotificationsEnabled(
       forSudoWithId: sudoId
   ) {
   // Notifications are enabled
} else {
   // Notifications are not enabled
}

Android

import com.sudoplatform.sudoemail.isEmailNotificationForSudoIdEnabled
import com.sudoplatform.sudonotification.types.NotificationConfiguration

val configuration: NotificationConfiguration

if (configuration.isEmailNotificationForSudoIdEnabled(sudoId)) {
   // Notifications are enabled
} else {
   // Notifications are not enabled
}

Notifications can be enabled or disabled for a particular Sudo by modifying and updating the NotificationConfiguration for the device:

iOS

import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

let newConfiguration = configuration.setEmailNotificationsForSudoId(
    sudoId: sudoId,
    enabled: true or false
)

try await notificationClient.setNotificationConfiguration(
    config: NotificationSettingsInput(
        bundleId: "<bundle-id>",
        deviceId: "<device-id>",
        filter: newConfiguration.configs,
        services: [sudoEmailNotificationFilterClient.getSchema()]
    )
)

Android

import com.sudoplatform.sudoemail.setEmailNotificationsForSudoId
import com.sudoplatform.sudonotification.types.NotificationConfiguration

val configuration: NotificationConfiguration

val newConfiguration = configuration.setEmailNotificationsForSudoId(
    sudoId = sudoId,
    enabled = true or false
)

// Call setNotificationConfiguration in IO context
sudoNotificationClient.setNotificationConfiguration(
    NotificationSettingsInput(
        bundleId = "<bundle-id>",
        deviceId = "<device-id>",
        services = listOf(sudoEmailNotifiableClient.getSchema()),
        filter = newConfiguration.configs,
    ),
)

Managing notification configuration for specific email addresses

Whether or not notifications that pertain to a particular email address are sent by the Sudo Platform Email Service can be controlled by adjusting the notification configuration for the device.

Whether or not notifications are currently enabled for a particular email address can be determined as follows for each platform:

iOS

import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

if configuration.areNotificationsEnabled(
       forEmailAddressWithId: emailAddressId
   ) {
   // Notifications are enabled
} else {
   // Notifications are not enabled
}

Android

import com.sudoplatform.sudoemail.isEmailNotificationForAddressIdEnabled
import com.sudoplatform.sudonotification.types.NotificationConfiguration

val configuration: NotificationConfiguration

if (configuration.isEmailNotificationForAddressIdEnabled(emailAddressId)) {
   // Notifications are enabled
} else {
   // Notifications are not enabled
}

Notifications can be enabled or disabled for a particular email address by modifying and updating the NotificationConfiguration for the device:

iOS

import SudoNotification
import SudoEmail

let configuration: NotificationConfiguration

let newConfiguration = configuration.setEmailNotificationsForAddressId(
    emailAddressId: emailAddressId,
    enabled: true or false
)

try await notificationClient.setNotificationConfiguration(
    config: NotificationSettingsInput(
        bundleId: "<bundle-id>",
        deviceId: "<device-id>",
        filter: newConfiguration.configs,
        services: [sudoEmailNotificationFilterClient.getSchema()]
    )
)

Android

import com.sudoplatform.sudoemail.setEmailNotificationsForAddressId
import com.sudoplatform.sudonotification.types.NotificationConfiguration

val configuration: NotificationConfiguration

val newConfiguration = configuration.setEmailNotificationsForAddressId(
    emailAddressId = emailAddressId,
    enabled = true or false
)

// Call setNotificationConfiguration in IO context
sudoNotificationClient.setNotificationConfiguration(
    NotificationSettingsInput(
        bundleId = "<bundle-id>",
        deviceId = "<device-id>",
        services = listOf(sudoEmailNotifiableClient.getSchema()),
        filter = newConfiguration.configs,
    ),
)

Notification Reception

Sudo Platform notification messages contain encrypted content that needs to be decoded. The specific ways that notifications are received and decoded is platform specific. See the platform specific sections below for information on receiving and decoding Sudo Platform Email Service notifications.

iOS

On iOS, in order to decode the notification you must implement a notification service app extension as described in Modifying content in newly delivered notifications in the iOS developer documentation. This allows you to use information in the encrypted payload of the notification to modify the notification for display to the user.

If you receive notifications from other sources, you must first determine the source of the notification.

The Sudo Platform Notification SDK for iOS provides a DefaultSudoNotifiableClient class that decodes all Sudo Platform notifications. It is initializes with a service SDK specific implementation of SudoNotifiableClient. The Sudo Platform Email SDK provides DefaultSudoEmailNotifiableClient for this purpose.

To initialize the DefaultSudoNotifiableClient to decode email service notifications, do the following within your UNNotificationServiceExtension implementation's didReceive method.

Separate SudoNotificationExtension and SudoEmailNotificationExtension PODs are provided containing the minimal code needed to implement the notification service app extension with minimal overhead.

import SudoNotificationExtension
import SudoEmailNotificationExtension

class MyNotificationServiceExtension: UNNotificationServiceExtension {

    override func didReceive(
        _ request: UNNotificationRequest,
        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
    ) {

    let bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)
    guard let bestAttemptContent = bestAttemptContent else {
        contentHandler(request.content)
        return
    }

    let sudoEmailNotifiableClient = DefaultSudoEmailNotifiableClient(keyNamespace: "eml")
    let sudoNotifiableClient = try DefaultSudoNotifiableClient(
        notifiableClients: [sudoEmailNotifiableClient]
    )

The keyNamespace specified in the construction of the DefaultSudoEmailNotifiableClient must match the keyNamespace you use to construct DefaultSudoEmailClient in the main application. If the key namespaces do not match then the DefaultSudoEmailNotifiableClient will not be able to access the keys needed to decrypt the notification payload.

To access the keys, the application and the notification service app extension must both have the Keychain Sharing capability and have the same Keychain group.

Once you have initialized the DefaultSudoNotifiableClient you can then extract any Sudo Platform notification data from the notification. If no data is extracted then the notification has come from a source other than a Sudo Platform service.

    guard let sudoNotificationData = sudoNotifiableClient.extractData(
        fromNotificationContent: bestAttemptContent
    ) else {
        // Handle non-Sudo Platform notification
    }

Once you have identified the notification as originating at a Sudo Platform service, you can then decode it to a specific notification class:

    switch sudoNotifiableClient.decodeData(data: sudoNotificationData) {
    case let decoded as EmailMessageReceivedNotification:
        // handle EmailMessageReceivedNotification
    case let decoded as ....
        // handle other Sudo Platform notification
    }

Android

On Android, a SudoEmailNotificationHandler specific to your application is required to be implemented.

This class will contain method of the form on<notification-type> for each type of notification your application is interested in handling.

An instance of this class is passed to SudoEmailNotifiableClient when it is constructed as part of initializing the SudoNotificationClient. See Notification Registration.

Within your application's FirebaseMessagingService implementation you call the SudoNotificationClient's process method to examine the notification payload, extract any Sudo Platform notification payload, decrypt and decode it, and then pass it to the appropriate registered SudoNotifiableClient.

class MyFirebaseMessagingService implements FirebaseMessagingService {
    override fun onMessageReceived(message: RemoteMessage) {
        sudoNotificationClient.process(message)
    }
}

Notification Types

The Sudo Platform Email Service supports the following notification types

EmailMessageReceivedNotification

Sent on receipt of an email message, this notification contains metadata about the message that was received.

Property	Description
emailAddressId	ID of the email address to which the notification pertains
sudoId	ID of the Sudo owner of the email address to which the notification pertains
messageId	ID of the message to which the notification pertains
folderId	ID of the folder in which the message to which the notification pertains is stored
encryptionStatus	End-to-end encryption status of the message to which the notification pertains
subject	Subject, if any, of the message to which the notification pertains
from	Sender of the message to which the notification pertains
replyTo	Reply-To address, if any, of the message to which the notification pertains
hasAttachments	Whether or not the message to which the notification pertains has any attachments
sentAt	Date when the message to which the notification pertains was sent - the message's Date header
receivedAt	Date when the message to which the notification pertains was received