Skip to content

Email Connector Reference

This documentation provides a reference guide for the Email Connector. The Email Connector allows you to list, send emails and perform other actions such as get body, get attachment,mark email as read, mark email as deleted, delete email and expunge folder on different mailboxes using protocols IMAP, POP3 and SMTP.

Connection Configurations

Email Connector Configuration

The WSO2 MI Email Connector supports multiple email protocols, allowing seamless integration with mail servers.

  • SMTP (Simple Mail Transfer Protocol)
    SMTP is a standard communication protocol used for sending emails between mail servers. It is primarily responsible for the transmission of outgoing messages from email clients to mail servers and between mail servers.

  • SMTPS (Secure SMTP)
    SMTPS is the secure version of SMTP that encrypts email communication using SSL/TLS to enhance security and protect sensitive information from interception during transmission.

  • POP3 (Post Office Protocol v3)
    POP3 is a protocol used to retrieve emails from a mail server. It downloads messages to the local device and typically removes them from the server, making it suitable for single-device email access.

  • POP3S (Secure POP3)
    POP3S is the secure version of POP3, where email retrieval is encrypted using SSL/TLS, ensuring that email data remains protected during transmission.

  • IMAP (Internet Message Access Protocol)
    IMAP is a protocol used for retrieving emails while keeping them stored on the mail server. It allows users to manage emails across multiple devices, providing synchronization between the client and server.

  • IMAPS (Secure IMAP)
    IMAPS is the secure version of IMAP, where email communication is encrypted using SSL/TLS, ensuring that sensitive data remains protected while being accessed or synchronized.

Connection Configuration Parameters

The connection configuration parameters are used to establish a connection with the email server. These parameters are needed to provide based on the protocol you are using.

SMTP

Parameter Name Description Required
connectionName Name of the connection. Yes
host Hostname of the SMTP server. Yes
port Port number of the SMTP server. Yes
requireAuthentication Specifies if authentication is required. Yes
username Username for authentication. No
password Password for authentication. No
Additional parameters for connection
Read Timeout Timeout for reading the response from the server. No
connectionTimeout Timeout for establishing the connection. No
writeTimeout Timeout for writing the request to the server. No
Max Active Connections Maximum number of active connections. No
Max Idle Connections Maximum number of idle connections. No
Max Wait Time Maximum wait time for a connection. No
Min Eviction Time Minimum time before an idle connection is evicted. No
Eviction Check Interval Interval for checking idle connections. No
Exhausted Action Action to take when the connection pool is exhausted. No

SMTPS

Parameter Name Description Required
connectionName Name of the connection. Yes
host Hostname of the SMTPS server. Yes
port Port number of the SMTPS server. Yes
username Username for authentication. Yes
password Password for authentication. Yes
requireTLS Specifies if TLS is required. No
Additional parameters for connection
Read Timeout Timeout for reading the response from the server. No
connectionTimeout Timeout for establishing the connection. No
writeTimeout Timeout for writing the request to the server. No
Max Active Connections Maximum number of active connections. No
Max Idle Connections Maximum number of idle connections. No
Max Wait Time Maximum wait time for a connection. No
Min Eviction Time Minimum time before an idle connection is evicted. No
Eviction Check Interval Interval for checking idle connections. No
Exhausted Action Action to take when the connection pool is exhausted. No

POP3

Parameter Name Description Required
connectionName Name of the connection. Yes
host Hostname of the POP3 server. Yes
port Port number of the POP3 server. Yes
username Username for authentication. Yes
password Password for authentication. Yes
Additional parameters for connection
Read Timeout Timeout for reading the response from the server. No
connectionTimeout Timeout for establishing the connection. No
writeTimeout Timeout for writing the request to the server. No
Max Active Connections Maximum number of active connections. No
Max Idle Connections Maximum number of idle connections. No
Max Wait Time Maximum wait time for a connection. No
Min Eviction Time Minimum time before an idle connection is evicted. No
Eviction Check Interval Interval for checking idle connections. No
Exhausted Action Action to take when the connection pool is exhausted. No

POP3S

