When you use the ESB profile of WSO2 Enterprise Integrator (WSO2 EI) to mediate messages, the mediation sequence can be configured to send emails (over SMTP) or receive emails (Over POP3 or IMAP) by using the MailTo transport protocol. The MailTo transport sender and receiver should be enabled in the axis2.xml file (stored in the <EI_HOME>/conf/axis2/ directory) by uncommenting the sender/receiver configurations. In addition to enabling the transport, you can add more properties to this configuration to control the behavior of the transport.
This transport implementation is available as a module of the WS-Commons Transports project. The JAR consisting of the MailTo transport implementation is named axis2-transport-mail.jar and the following sender and receiver classes should be included in the WSO2 EI configuration to enable the MailTo transport:
org.apache.axis2.transport.mail.MailTransportSenderorg.apache.axis2.transport.mail.MailTransportListener
Sending emails from a mediation sequence
Follow the steps given below to configure your mediation sequences to trigger emails.
Step 1: Enabling the transport sender
To enable the MailTo sender, uncomment the following in the axis2.xml file (stored in the <EI_HOME>/conf/axis2/ directory):
<transportSender name="mailto" class="org.apache.axis2.transport.mail.MailTransportSender">
<parameter name="mail.smtp.host">smtp.gmail.com</parameter>
<parameter name="mail.smtp.port">587</parameter>
<parameter name="mail.smtp.starttls.enable">true</parameter>
<parameter name="mail.smtp.auth">true</parameter>
<parameter name="mail.smtp.user">synapse.demo.0</parameter>
<parameter name="mail.smtp.password">mailpassword</parameter>
<parameter name="mail.smtp.from">synapse.demo.0@gmail.com</parameter>
</transportSender>
Note that, in addition to enabling the transport, the following parameters are used in the above configuration to set a default email account as the mail sender. You can override this default mail sender by specifying an email sender account within your mediation sequence.
mail.smtp.from | The email address from which mails will be sent. |
|---|---|
mail.smtp.user | The user name of the email account (mail sender). Note that in some email service providers, the user name is the same as the email address specified for the 'From' parameter. |
mail.smtp.password | The password of the email account (mail sender). |
If you want to use multiple mail boxes to send emails, make a copy of the default MailTo sender configuration in the <EI_HOME>/conf/axis2/axis2.xml file and change the transport sender name. For example, add mailtoWSO2 as the name.
<transportSender name="mailtoWSO2" class="org.apache.axis2.transport.mail.MailTransportSender">
.........
You can use the mailtoWSO2 mail box by specifying the following in a synapse configuration:
<endpoint>
<address uri="mailtoWSO2:user@host"/>
</endpoint>
For a list of parameters supported by the MailTo transport sender, see SMTP Package Summary. In addition to the parameters described there, the MailTo transport sender supports the following parameters.
Parameter Name | Description | Possible Values |
|---|---|---|
| If one or more e-mail addresses need to be specified as BCC addresses for outgoing mails, this parameter can be used. | A comma-separated list of e-mail addresses |
| Format of the outgoing mail. | Text, Multipart |
Step 2: Configuring the mediation flow
Once the MailTo transport sender is enabled, you can configure email messaging within your mediation flow by applying the MailTo transport properties.
To send emails from the global sender
Use WSO2 EI Tooling to create a simple passthru proxy service with the following configurations:
Transport Select 'http' and 'https' as the transports receiving messages. Endpoint URL Enter a valid email address prefixed with the transport sender name (specified in the axis2.xml file). For example, if the transport sender is 'mailto', the endpoint URL should be as follows: 'mailto:targetemail@mail.com'.
For testing purposes, be sure to enable access from less secure apps to your email account. See the documentation from your email service provider for instructions.
- Deploy the proxy service in you WSO2 EI server.
- Invoke the proxy service by sending a request. For example use SOAP UI.
- Check the inbox of your email account, which is configured as the target endpoint. You will receive an email from the email sender that is configured globally in the axis2.xml file.
To send emails from a service-specific sender
Use WSO2 EI Tooling to create a simple passthru proxy service with the following configurations:
Transport Select 'http' and 'https' as the transports receiving messages. Endpoint URL Enter a valid email address prefixed with the transport sender name (specified in the axis2.xml file). For example, if the transport sender is 'mailto', the endpoint URL should be as follows: 'mailto:targetemail@mail.com'.
For testing purposes, be sure to enable access from less secure apps to your email account. See the documentation from your email service provider for instructions.
The following proxy service is generated:
Now, let's set the email sender details by adding Property mediators to the mediation sequence. If these details are not provided in the proxy service, the system uses the email sender configurations in the axis2.xml explained above. Shown below is the new mediation sequence:
Note the following:
- You need to update the property values with actual values of the mail sender account.
- In some email service providers, the value for the 'mail.smtp.user' property is the same as the email address of the account.
- Deploy the proxy service in you WSO2 EI server.
- Invoke the proxy service by sending a request.
- Check your inbox. You will receive an email from the email sender that you configured for the proxy service.
Receiving emails to a mediation sequence
Follow the steps given below to configure your mediation sequence to receive emails, and then process the contents within the sequence.
Step 1: Enabling the transport receiver
To enable the MailTo receiver globally, uncomment the following:
<transportReceiver name="mailto" class="org.apache.axis2.transport.mail.MailTransportListener"> </transportReceiver>
The MailTo transport receiver should be configured at service level and each service configuration should explicitly state the mail transport receiver configuration. This is required to enable different services to receive mails over different mail accounts and configurations.
Note
You need to provide correct parameters for a valid mail account at the service level.
Step 2: Configuring the mediation flow
Once the MailTo transport receiver is enabled, you can configure email messaging within your mediation flow by applying the MailTo transport properties. The MailTo transport listener implementation can be configured by setting the parameters as described in the JavaMail API documentation. For IMAP related properties, see IMAP Package Summary. For POP3 properties, see POP3 Package Summary. The MailTo transport listener also supports the following transport parameters in addition to the parameters described in the JavaMail API documentation.
In the following transport parameter tables, the literals displayed in italics in the Possible Values column should be considered as fixed literal constant values. Those values can be directly specified in the transport configuration.
Parameter Name | Description | e.g.Required | Possible Values | Default Value |
|---|---|---|---|---|
| The mail address from which this service should fetch incoming mails. | Yes | A valid e-mail address | |
transport.mail.bodyWhenAttached | The content for the body of the mail when sending a mail with an attachment. | No | The text you want to appear in the mail body | |
| The mail folder in the server from which the listener should fetch incoming mails. | No | A valid mail folder name (e.g., inbox) | inbox folder if that is available or else the root folder |
| The mail protocol to be used to receive messages. | No | pop3, imap | imap |
| A comma separated list of mail header names that this receiver should preserve in all incoming messages. | No | A comma separated list | |
| A comma separated list of mail header names that this receiver should remove from incoming messages. | No | A comma separated list | |
| Action to perform on the mails after processing them. | No | MOVE, DELETE | DELETE |
| Action to perform on the mails after a failure occurs while processing them. | No | MOVE, DELETE | DELETE |
| Folder to move the mails after processing them. | Required if ActionAfterProcess is MOVE | A valid mail folder name | |
| Folder to move the mails after encountering a failure. | Required if ActionAfterFailure is MOVE | A valid mail folder name | |
| Whether the receiver should process incoming mails in parallel or not. This works only if the mail protocol supports processing incoming mails in parallel. (e.g., IMAP) | No | true, false | false |
| Whether the receiver should poll for multiple messages concurrently. | No | true, false | false |
| Maximum number of retry operations to be performed when fetching incoming mails. | Yes | A positive integer | |
| The reconnect timeout in milliseconds to be used when fetching incoming mails. | Yes | A positive integer |