Notification Dispatcher System API

8/5/2025

Introduction

The Notification Dispatcher System API is a centralized API that helps you send notifications to multiple channels — Email, Slack, SMS, and WhatsApp — with just one API call.

This removes the need for multiple separate integrations. Instead of calling Email, Slack, or Twilio separately, you send one payload → the API splits it → validates → formats → sends messages to the right channels.

Objective

This API is designed to:

    Send notifications to multiple channels at once (Email, Slack, SMS, WhatsApp).

    Validate each message before sending.

    Process multiple messages in parallel for speed.

   Retry automatically if there’s a temporary failure (e.g., server down).

  Track which channels succeeded or failed.

   Handle errors gracefully with clear logs and structured responses.

STEP1: Designing API specifications in Design Center


What is RAML?

RAML (RESTful API Modeling Language) is a YAML-based format used to design and describe your API contract.
In MuleSoft, RAML is used with APIkit, which automatically:
   → Builds flows and routes for your endpoints

  → Validates incoming requests

  → Generates standard HTTP error codes (400, 404, etc.) if input is wrong

Why do we need RAML?

Design First: RAML acts like a contract — it tells frontend teams and integrators what your API expects before you even build the backend.
Validation: RAML ensures incoming requests match what you designed.
 E.g., if you say channels must be an array, APIkit checks it — no extra code needed!
Mocking: RAML lets you create mock endpoints.


1.  Login to your Anypoint platform account and click on “Start Designing.”


2. Click on create new and select New API Spec.

3. It will open a new window as below. Give a name to your API spec and click on create API specification. It will create a basic structure of API.

4. Write RAML as per your requirement.

RAML project contains:

accelerator-notification-dispatcher-sys-api.raml — main entry point.

DataTypes:

  NotificationType.raml → Defines the main payload: channels, messages

  EmailMessageType.raml → Fields for an Email message

  SlackMessageType.raml → Fields for Slack

  SmsMessageType.raml → Fields for SMS

  WhatsappMessageType.raml → Fields for WhatsApp
 

Traits:
 ErrorResponsesTrait.raml → Defines standard error responses

 PingResponseTrait.raml → For health check

 TrackableTrait.raml → For tracking requests
 

Libraries:

 ResponseTypeLibrary.raml → Reusable response schemas

Examples:
 Example payloads for each channel (EmailMessageExample.raml, etc.)

 Example error responses

Sample input 

