Do not worry, this is not going to be a review of the 1998 film “You’ve got mail” starring Meg Ryan and Tom Hanks. It would be a bit late after almost 20 years. What this WSO2TORIAL is all about is the use of email specifically in the context of the WSO2 ESB: SMTP mailto transport in WSO2 ESB
Because email is still a widely used method of sending and receiving information both in the B2B world as in the B2C world.
AXIS2
The mailto transport is part of the axis2 environment that is used in, among others, the following WSO2 products: Identity Server, API Manager, Enterprise Service Bus and Data Services Servers.
Like the other supported transports, like VFS and JMS available in axis2, the mailto transport comes in sender and receiver pairs. One is responsible for the receiving of emails and the other for sending them.
But you can actually use only the sender and not the receiver or vice versa. There is no requirement to use both if you do not need both capabilities.
Defining the mailto transport
For this blog we will use devnullSMTP server to test out the SMTP (Simple Mail Transfer Protocol) functionality. This Java program is a fake smtp server and can be downloaded and used in a couple of minutes. Since we would like to show the functionality rather than actually sending out messages that would make sense.
The mailto transport is found in the [ESB-HOME]/repository/conf/axis2/axis2.xml file. The [ESB-HOME] refers to the fully qualified path the the ESB installation directory.
This is the transportReceiver for mailto.
And this the transportSender for mailto.
We create a mailtoSMTP transport.
Each of these parameters has a function:
| Variable | value | Purpose |
| Name | mailtoSMTP | mailto name used in endpoints |
| mail.smtp.host | localhost | Hostname of smtp host |
| mail.smtp.port | 2500 | Port number |
| mail.smtp.starttls.enable | False | Do not use tls or sl |
| mail.smtp.auth | false | Do not authenticate user |
| mail.smtp.user | donotreply | User name |
| mail.smtp.password | No password needed | |
| mail.smtp.from | SMTPSENDER@gmail.com | Address of email sender |
We need to restart the ESB since changes to axis2 configurations are only loaded at startup.
Building a proxy
So now we need to test it. We will create a simple proxy, based on the echo service found on the ESB. It is actually an axis2 service (.AAR) and will echo anything that you will send to it.
The setup is going to be that we:
- Create a passthrough proxy to the http://localhost:8280/services/echo endpoint;
- Add a clone mediator since we want to send the message to the SMTP server we just defined in the SMTP transport AND send the message to the echo service
- Define a sequence to be used in the clone mediator since we want to set properties like Subject, messageType and ContentType
sendMailSequence
In the sequence we are going to set some properties and define an endpoint. We will do everything inline, normally you would define endpoints in the registry or as a separate endpoint.
Graphically, it looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<sequence name="sendMailSequence" trace="disable" xmlns="http://ws.apache.org/ns/synapse">
<log level="custom">
<property name="status" value="Sending the mail now"/>
</log>
<property name="messageType" scope="axis2" type="STRING" value="text/html"/>
<property name="ContentType" scope="axis2" type="STRING" value="text/html"/>
<property name="Subject" scope="transport" type="STRING" value="File Received"/>
<property name="OUT_ONLY" scope="default" type="STRING" value="true"/>
<send>
<endpoint name="MailEpr">
<address uri="mailtoSMTP:username@gmail.com"/>
</endpoint>
</send>
</sequence>
We put in the log mediator to show that we hit the sequence on the console. The properties are used to create the right message and the OUT_ONLY tells not to wait for a response.
The endpoint definition has our defined mailtoSMTP address.
Defining the proxy
We create a simple passthrough proxy that will send the message to the echo endpoint and with help with the clone mediator, send a copy to the SMTP server. Again, graphically you see little of the workings.
The source is more revealing but it is clear that it is a simple setup.
<?xml version="1.0" encoding="UTF-8"?>
<proxy name="SimpleProxy2" startOnLoad="true" transports="https http" xmlns="http://ws.apache.org/ns/synapse">
<target>
<endpoint name="endpoint_urn_uuid_cacd935b-0ce9-488a-a2bc-3ac1b80a0589">
<address uri="http://localhost:8280/services/echo"/>
</endpoint>
<inSequence>
<clone continueParent="true">
<target sequence="sendMailSequence"/>
</clone>
</inSequence>
<outSequence>
<send/>
</outSequence>
<faultSequence/>
</target>
</proxy>
The most notable is the defined sequence and the continueParent=”true” setting that will clone the message to SMTP and send the message on to the endpoint as a regular execution of the inSequence.
Starting devnullSMTP
You download devnullSMTP from this URL. The standalone jar can be started using the command
java -jar DevNullSmtp.jar
Set the port to 2500 and start the server.
You are now ready to receive mails.
Creating and deploying
We have created our proxy and sequence in Developer Studio in the regular way. You know, create a ESB configuration project to house your artifacts, create them and put them in a C-App. We assume that you are familiar with this and we can skip it. We have a CAR file for download that will circumvent all typing in and you can simply deploy to your esb and does not require changes or modifications when running on localhost.[insert bitbucket]
We will use SoapUI to test our service. We take the WSDL definition from the echoservice to create a Soap project in SoapUI. We change the url to match the SimpleProxy2 on the ESB.
We have cut of some of the envelope since this is a standard soap message. As you can see, the message is echoed to the response window.
This is of course normal behavior, but do we also have an email? The answer is yes. DevnullSMTP received the message we sent using the clone mediator.
Using the mailto transport is as easy as that. Just define your transport and start sending emails.
If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.
