Email Connector Example¶

Email Connector can be used to perform operations using protocols SMTP, IMAP, and POP3.

What you'll build¶

This example explains how to use Email Connector to send an email and retrieve the same email from Gmail. The user sends a payload with the recipients and content of the email. Then, by invoking another API resource, the content of the sent email will be retrieved.

The example consists of an API named EmailConnector API with two resources send and retrieve.

/send: The user sends the request payload which includes the recipients, content, and attachments of the email. This request is sent to the integration runtime by invoking the EmailConnector API. It will send the email to the relevant recipients.
/retrieve: The user sends the request payload, containing the filter to search the received email. This request is sent to the integration runtime where the EmailConnector API resides. Once the API is invoked, it returns the filtered emails.

If you do not want to configure this yourself, you can simply get the project and run it.

Set up the integration project¶

Follow the steps in the create integration project guide to set up the Integration Project.

Create the integration logic¶

Select Micro Integrator and click on + in APIs to create a REST API.
Provide the API name as EmailConnector and the API context as /emailconnector. Once we create the API there will be a default resource created and it can be deleted as given below.
First, we will create the /send resource. This API resource will retrieve information from the incoming HTTP post request such as recipients and content. Create the email and send it to the mentioned recipients.
Select the EmailConnector API and go to Open Service Designer. Click on the + Resource to add an API resource. We use a URL template called /send as we have two API resources inside a single API. The method will be Post.
In this operation, we are going to receive the following inputs from the user.
- from - Sender of the email.
- to - Recipient of the email.
- subject - Subject of the email.
- content - Content to be included in the email.
- contentType - Content Type of the email
Click on the yellow color highlighted + mark. In the pop-up window, go to the email connector in the Connectors tab and select the send operation.
Create a connection by clicking on the 'Add new connection' in the pop-up window as shown below. It will appear a new pop-up window.

In the pop-up window, the following parameters must be provided.
- Connection Name - A unique name to identify the connection by.
- Connection Type - Type of the connection that specifies the protocol to be used.
- Host - Host name of the mail server.
- Port - The port number of the mail server.
- Username - Username used to connect with the mail server.
- Password - Password to connect with the mail server.
Additionally, for SMTP Secure Connection, the following parameter is also required.
- Require TLS
The following values can be provided to connect to Gmail.
- Connection Name - smtpsconnection
- Connection Type - SMTPS
- Host - smtp.gmail.com
- Port - 465
- Username - <your_email_address>
- Password - <your_email_password>
  
  NOTE: If you have enabled 2-factor authentication, an app password should be obtained as instructed here.
- Require TLS - false
After the connection is successfully created, select the created connection as Connection from the drop-down in appeared window after going into the email connector and select the send operation.
Next, provide the expressions below to the following properties in the properties window to obtain respective values from the JSON request payload.
- to - json-eval($.to)
- from - json-eval($.from)
- subject - json-eval($.subject)
- content - json-eval($.content)
- contentType - json-eval($.contentType)
Add the Respond Mediator to respond to the response from sending the email as shown below.
Create the next API resource, which is /retrieve by following the same steps previously. This API resource will retrieve filters from the incoming HTTP post request from which to filter the email messages such as the subject, retrieve the emails, retrieve the email body, and respond. This will be used to retrieve the email we just sent. This will also be a POST request.
Add the list operation of the Email Connector similar to step 5.
Next, we will create an IMAP connection to list emails similar to step 6. Following are the values to be provided when creating the connection. Then select the created connection for the list operation similar to step 7.
- Connection Name - imapsconnection
- Connection Type - IMAPS
- Host - imap.gmail.com
- Port - 993
- Username - <your_email_address>
- Password - <your_email_password>
In this operation we are going to receive the following inputs from the user.
- subjectRegex - Subject Regex to filter the email from.
Therefore, provide the expressions below to the following properties in the list operation window to obtain respective values from the JSON request payload similar to step 8.
- Subject Regex : json-eval($.subjectRegex)
We will next iterate the response received and obtain the email content of each email using the getEmailBody operation. To do this, add the Foreach Mediator as shown below entering //emails/email as the Foreach Expression.
Inside the Foreach Mediator, add the getEmailBody operation as shown below providing the //email/index/text() expression as the Email Index.

NOTE: Further, you can use the getAttachment operation to retrieve attachment content if there is any. Refer to the Reference Documentation to learn more.
Next, we will use a Payload Factory Mediator, to add the email content to the same response we received from the list operation and configure the Payload Factory mediator as shown below.