{
  "channels": [
    "EMAIL",
    "SLACK"
  ],
  "messages": {
    "Email":     {
            "channelType": "Email",
            "useTemplate": true,
            "recipientEmail": "user@example.com",
            "subject": "✅ Success: 7 Records Processed",
            "content": {
                "heading": "✅ Database Update Successful",
                "summary": "7 records were updated successfully.",
                "description": "The following records were processed without any issues.",
                "details": {
                    "recordIds": "R01,R02,R03,R04,R05,R06,R07",
                    "totalProcessed": 7,
                    "timestamp": "2025-06-27T13:10:00Z"
                }
            }
        },
    "Slack": {
      "channelType": "Slack",
      "channelName": "#alerts",
      "content":    {
                "heading": ":X: Database Update Failed",
                "summary": "3 records failed to update.",
                "description": "The following records encountered errors during processing.",
                "details": {
                    "failedRecords": "R110,R112,R115",
                    "totalFailed": 3,
                    "timestamp": "2025-06-27T13:10:00Z"
                }
            }
  }
}

5. Then click on publish button and select publish to exchange.

6. Go to Exchange, and you can see that a newly created API is published.

 

STEP 2: configuring API in Anypoint studio 

1. Open your anypoint studio and create a new mule project by selecting file>new>mule project.

2. Give a name to your project and click on ‘Download RAML from design centre’.

3. Search for the API you created and select that, and click on add and finish.

4. You can see the new project is scaffolded as follows: Depending upon resource/method, a pair number of flows are created.

5. Next, import the Slack, Twilio, and Email connectors from the Exchange.

Now let’s go over the configuration steps for Slack, Email, and Twilio.

SLACK
Step 1 setup a slack app

1. To send a message to Slack from MuleSoft, you must first create a Slack App. Go to https://api.slack.com and click on Create App.

2. In the next screen, click on From an app manifest.

3. Select the workspace you want to publish the app to and click on Next.

4. In the next step, paste the following over the default app manifest:

display_information:
  name: Codelab Demo App
features:
  bot_user:
    display_name: Codelab Demo App
    always_online: true
oauth_config:
  redirect_urls:
    - http://localhost:8081/callback
    - http://0.0.0.0:8081/callback
    - http://127.0.0.1:8081/callback
  scopes:
    bot:
      - chat:write
      - channels:read
      - incoming-webhook
settings:
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false

5. In the last step, click on Create.


6. Before using the Slack App, it must be installed in a Workspace. Click on Install to Workspace to proceed.

7. Select a channel to allow the app to post to by default and click on Allow.

8. You’ll be redirected to the Basic Information section of your newly created app. In the App Credentials section, make sure to copy the Client ID and Client Secret—you’ll need these later to configure the Slack Connector in Studio.

Step 2 Configure Slack Configuration

1. Let's configure the Send Message component to call Slack.

2. Select the Send Message component. If the Mule Properties tab doesn't appear, click on the Send Message icon, then click the green plus (+) sign to create a new connector configuration.

This is where the bulk of the configuration will be for calling the Slack API.

3. Under the General tab, and in the oauthAuthorizationCode section, fill in the Consumer key: and Consumer secret: field with the Client ID and Client Secret from the previous step from Slack. In the Scopes field, replace the default text with the following:

chat:write

See the screenshot below to see what it should look like.

4. Next, scroll down and find the oauthCallbackConfig section. Fill in the Callback path: and Authorize path: fields to match the following screenshot below.

Callback path:

/callback

Authorize path:

/authorize

External callback url:

http://127.0.0.1:8081/callback


5. Then click on OK to close the screen.

6. Now that everything has been configured, let's run the project , When the project is successfully deployed, switch to your browser and navigate to the following URL:

http://localhost:8081/authorize

7. If configured correctly, you'll be redirected to the Slack workspace screen to allow the app access to the workspace.

8. Once you click on Allow, you'll be redirected to this screen:

EMAIL
Step 1: Enable 2-Step Verification and Generate an App Password

1. Go to your Gmail account settings: https://myaccount.google.com/security
2. Enable 2-Step Verification if it's not already enabled.

3. After enabling it, generate a 16-digit App Password for use in third-party applications (as shown in the diagram below).

Step 2: Add the Email-Send Connector Configure the Connector

1. From the Mule Palette, drag the Email - Send connector into your flow.

General Connection Settings:

Host: smtp.gmail.com

Port: 587

User: Your Gmail address

Password: The 16-digit App Password you generated


Advanced Configuration:

     Go to the Advanced tab.

     In the Properties section, choose Edit inline.

     Add the following property:
             Key: mail.smtp.starttls.enable

             Value: true


TWILIO
Step 1: Set Up Your Twilio Account

1. Visit Twilio and sign up for a free trial account.

2. During setup, you may be prompted for two-factor authentication. You can choose “Set up later” to skip this for now and proceed to the Twilio Console.

3. Once logged in, Get twilio phone number you'll find the following key details on the dashboard:

       Account SID

       Auth Token

       Twilio Phone Number


Note: If the phone number is not visible immediately:

4. Go to the Messages section on the left-hand side.

5. Click on Overview.

6. There, you’ll find options like "Try SMS" and "Try WhatsApp"—these sections will provide trial phone numbers for SMS and WhatsApp messaging.

Step 2 : Configure the Twilio Connector

1. Select the Create Message component.

2. In the Mule Properties tab, click the green plus (+) button to create a new connector configuration.

3. In the configuration window:
       Username: Enter your Account SID

       Password: Enter your Auth Token

4. Click OK to save the configuration.

The setup is complete, let’s proceed with implementing the flows.

Entry Flow — notifications_flow

1. Logs the start of request processing.

2. Uses DataWeave (ValidationUtils) to check channel validity.

3. Splits results into Valid and Invalid messages.

4. Starts Parallel For Each for valid ones.

5. Combines processed and unprocessed results into the final output.

6. Logs the end of processing.

Email Notification Flow (email-notifications)

1. Handles email notifications via SMTP.

2. Dynamically chooses between an HTML template or plain text body.
→ If useTemplate = true:
 Loads a pre-defined HTML email template.
→ If useTemplate = false:
 Falls back to plain text email.

3. Ensures robust error handling with retry logic.

4. In the send mail, the connector details are already configured, and the required details like from address, to address, subject, and content are passed dynamically.


Slack Notification Flow (slack-notifications)

1. This is the flow created for the slack notification.

2. Sends formatted text messages to Slack channels.

3. Includes retry logic and graceful error handling.

4. We have already configured the Slack connector, and we just need to add the message content in the Slack connector component.

Twilio Notification Flow (sms-whatsapp-notifications)

1. This is the flow created to send SMS and WhatsApp notifications.

2. It sends formatted text messages to SMS and WhatsApp channels using the Twilio connector.

3. Before invoking the Twilio connector, we perform the necessary mapping in the Transform Message component:

4. In the Twilio connector, we need to set the Account SID and select the "Create Message" operation to send the message.

STEP 3: Testing

Once the application has been fully developed, it's time to test it. Run the application.

http://localhost:8081/api/notifications

1. Send Email with Template

→ Open Postman and send a POST request to the email notification URL.

In the request body: Set the channels array to ["EMAIL"].

  Under the messages object:
        → Use the key "Email".
        → Set "channelType" to "Email".
        → Set "useTemplate" to true.
 

→ When this request is executed, the email will be sent using the specified template format.

2. Send Email without Template

→ Open Postman and send a POST request to the email notification URL.

In the request body: Set the channels array to ["EMAIL"].

  Under the messages object:
        → Use the key "Email".
        → Set "channelType" to "Email".
        → Set "useTemplate" to false.

→ When this request is executed, the email will be sent as plain text without using any template.

3. Send Message to slack

→ Open Postman and send a POST request URL.

In the request body: Set the channels array to ["SLACK"].

  Under the messages object:
        → Use the key "slack" .
        → Set "channelType" to "Slack".
        → Mention "channelName" to send Message

→ The message will be posted to the configured Slack channel in the format shown below.

4. Send Message to SMS

→ Open Postman and send a POST request URL.

In the request body: Set the channels array to ["SMS"].

  Under the messages object:
        → Use the key "Sms" .
        → Set "channelType" to "Sms".
        → Include the recipient's phone number , sender phone number and message content.

→ This is how the SMS message will be delivered to the recipient.

5. Send Message to WHATSAPP

→ Open Postman and send a POST request URL.

In the request body: Set the channels array to ["WHATSAPP"].

  Under the messages object:
        → Use the key "Whatsapp" .
        → Set "channelType" to "whatsapp".
        → Include the recipient's phone number , sender phone number and message content.

→ The message will be sent via WhatsApp and will appear as shown below.

6. Send Message to All Channels (with some invalid channel names)

→ Open Postman and send a POST request to the notification URL to test how the system handles both valid and invalid channels.

Provide a mix of valid and invalid channel names in the channels array.

  Under the messages object:
        → Valid: "EMAIL", "SLACK"
        → Invalid: "WhattsApp", "SMSs".
        → Under the messages object, provide matching keys and message content.

→ When the request is executed, the system will attempt to process all channels. The valid ones will succeed, and the invalid ones will return appropriate error messages.

Conclusion

With this Notification Dispatcher System API, you can send notifications to multiple platforms in one go, with contract-first design, validation, parallel processing, robust retries, and clean error handling — all in one place.

Recent Blogs