Email Connector Reference

The following operations allow you to work with the Email Connector. Click an operation name to see parameter details and samples on how to use it.

init

The init operation configures the connection parameters used to establish a connection to the mail server.

Parameter Name Description Required
host Host name of the mail server. Yes
port The port number of the mail server. Yes
name Unique name the connection is identified by. Yes
username Username used to connect with the mail server. Yes
password Password to connect with the mail server. Yes
connectionType Email connection type (protocol) that should be used to establish the connection with the server. (IMAP/IMAPS/POP3/POP3S/SMTP/SMTPS). Yes
readTimeout The socket read timeout value. E.g., 100000. Optional
connectionTimeout The socket connection timeout value. E.g., 100000. Optional
writeTimeout The socket write timeout value. E.g., 100000. Optional
requireTLS Whether the connection should be established using TLS. The default value is false. Therefore, for secured protocols SSL will be used by default. Optional
checkServerIdentity Whether server identity should be checked. Optional
trustedHosts Comma separated string of trust host names. Optional
sslProtocols Comma separated string of SSL protocols. Optional
cipherSuites Comma separated string of Cipher Suites. Optional
maxActiveConnections Maximum number of active connections in the pool. When negative, there is no limit to the number of objects that can be managed by the pool at one time. Default is 8. Optional
maxIdleConnections Maximum number of idle connections in the pool. When negative, there is no limit to the number of objects that may be idle at one time. Default is 8. Optional
maxWaitTime Specifies the number of milliseconds to wait for a pooled component to become available when the pool is exhausted and the exhaustedAction is set to WHEN_EXHAUSTED_WAIT. If maxWait is negative, it will be blocked indefinitely. Default is -1. Optional
evictionCheckInterval The number of milliseconds between runs of the object evictor. When non-positive, no eviction thread will be launched. The default setting for this parameter is -1 Optional
minEvictionTime The minimum amount of time an object may sit idle in the pool before it is eligible for eviction. When non-positive, no object will be dropped from the pool due to idle time alone. This setting has no effect unless timeBetweenEvictionRunsMillis > 0. The default setting for this parameter is 30 minutes. Optional
exhaustedAction The behavior of the pool when the pool is exhausted. (WHEN_EXHAUSTED_FAIL/WHEN_EXHAUSTED_BLOCK/WHEN_EXHAUSTED_GROW) Default is WHEN_EXHAUSTED_FAIL. Optional

Sample configuration

<email.connection>
    <host>127.0.0.1</host>
    <port>465</port>
    <connectionType>SMTPS</connectionType>
    <name>smtpconnection</name>
    <username>user1</username>
    <password>user1</password>
</email.connection>
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="imapconnection">
    <subjectRegex>{json-eval($.subjectRegex)}</subjectRegex>
    <seen>{json-eval($.seen)}</seen>
    <answered>{json-eval($.answered)}</answered>
    <deleted>{json-eval($.deleted)}</deleted>
    <recent>{json-eval($.recent)}</recent>
    <offset>{json-eval($.offset)}</offset>
    <limit>{json-eval($.limit)}</limit>
    <folder>{json-eval($.folder)}</folder>
</email.list>

Sample request

Following is a sample REST/JSON request that can be handled by the list operation. 

{
    "subjectRegex":"This is the subject",
    "offset":"0",
    "limit":"2",
    "folder":"INBOX"
}

Sample response

The response received would contain the meta data of the email as below. 