Entered payload:
```
<email>
    <emailID>$1</emailID>
    <to>$2</to>
    <from>$3</from>
    <subject>$4</subject>
    <textContent>$5</textContent>
</email>
```
You can add every parameter following similar steps given below.

Here, you may observe that we are obtaining the TEXT_CONTENT property which is set when getEmailBody is invoked to retrieve the email content. You can find the list of similar properties set in this operation here.
Add a Property Mediator and set the Property name as 'messageType' and the value as application/json. This is added so that the response will be in JSON.
Finally, add a Respond Mediator after the 'foreach' mediator to respond to the response of retrieved emails.

You can find the complete API XML configuration below. You can go to the source view and copy-paste the following config.

<?xml version="1.0" encoding="UTF-8"?>
<api context="/emailconnector" name="EmailConnector" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="POST" uri-template="/send">
        <inSequence>
            <email.send configKey="smtpsconnection">
                <from>{json-eval($.from)}</from>
                <to>{json-eval($.to)}</to>
                <subject>{json-eval($.subject)}</subject>
                <inlineImages>[]</inlineImages>
                <content>{json-eval($.content)}</content>
                <contentType>{json-eval($.contentType)}</contentType>
                <encoding>UTF-8</encoding>
                <contentTransferEncoding>Base64
                </contentTransferEncoding>
            </email.send>
            <respond/>
        </inSequence>
        <faultSequence>
        </faultSequence>
    </resource>
    <resource methods="POST" uri-template="/retrieve">
        <inSequence>
            <email.list configKey="imapsconnection">
                <folder>Inbox</folder>
                <deleteAfterRetrieve>false</deleteAfterRetrieve>
                <offset>0</offset>
                <limit>10</limit>
                <subjectRegex>{json-eval($.subjectRegex)}</subjectRegex>
            </email.list>
            <foreach expression="//emails/email" id="">
                <sequence>
                    <email.getEmailBody>
                        <emailIndex>{//email/index/text()}</emailIndex>
                    </email.getEmailBody>
                    <payloadFactory media-type="xml" template-type="default">
                        <format>
                            <email>
                                <emailID>$1</emailID>
                                <to>$2</to>
                                <from>$3</from>
                                <subject>$4</subject>
                                <textContent>$5</textContent>
                            </email>
                        </format>
                        <args>
                            <arg expression="//email/emailID" evaluator="xml"/>
                            <arg expression="//email/to" evaluator="xml"/>
                            <arg expression="//email/from" evaluator="xml"/>
                            <arg expression="//email/subject" evaluator="xml"/>
                            <arg expression="$ctx:TEXT_CONTENT" evaluator="xml"/>
                        </args>
                    </payloadFactory>
                    <property name="messageType" scope="axis2" type="STRING" value="application/json"/>
                </sequence>
            </foreach>
            <respond/>
        </inSequence>
        <faultSequence>
        </faultSequence>
    </resource>
</api>

Export integration logic as a carbon application¶

To export the project, refer to the build and export the carbon application guide.

Get the project¶

You can download the ZIP file and extract the contents to get the project code.

Deployment¶

To deploy and run the project, refer to the build and run guide.

You can further refer to the application deployed through the CLI tool. See the instructions on managing integrations from the CLI.

Test¶

Email send operation¶

Create a file called data.json with the following payload. We will send the email to ourselves so that we can retrieve it later.

{
    "from": "<your-email>@gmail.com",
    "to": "<your-email>@gmail.com",
    "subject": "Sample email",
    "content": "This is the body of the sample email",
    "contentType":"text/plain"
}

Invoke the API as shown below using the curl command. Curl Application can be downloaded from here.
```
curl -H "Content-Type: application/json" --request POST --data @data.json http://localhost:8290/emailconnector/send
```
Expected Response: You should get a 'Success' response as below and you will receive the email.
```
{
    "result": {
        "success": true
    }
}
```

Email list operation¶

Create a file called data.json with the following payload.
```
{
    "subjectRegex":"Sample email"
}
```

Invoke the API as shown below using the curl command.

curl -H "Content-Type: application/json" --request POST --data @data.json http://localhost:8290/emailconnector/retrieve

Expected Response: You should get a response like below.

{
    "emails": {
        "email": [
            {
                "emailID": "<[email protected]>",
                "to": "<your-email>@gmail.com",
                "from": "<your-email>@gmail.com",
                "subject": "Sample email",
                "textContent": "This is the body of the sample email"
            }
        ]
    }
}

What's next¶

To customize this example for your own scenario, see Email Connector Configuration documentation for all operation details of the connector.