How to Send an Email from an Integration Service¶

What you'll build¶

When you integrate the systems in your organization, it is also necessary to integrate with third-party systems and their capabilities to enhance your services. WSO2 Micro Integrator uses Connectors for the purpose of referring the APIs of third-party systems.

In this tutorial, when a client sends an appointment reservation request to the Micro Integrator, the client should receive an email confirming the appointment reservation details. To build this use case, you can add an Email connector to the mediation flow.

Let's get started!¶

Step 1: Set up the workspace¶

You need Visual Studio Code (VS Code) with the Micro Integrator for VS Code extension installed.

Info

See the Install Micro Integrator for VS Code documentation to learn how to install Micro Integrator for VS Code.

Step 2: Develop the integration artifacts¶

Create an integration project¶

The Integration project will contain all the required artifacts for the integration solution.

Launch VS Code with the Micro Integrator extension installed.
Click on the Micro Integrator icon on the Activity Bar of the VS Code editor.
Click Create New Project on Design View.

Next, the Project Creation Form will be opened.
In the Project Creation Form, enter EmailConnectorTutorial as the Project Name.
Provide a location under Select Project Directory.
Click Create.

Now let's start designing the integration by adding the necessary artifacts.

Create an HTTP connection¶

Navigate to the Project Overview page.
Click on Add artifact.

Click + View More under Create an Integration.
Select Connections under Other Artifacts to open the Connector Store Form.
Select Http. You need to add dependencies to the project, if not added yet.

In the Add New Connection form, specify the following values to create the new HTTP connection.

Property	Value	Description
Connection Name	`HospitalServicesConn`	The name of the connection.
Base URL	`http://localhost:9090`	The base of the request URL for the back-end service.

Create an email connection¶

Navigate to the Project Overview page.
Click on Add artifact.
Click + View More under Create an Integration.
Select Connections under Other Artifacts to open the Connector Store Form.
From the available connections for the email connector, select SMTPS. You need to add dependencies to the project, if not added yet.

In the Add New Connection form, specify the following values to create a new SMTPS connection.

Tip

If you have enabled 2-factor authentication, an app password should be obtained as instructed here.

Property	Description
Connection Name	Enter `smtpsconnection`
Host	Enter `smtp.gmail.com`
Port	Enter `465`
Username	Enter your email address
Password	Enter your email password
Require TLS	Select `false`

Create the REST API¶

Navigate to the Project Overview page.
Click on Add artifact.
Select APIs under Create an Integration to open the API Form.

Specify values for the required REST API properties:

Property	Value	Description
Name	`HealthcareAPI`	The name of the REST API.
Context	`/healthcare`	Here you are anchoring the API in the `/healthcare` context. This will become part of the name of the generated URL used by the client when sending requests to the Healthcare service. For example, setting the context to `/healthcare` means that the API will only handle HTTP requests where the URL path starts with `http://host:port/healthcare.`

Click Create. This will open the Service Designer interface.

You can now start configuring the API resource.
Click on the GET API resource under Available resources on the Service Designer.

You will now see the graphical view of the HealthcareAPI with its default API Resource.
Click the Edit icon to edit the API resource.

Specify values for the required resource properties:

Property	Description
Resource Path	`/categories/{category}/reserve` This defines the request URL format. In this case, the full request URL format is `http://host:port/categories/{category}/reserve` where `{category}` is a variable.
Methods	`POST` This defines that the API resource only handles requests where the HTTP method is POST.

Click Update.

Update the mediation flow¶

You can now start updating the API resource with the mediation flow.

Navigate to the MI Project Explorer > APIs > HealthcareAPI > /categories/{category}/reserve.
To add Variable mediator click + icon in the design view and select Variable mediator from the palette. This is used to extract the hospital name that is sent in the request payload.

With the Variable mediator selected, specify the details given below.

Property	Value	Description
Action	`set`	The variable action.
Name	`hospital`	The name that will be used to refer to this variable's values.
Action	`set`	The variable action.
Data Type	STRING	The data type of the variable.
Value (Expression)	`payload.hospital_id`	Click the Ex button in the Value field towards the end. This specifies the value type as an expression. Enter `payload.hospital_id` as the expression value. Note: This is the synapse expression that will extract the hospital from the request payload.
Description	Get hospital name

Click Submit.
Add another Variable Mediator by clicking + after the previously added variable mediator and select Variable Mediator from the palette. This is used to extract the patient's email address.

With the variable mediator selected, specify the details given below.

Property	Description
Action	Enter `set`.
Name	Enter `email_id`.
Action	Enter `set`.
Data Type	STRING
Value	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `payload.patient.email` to overwrite the default expression.
Description	Get Email ID

Click on the + icon in the sequence after the previously added variable mediator to add a GET operation. From the palette, select Mediators > HTTP > GET operation.

Once the GET operation form is opened, fill in the information in the table below:

Field	Value	Description
Connection	`HospitalServiceConn`	The connection to be used to execute the operation.
Relative Path	`/ ${vars.hospital}/categories/$ /reserve`	Indicates the relative path added to the base URL of the connection. In this case, the variable 'category' that needs to be included in the request is accessed as `{params.uriParams.category}` in the relative path.

Click Submit.

Note

The following response will be returned from GrandOakEP, ClemencyEP, or PineValleyEP:

{"appointmentNumber":1,   "doctor":
    {"name":"thomas collins",
             "hospital":"grand oak community hospital",
             "category":"surgery","availability":"9.00 a.m - 11.00 a.m",
             "fee":7000.0},
       "patient":
           {"name":"John Doe",
            "dob":"1990-03-19",
            "ssn":"234-23-525",
            "address":"California",
            "phone":"8770586755",
            "email":"[email protected]"},
       "fee":7000.0,
       "confirmed":false}

Add another Variable mediator just after the GET operation to retrieve and store the response sent from HospitalService endpoint. This will be used within the body of the email.

With the variable mediator selected, specify the details given below.

Property	Description
Name	Enter `hospital_response`.
Action	Enter `set`.
Data Type	STRING
Value	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `payload` to overwrite the default expression.
Description	Get Hospital Response

Click + icon below the previously added variable mediator and add the Send operation from the Email connector.
With the Send operation selected, specify the following details in the property tab.

Specify the following details in the property tab;

Property	Description
Connection	Select the created `smtpsconnection` from the drop-down list.
From	Enter your email address as the value. This will be the account from which the email is sent.
Personal Name	Enter personal name of the person who is sending the email.
To	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `vars.email_id` as the value. This retrieves the patient's email address, which was stored in the relevant variable mediator.
Subject	Enter `Appointment Status` as the value. This is the subject line in the email that is sent out.
Content	Click the Ex button in the Value field towards the end. This specifies the value type as expression. Enter `vars.hospital_response` as the value. This retrieves the payment response that was stored in the relevant variable mediator.

Add a Respond mediator to end the sequence processing.

We have now finished creating all the required artifacts.

Step 3: Build and run the artifacts¶

Prerequisites

Before you begin, install Micro Integrator on your machine:

Go to the WSO2 Micro Integrator web page, click Download, provide necessary details, and then click Zip Archive to download the Micro Integrator distribution as a ZIP file.
Extract the ZIP file. The extracted folder will be referred as the <MI_HOME> folder.

Once you have downloaded and set up the Micro Integrator locally, follow the steps given below. Use one of the below two methods.

Click on the Command Palette on the top of the VS Code.
Type > to show the available commands.
Select MI: Add MI server.
Select Add MI server.
Select the folder where <MI_HOME> is located. This wll be set as the current server path.
Run the project.

Click the Build and Run icon located in the top right corner of the VS Code.

The artifacts will be deployed in the embedded Micro Integrator and the server will start.

See the startup log in the Console tab.
See the URLs of the deployed services and APIs in the Runtime Services tab.

Step 4: Test the use case¶

Let's test the use case by sending a simple client request that invokes the service.

Start the back-end service¶

Download the JAR file of the back-end service from here.
Open a terminal, and navigate to the location where you saved the back-end service.
Execute the following command to start the service:
```
java -jar Hospital-Service-JDK11-2.0.0.jar
```

Send the client request¶

Let's send a request to the API resource. You can use Postman or any other HTTP Client. Make sure you provide a valid email address so that you can test the email being sent to the patient.

Open the Postman application. If you do not have the application, download it from here : Postman

Add the request information as given below and click the Send button.

Method	`POST`
Headers	`Content-Type=application/json`
URL	`http://localhost:8290/healthcare/categories/surgery/reserve` The URI-Template format that is used in this URL was defined when creating the API resource: `http://:/categories/{category}/reserve`.
Body	`{ "patient": { "name": "John Doe", "dob": "1940-03-19", "ssn": "234-23-525", "address": "California", "phone": "8770586755", "email": "[email protected]", "cardNo": "7844481124110331" }, "doctor": "thomas collins", "hospital_id": "grandoaks", "hospital": "grand oak community hospital", "appointment_date": "2025-04-02" }` This JSON payload contains details of the appointment reservation, which includes patient details, doctor, hospital, and data of appointment.

If you want to send the client request from your terminal:

Install and set up cURL as your REST client.

Create a JSON file named request.json with the following request payload.

{
  "patient": {
  "name": "John Doe",
  "dob": "1940-03-19",
  "ssn": "234-23-525",
  "address": "California",
  "phone": "8770586755",
  "email": "[email protected]",
  "cardNo": "7844481124110331"
  },
  "doctor": "thomas collins",
  "hospital_id": "grandoaks",
  "hospital": "grand oak community hospital",
  "appointment_date": "2025-04-02"
}

Open a command line terminal and execute the following command from the location where the request.json file you created is saved:

curl -v -X POST --data @request.json http://localhost:8290/healthcare/categories/surgery/reserve --header "Content-Type: application/json"

Analyze the response¶

An email will be sent to the provided patient email address with the following details:

Subject: Appointment Status
             
Message: 
    {
        "appointmentNumber": 1,
        "doctor": {
            "name": "thomas collins",
            "hospital": "grand oak community hospital",
            "category": "surgery",
            "availability": "9.00 a.m - 11.00 a.m",
            "fee": 7000.0
        },
        "patient": {
            "name": "John Doe",
            "dob": "1940-03-19",
            "ssn": "234-23-525",
            "address": "California",
            "phone": "8770586755",
            "email": "[email protected]"
        },
        "fee": 7000.0,
        "confirmed": false
    }

You have now explored how to import the Email connector to the Micro Integrator and then use the connector operations to send emails.