{
    "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 index of the email can be used to retrieve the email content and attachment content using below operations.

getEmailBody

Note: 'List' operation MUST be invoked prior to invoking this operation as it will retrieve the email body of the emails retrieved by the 'list' operation.

The getEmailBody operation retrieves the email content.

Parameter Name Description Required
emailIndex Index of the email as per above response of which to retrieve the email body and content. Yes

Sample configuration

<email.getEmailBody>
    <emailIndex>0</emailIndex>
</email.getEmailBody>

Following properties will be set in the message context containing email data.

  • EMAIL_ID: Email ID of the email.
  • TO: Recipients of the email.
  • FROM: Sender of the email.
  • SUBJECT: Subject of the email.
  • CC: CC Recipients of the email.
  • BCC: BCC Recipients of the email.
  • REPLY_TO: Reply to Recipients of the email.
  • HTML_CONTENT: HTML content of the email.
  • TEXT_CONTENT: Text content of the email.
getEmailAttachment

Note: 'List' operation MUST be invoked prior to invoking this operation as it will retrieve the attachment of the emails retrieved by the 'list' operation.

The getEmailAttachment operation retrieves the email content.

Parameter Name Description Required
emailIndex Index of the email as per above response of which to retrieve the email body and content. Yes
attachmentIndex Index of the attachment as per above response of which to retrieve the attachment content. Yes

Sample configuration

<email.getEmailAttachment>
    <emailIndex>0</emailIndex>
    <attachmentIndex>0</attachmentIndex>
</email.getEmailAttachment>

Following properties will be set in the message context containing attachment data.

  • 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.

Sample response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><axis2ns3:text xmlns:axis2ns3="http://ws.apache.org/commons/ns/payload">id,firstname,surname,phone,email
1,John1,Doe,096548763,john1.doe@texasComp.com
2,Jane2,Doe,091558780,jane2.doe@texasComp.com
</axis2ns3:text></soapenv:Body></soapenv:Envelope>
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
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

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="smtpconnection">
    <from>{json-eval($.from)}</from>
    <to>{json-eval($.to)}</to>
    <subject>{json-eval($.subject)}</subject>
    <content>{json-eval($.content)}</content>
    <attachments>{json-eval($.attachments)}</attachments>
</email.send>

Sample request

{
    "from": "user1@gmail.com",
    "to": "user2@gmail.com",
    "subject": "This is the subject",
    "content": "This is the body",
    "attachments": "/Users/user1/Desktop/contacts.csv"
}

NOTE: The latest Email connector (v1.0.2 onwards) supports the attachments from JSON request payload. The connector is tested with .txt, .pdf and images (.png and .jpg). 

{
    "attachments": [{"name": "sampleimagefile.png", "content": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="}]
}

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="imapconnection">
    <folder>{json-eval($.folder)}</folder>
    <emailID>{json-eval($.emailID)}</emailID>
</email.delete>

Sample request

{
    "folder":"Inbox",
    "emailID": "<296045440.2.15945432523040@localhost>"
}
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="imapconnection">
    <folder>{json-eval($.folder)}</folder>
    <emailID>{json-eval($.emailID)}</emailID>
</email.markAsRead>

Sample request

{
    "folder":"Inbox",
    "emailID": "<296045440.2.15945432523040@localhost>"
}
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="imapconnection">
    <folder>{json-eval($.folder)}</folder>
    <emailID>{json-eval($.emailID)}</emailID>
</email.markAsRead>

Sample request

{
    "folder":"Inbox",
    "emailID": "<296045440.2.15945432523040@localhost>"
}
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="imapconnection">
    <folder>{json-eval($.folder)}</folder>
</email.expungeFolder>

Sample request

{
    "folder":"Inbox"
}
inlineImages

The inlineImages parameter, is a JSONArray that enables the insertion of inline image details. This parameter 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.

There are 2 methods you can follow to add images, as listed below.

1. Providing file path 

{
    "from": "abc@wso2.com",
    "to": "xyz@wso2.com",
    "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": "xyz@wso2.com",
    "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"
}

Sample configuration in a scenario

The following is a sample proxy service that illustrates how to connect to the Email connector and use the send operation to send an email. You can use this sample as a template for using other operations in this category.

Sample Proxy 

<proxy xmlns="http://ws.apache.org/ns/synapse"
       name="SendEmail"
       transports="https,http"
       statistics="disable"
       trace="disable"
       startOnLoad="true">
   <target>
      <inSequence>
         <email.send configKey="smtpsconnection">
             <from>{json-eval($.from)}</from>
             <to>{json-eval($.to)}</to>
             <subject>{json-eval($.subject)}</subject>
             <content>{json-eval($.content)}</content>
         </email.send>
         <respond/>
      </inSequence>
   </target>
   <description/>
</proxy>

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

Top