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 inbox email will be retrieved. The example consists of two API 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 for sending email¶ Under the Create an integration section, select API to create a new REST API. Provide the API name as send and the API context as /send. Select the newly created send API and Click the edit icon to change the API method. Then select the POST method and click OK. This will create a new API resource with the context /send and the method POST. First, Let's create a sample payload request to send API. Click on the Start node and select the Add Request option. This will create a new example payload request. 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 Therefore, provide the following JSON payload to the request. { "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" } Now we will add the send operation of the Email Connector to send the email. To do this, we need to add the Email Connector to the integration project. Now, Click on the Add icon and search for the email connector. Select the email connector and click on the Download button. Add a send operation to the integration logic by clicking on the Add icon and selecting the send operation from the list of operations. 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. 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 - GmailConnection 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. Then we need to provide the necessary parameters to the send operation. Since we defined an example request payload, we can use the same parameters to send the email. To do this, click on the Expression icon in the From field and select the Payload option. This will open a new pop-up window where you can select the payload.from parameter from the request payload. Next, do the same for the To, Subject, Content, and ContentType fields. Tick the Overwrite body checkbox in the Output field to overwrite the body of the email with the content provided in the request payload. Add the Respond Mediator to respond to the response from sending the email as shown below. Create the integration logic for retrieving email¶ 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 3. Next, we will create an IMAP connection to list emails similar to step 4. Following are the values to be provided when creating the connection. 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 Subject Regex property in the list operation window. Subject Regex : payload.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 payload.emails as the Foreach Expression. Inside the Foreach Mediator, add the getEmailBody operation as shown below providing the payload.emails 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 Mediator, to add the email content to the same response we received from the list operation and configure the Payload mediator as shown below. Entered payload: {"To":"${payload.email.to}","From":"${payload.email.from}","Subject":"${payload.email.subject}","Content":"${payload.email.textContent}"} Finally, add a Respond Mediator after the 'foreach' mediator to respond to the response of retrieved emails. 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/send Expected Response: You should get a 'success' response as below and you will receive the email. { "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/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.