Parameter Name Description Required
connectionName Name of the connection. Yes
host Hostname of the POP3S server. Yes
port Port number of the POP3S server. Yes
username Username for authentication. Yes
password Password for authentication. Yes
Additional parameters for connection
Read Timeout Timeout for reading the response from the server. No
connectionTimeout Timeout for establishing the connection. No
writeTimeout Timeout for writing the request to the server. No
Max Active Connections Maximum number of active connections. No
Max Idle Connections Maximum number of idle connections. No
Max Wait Time Maximum wait time for a connection. No
Min Eviction Time Minimum time before an idle connection is evicted. No
Eviction Check Interval Interval for checking idle connections. No
Exhausted Action Action to take when the connection pool is exhausted. No

IMAP

Parameter Name Description Required
connectionName Name of the connection. Yes
host Hostname of the IMAP server. Yes
port Port number of the IMAP server. Yes
username Username for authentication. Yes
password Password for authentication. Yes
Additional parameters for connection
Read Timeout Timeout for reading the response from the server. No
connectionTimeout Timeout for establishing the connection. No
writeTimeout Timeout for writing the request to the server. No
Max Active Connections Maximum number of active connections. No
Max Idle Connections Maximum number of idle connections. No
Max Wait Time Maximum wait time for a connection. No
Min Eviction Time Minimum time before an idle connection is evicted. No
Eviction Check Interval Interval for checking idle connections. No
Exhausted Action Action to take when the connection pool is exhausted. No

IMAPS

Parameter Name Description Required
connectionName Name of the connection. Yes
host Hostname of the IMAPS server. Yes
port Port number of the IMAPS server. Yes
username Username for authentication. Yes
password Password for authentication. Yes
requireTLS Specifies if TLS is required. No
Oauth2 Authentication
Enable OAuth2 Specifies if OAuth2 authentication is required. No
Grant Type Type of OAuth2 grant to be used. No
Client Id Client ID for OAuth2 authentication. No
Client Secret Client Secret for OAuth2 authentication. No
Refresh Token Refresh Token for OAuth2 authentication. No
Token URL URL to obtain the OAuth2 token. No
Scope Scope for OAuth2 authentication. No
Additional parameters for connection
Read Timeout Timeout for reading the response from the server. No
connectionTimeout Timeout for establishing the connection. No
writeTimeout Timeout for writing the request to the server. No
Max Active Connections Maximum number of active connections. No
Max Idle Connections Maximum number of idle connections. No
Max Wait Time Maximum wait time for a connection. No
Min Eviction Time Minimum time before an idle connection is evicted. No
Eviction Check Interval Interval for checking idle connections. No
Exhausted Action Action to take when the connection pool is exhausted. No

Operations

list

The list operation retrieves emails matching the specified filters.

Parameter Name Description Required
deleteAfterRetrieve Whether the email should be deleted after retrieving. Optional
receivedSince The date after which to retrieve received emails. Optional
receivedUntil The date until which to retrieve received emails. Optional
sentSince The date after which to retrieve sent emails. Optional
sentUntil The date until which to retrieve sent emails. Optional
subjectRegex Subject Regex to match with the wanted emails. Optional
fromRegex From email address to match with the wanted emails. Optional
seen Whether to retrieve 'seen' or 'not seen' emails. Optional
answered Whether to retrieve 'answered' or 'unanswered' emails. Optional
deleted Whether to retrieve 'deleted' or 'not deleted' emails. Optional
recent Whether to retrieve 'recent' or 'past' emails. Optional
offset The index from which to retrieve emails. Optional
limit The number of emails to be retrieved. Optional
folder Name of the Mailbox folder to retrieve emails from. Default is INBOX. Optional

Sample configuration

<email.list configKey="IMAPS_CONN">
    <deleteAfterRetrieve>false</deleteAfterRetrieve>
    <receivedSince></receivedSince>
    <receivedUntil></receivedUntil>
    <sentSince></sentSince>
    <sentUntil></sentUntil>
    <subjectRegex></subjectRegex>
    <fromRegex></fromRegex>
    <seen></seen>
    <answered></answered>
    <deleted></deleted>
    <recent>true</recent>
    <offset>0</offset>
    <limit>10</limit>
    <folder>Inbox</folder>
    <responseVariable>email_list_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</email.list>

