Custom server for emails

Custom email server enables you to connect to an external web service with a REST API for sending emails. This is particularly useful when leveraging an external email service provider for message delivery. Custom web services offer flexibility, allowing for customized requests and responses while integrating seamlessly with other systems.

Configuring a custom web service involves setting up request settings, SSL identities, HTTP connection settings, and logging options. You can also define how responses are handled, including applying transformations or setting fallback behaviors.

Mosaic's Journeys use custom web services for emails through the Send Email step. This step lets you configure an external service to handle parameters like email content and recipient details, and return a response indicating success or failure.

How it works

Configuring a custom web service for sending email involves these steps:

Establishing the connection: The connection to the external web service is set up by configuring connection parameters, such as the request URI, HTTP method, headers, and optional authentication details (Admin Portal > Management > Integration hub > Custom Email Server).
Defining request parameters: Parameters like to (recipient email address), subject (email subject), and text (email body) can be dynamically inserted into different parts of the HTTP request, depending on the use case. These include the Request URI (as URL parameters), the Request Body, or even HTTP Headers. These parameters are defined as variables in the external connection configuration, and their values are passed dynamically from the journey step that invokes this connection.
Enabling the connector

At runtime, sending an email consists of:

Sending the request: When the Send an email step executes, an HTTP request is sent to the configured web service.
Response and handling: The external web service processes the request and returns a response, which Mosaic uses to determine whether the operation succeeded or failed.

Configuration

Request

Field	Description
FORMAT
Name	A unique name for the external connection.
Request URI	The endpoint of the web service that handles email sending (e.g., `http://email.service/send`). This field supports expressions using the parameters: to: recipient email address or group of addresses. subject: the email subject text: email body
HTTP request method	The HTTP method used for the request (e.g., `POST`).
Request Body	Holds the body of the POST requests. Supports the following parameters: to: recipient email address or group of addresses. subject: the email subject text: email body
HTTP request headers	Custom headers included in the request. Allows to set the name and value for the header: e.g., `Content-type: application/json`. Supports the following parameters: to: recipient email address or group of addresses. subject: the email subject text: email body
AUTHENTICATION
Authentication type	Specifies if the connection requires authentication. Supported options: `None`, `Basic`, `Bearer`, `OAuth`, etc.
SSL Identities
Client certificate local identity	Enables the specification of a key for a client certificate used in secure communication. Options include key generation, keystore file upload, and PEM file upload. For each key, you can configure a Key Alias, Key Version, and JWT Key ID.
Trusted identities	Enables the specification of a client certificate for secure communication. Options include PEM file upload, keystore file upload, loading from a URL, or loading a public key from a JWKS URL. For each certificate, you can configure a Certificate Alias and a Certificate Version.
HTTP CONNECTION SETTINGS
Follow Redirect	If enabled, the system will automatically follow an HTTP redirect response (302/303) to the new URL provided by the API. Otherwise, the redirect response will be returned to the client without further action.
Request timeout	Specifies the maximum time, in seconds, that the system will wait for a response before the request times out.
Connection timeout	Specifies the maximum time, in seconds, that the system will wait to establish a connection to the server before timing out.
LOGGING
Log Outgoing Request	Specifies whether and at what level outgoing requests should be logged. Options: `Disable`, `Debug`, `Info`, `Warning`, `Error`.
Log Successful Response	Specifies whether and at what level successful responses should be logged. Options: `Disable`, `Debug`, `Info`, `Warning`, `Error`.
Log Failed Response	Specifies whether and at what level failed responses should be logged. Options: `Disable`, `Debug`, `Info`, `Warning`, `Error`.

Response

Field	Description
Return failure if response is invalid	Enables the option to treat an invalid response as a failure (checkbox).
FORMAT
Response format	Specifies the format of the expected response. Options: `None`, `String`, `JSON Array`, `JSON Object`, `XML`.
Specify JSON schema for response	Allows you to define a JSON schema to validate the response content (checkbox).
Apply transformation on response received from the web service	Enables transformations on the response data before further processing (checkbox).
RESPONSE CLASSIFIERSs
Add classifier	Allows you to define conditions and values to classify responses (e.g., success or failure).
Fallback (for classifiers)	Specifies the fallback response if no classifiers match. Options: `Success`, `Error`.
RATE LIMIT
Limit Rate of Requests	Enables rate limiting for requests (checkbox), with the following configuration options: Span Period (Seconds): Specifies the time period for rate limiting. Max. Requests per Period: Specifies the maximum number of requests allowed in the defined time period.

Request parameters

When configuring the Send an email step, you define the parameters that Mosaic sends to the external web service. These parameters are dynamically mapped to the JSON request body using placeholders (${}), as shown below:

Step Parameter	Mapped to JSON Request Body
Recipients	`"to": "${to}"`
Subject	`"subject": "${subject}"`
Message Body	`"body": "${text}"`

At runtime, these placeholders are replaced with the actual values configured in the Send an email step parameters, and the request is built following the configuration of the web service. For example:

curl -X POST http://email.service/send \ Set in the web service configurations
-H "Content-Type: application/json" \ Set in the web service configurations
-d '{
   "to": "${to}",        \ Replaced with the recipient email address. E.g., admin1@example.com
   "subject": "${subject}", \ Replaced with the email subject. E.g., Security Alert for {appName}
   "body": "${text}"     \ Replaced with the email content. E.g., Alert: A potential security threat has been detected in the {appName} application due to {eventType}. Please investigate immediately.
   }'

The designated web service will then distribute the emails.