

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,[email protected]
2,Jane2,Doe,091558780,[email protected]
</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
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

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": "[email protected]",
    "to": "[email protected]",
    "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"
}

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