Sample response

The response received will be stored in the variable email_list_1 as a JSON object. The following is a sample response.

{
    "emails": {
        "email": [
            {
                "index": 0,
                "emailId": "<1623446944.0.152334336343@localhost>",
                "to": "<your-email>@gmail.com",
                "from": "<your-email>@gmail.com",
                "replyTo": "<your-email>@gmail.com",
                "subject": "Sample email",
                "attachments": {
                    "index": "0",
                    "name": "contacts.csv",
                    "contentType": "TEXT/CSV"
                }
            }
        ]
    }
}

Note: The emailId of the email can be used to retrieve the email content and attachment content using below operations.

getEmailBody

The getEmailBody operation retrieves the email content.

Parameter Name Description Required
emailId Email Id of the email to retrieve the content. Yes
folder Name of the mailbox folder from which to retrieve the email. Default is INBOX. Optional

Sample configuration

<email.getEmailBody configKey="IMAPS_CONN">
    <emailId >&lt;CAJDNsXYtN9_QnACnZP=MRp5E2u3_StvQ0SO4QQu5THxSA=mAXg@mail.wso2.com&gt;</emailId>
    <folder >Inbox</folder>
    <responseVariable >email_getEmailBody_1</responseVariable>
    <overwriteBody >false</overwriteBody>
</email.getEmailBody>

Following properties will be set in the message context or to a new variable if the overwriteBody parameter is set to false.

{
    "email": {
        "emailId": "<[email protected]>",
        "to": "[email protected]",
        "from": "[email protected]",
        "cc": "",
        "bcc": "",
        "subject": "Subject",
        "replyTo": "[email protected]",
        "htmlContent": "<div dir=\"auto\"></div>\r\n",
        "textContent": "\r\n"
    }
}
getEmailAttachment

The getEmailAttachment operation retrieves the email content.

Parameter Name Description Required
emailId Email Id of the email to retrieve the content. Yes
folder Name of the mailbox folder from which to retrieve the email. Default is INBOX. Optional
attachmentIndex Index of the attachment as per above response of which to retrieve the attachment content. Yes

Sample configuration

<email.getEmailAttachment configKey="IMAPS_CONN">
    <emailId>emailId</emailId>
    <folder>Inbox</folder>
    <attachmentIndex>0</attachmentIndex>
    <responseVariable>email_getEmailAttachment_1</responseVariable>
    <overwriteBody>true</overwriteBody>
</email.getEmailAttachment>

Following properties will be set as attributes.

  • ATTACHMENT_TYPE: Content Type of the attachment.
  • ATTACHMENT_NAME: Name of the attachment.

This operation will set the content of the attachment in the message context according to its content type or assign it to a new variable if the overwriteBody parameter is set to false. The content will be set in the variable context as a base64 encoded string.

send

The send operation sends an email to specified recipients with the specified content.

Parameter Name Description Required
from The 'From' address of the message sender. Yes
to The recipient addresses of 'To' (primary) type. Yes
personalName The personal name of the message sender. This is available from Email Connector version 1.1.2 onwards. Optional
cc The recipient addresses of 'CC' (carbon copy) type. Optional
bcc The recipient addresses of 'BCC' (blind carbon copy) type. Optional
replyTo The email addresses to which to reply to this email. Optional
subject The subject of the email. Optional
content Body of the message in any format. Optional
contentType Content Type of the body text. Optional
encoding The character encoding of the body. Optional
attachments The attachments that are sent along with the email body. Optional
contentTransferEncoding Encoding used to indicate the type of transformation that is used to represent the body in an acceptable manner for transport. Optional
inlineImages A JSONArray that enables the insertion of inline image details. This can be used to specify the image properties, such as the image URL, size, and alignment, among others. By including inline images in the JSONArray, developers can create more visually appealing and engaging content within their application. Note that this feature is available from Email connector version 1.1.1 onwards.

Note

