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