Sending emails

Introduction

NOUMENA Cloud supports sending emails from NPL applications through a dedicated Email Sender connector. This guide will help you set up the Email Sender and integrate it with your NOUMENA Cloud application.

Getting Started

To get started with the Email Sender, you need to enable it in your NOUMENA Cloud application. Once enabled, you can configure the SMTP server settings and implement the necessary logic in NPL to send emails.

Dependencies

The npl-connectors-library needs to be added as a dependency to the NPL project. See the Contributor library getting started for more information.

Here is an example of how to add the dependency and unpack the library using Maven:

<!-- pom.xml -->
<!-- add dependency -->
<!-- Check the available versions at: https://central.sonatype.com/artifact/com.noumenadigital.contrib/npl-connectors-library/versions -->
<dependencies>
  <!--...-->
  <dependency>
    <groupId>com.noumenadigital.contrib</groupId>
    <artifactId>npl-connectors-library</artifactId>
    <version>1.0.21</version>
  </dependency>
</dependencies>
<!-- unpack library -->
<build>
  <plugins>
    <!--...-->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-dependency-plugin</artifactId>
      <executions>
        <execution>
          <id>copy-npl-contrib</id>
          <goals>
            <goal>copy-dependencies</goal>
          </goals>
          <phase>generate-sources</phase>
          <configuration>
            <outputDirectory>${project.build.directory}/contrib</outputDirectory>
            <includeGroupIds>com.noumenadigital.contrib</includeGroupIds>
            <includeArtifactIds>npl-connectors-library</includeArtifactIds>
            <overWriteIfNewer>true</overWriteIfNewer>
          </configuration>
        </execution>
        <execution>
          <id>unzip-contrib-libs</id>
          <goals>
            <goal>unpack-dependencies</goal>
          </goals>
          <phase>generate-sources</phase>
          <configuration>
            <outputDirectory>${project.build.directory}/classes</outputDirectory>
            <includeArtifactIds>npl-connectors-library</includeArtifactIds>
            <fileMappers>
              <fileMapper implementation="org.codehaus.plexus.components.io.filemappers.RegExpFileMapper">
                <pattern>npl-connectors-library-.*/connector</pattern>
                <replacement>connector</replacement>
              </fileMapper>
            </fileMappers>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Configuring the Email Sender

The Email Sender can be enabled in your NOUMENA Cloud application by navigating to the services section in the NOUMENA Cloud portal and toggling the Email Sender service on. This will allow you to use the Email Sender for sending emails directly from your NPL applications.

Once the Email Sender is enabled, you can configure the SMTP server settings in the NOUMENA Cloud portal.

The following settings are available:

Setting	Description
Host	The hostname of the SMTP server (e.g. smtp.example.com)
Port	The port of the SMTP server (e.g. 587)
TLS enabled	Whether to use TLS for the connection
Username	The username for authenticating with the SMTP server
Password	The password for authenticating with the SMTP server

Using the Email Sender in NPL

To use the Email Sender in your NPL applications, you need to implement the necessary logic to send emails and handle the result. The Email Sender uses the standard NPL notify-resume pattern, following the same principle as the HTTP bridge.

Email messages and results

Once the Email Sender is configured, you can use it in your NPL applications. The Email Sender provides a set of APIs that can be used to send emails using the standard NPL notify-resume pattern. It provides the following types of messages:

• SendEmailNotification: Used to send an email via the configured SMTP server.

notify SendEmailNotification(emailAddress, subject, body) resume emailCallback;

Email sending execution

use connector.v1.email.SendEmailNotification;
use connector.v1.email.SendEmailResponse;

protocol[emailService] EmailServiceProtocol() {
    @api
    permission[emailService] sendEmail(recipientName: Text) {
        var emailAddress = "john.doe@example.com";
        var subject = "Hello world";
        var body = "Hi " + recipientName + ",\n\nWelcome to this tutorial!";
        notify SendEmailNotification(emailAddress, subject, body) resume emailCallback;
    }

    @api
    permission[emailService] emailCallback(r: NotifyResult<SendEmailResponse>) {
        info("Received email callback for participant: " + r.toText());
        match(r) {
            is NotifySuccess<SendEmailResponse> -> {
                var emailResponse = r.result;
                var errorCodeText = if (emailResponse.errorCode.isPresent()) " (" + emailResponse.errorCode.getOrFail() + ")" else "";
                var detailsText = if (emailResponse.details.isPresent()) ": " + emailResponse.details.getOrFail() else "";
                info("Email sent to " + emailResponse.recipientAddress + " with status: " + emailResponse.status.toText() + errorCodeText + detailsText);
            }
            is NotifyFailure -> {
                info("Failed to send email");
            }
        };
    };
};