Custom web services for emails

Custom web services for emails enable 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 an 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:

  1. 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 > Journey Tools > External connections > +Add button > type Custom Web Service ).
  2. 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.

At runtime, sending an email consists of:

  1. Sending the request : When the Send an email step executes, an HTTP request is sent to the configured web service.
  2. 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 classifiers
        Add classifier
        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:

        Copy
        Copied
        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's 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.