There are 2 methods you can follow to add images, as listed below.
1. Providing file path 
{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Sample email subject",
    "content": "<H1>Image1</H1><img src=\"cid:image1\" alt=\"this is image of image1\"><br/><H1>Image2</H1><img src=\"cid:image2\" alt=\"this is image of image2\">",
    "inlineImages": [
        {
            "contentID": "image1",
            "filePath": "/Users/user/Documents/images/image1.jpeg"
        },
        {
            "contentID": "image2",
            "filePath": "/Users/user/Documents/images/image2.jpeg"
        }
    ],
    "contentType": "text/html"
}
2. Base64Content 
{
    "from": "abc@wso2com",
    "to": "[email protected]",
    "subject": "Sample email subject",
    "content": "<H1>Image1</H1><img src=\"cid:image1\" alt=\"this is image of a image1\"><br/><H1>Image2</H1><img src=\"cid:image2\" alt=\"this is a image2\">",
    "inlineImages": [
        {
            "contentID": "image1",
            "fileName": "image1.jpeg",
            "base64Content": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAY......"
        },
        {
            "contentID": "image2",
            "fileName": "image2.jpeg",
            "base64Content": "/9j/4AAQSkZJRgABAQEBLAEsAAD/4QBbRXhp...."
        }
    ],
    "contentType": "text/html"
}

Optional

NOTE: If there are any custom headers to be added to the email they can be set as Axis2 properties in the context with the prefix "EMAIL-HEADER:" as the property name similar to below. 

<property name="EMAIL-HEADER:myProperty" value="testValue"/>

Sample configuration

<email.send configKey="SMTP_CONN">
    <from>[email protected]</from>
    <personalName></personalName>
    <to>[email protected]</to>
    <cc></cc>
    <bcc></bcc>
    <replyTo></replyTo>
    <subject>WSO2 MI Email Connector Test</subject>
    <content>Sample Email</content>
    <contentType>text/html</contentType>
    <encoding>UTF-8</encoding>
    <attachments></attachments>
    <inlineImages>[]</inlineImages>
    <contentTransferEncoding>Base64</contentTransferEncoding>
    <responseVariable>email_send_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</email.send>

Sample response The response received will be stored in the variable email_send_1 as a JSON object. The following is a sample response.

{
    "success":true
}

Note: The response will be set in the message context or to a new variable if the overwriteBody parameter is set to false.

delete

The delete operation deletes an email.

Parameter Name Description Required
emailId Email Id of the email to delete. Yes
folder Name of the mailbox folder from which to delete the emails. Default is INBOX. Optional

Sample configuration

<email.delete configKey="IMAPS_CONN">
    <folder>INBOX</folder>
    <emailId>sampleId</emailId>
    <responseVariable>email_delete_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</email.delete>

Sample response The response received will be stored in the variable email_delete_1 as a JSON object. The following is a sample response.

{
    "success":true
}
markAsDeleted

The markAsDeleted operation marks an email as deleted.

Parameter Name Description Required
emailId Email Id of the email to mark as deleted. Yes
folder Name of the mailbox folder where the email is. Default is INBOX. Optional

Sample configuration

<email.markAsRead configKey="IMAPCONN">
    <folder>INBOX</folder>
    <emailId>sampleId</emailId>
    <responseVariable>email_markAsDelete_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</email.markAsRead>

Sample response The response received will be stored in the variable email_markAsDelete_1 as a JSON object. The following is a sample response.

{
    "success":true
}
markAsRead

The markAsRead marks an email as read.

Parameter Name Description Required
emailId Email Id of the email to mark as read. Yes
folder Name of the mailbox folder where the email is. Default is INBOX. Optional

Sample configuration

<email.markAsRead configKey="IMAPCONN">
    <folder>INBOX</folder>
    <emailId>sampleId</emailId>
    <responseVariable>email_markAsRead_1</responseVariable>
    <overwriteBody>false</overwriteBody>
</email.markAsRead>

Sample response The response received will be stored in the variable email_markAsRead_1 as a JSON object. The following is a sample response.

{
    "success":true
}
expungeFolder

The expungeFolder operation permanently deletes the emails marked for deletion.

Parameter Name Description Required
folder Name of the mailbox folder where the email is. Default is INBOX. Optional

Sample configuration

<email.expungeFolder configKey="IMAPCONN">
    <folder>INBOX</folder>
</email.expungeFolder>

Note: For more information on how this works in an actual scenario, see Email Connector Example.