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. initThe 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 The following OAuth2 authentication configurations can be used for IMAP, IMAPS, and SMTPS connections. Note: These configurations are available from Email connector version 1.1.6 and above. Parameter Name Description Required enableOAuth2 Whether to enable OAuth2 authentication. Possible values are true or false. Default value is false. grantType The OAuth2 grant type. For example: AUTHORIZATION_CODE, CLIENT_CREDENTIALS. Required if enableOAuth2 is true. clientId The Client ID obtained when registering your application. Required if enableOAuth2 is true. clientSecret The Client Secret obtained when registering your application. Required if enableOAuth2 is true. tokenUrl The token endpoint URL used to generate the access token. Required if enableOAuth2 is true. scope The scope for the OAuth2 connection. Required if the grantType is CLIENT_CREDENTIALS. refreshToken The generated refresh token. Required if the grantType is AUTHORIZATION_CODE. 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> listThe 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> sendThe 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="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=="}] } deleteThe 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>" } markAsDeletedThe 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>" } markAsReadThe 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>" } expungeFolderThe 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.