Note: This article will be in three parts. This, the first will discuss the concepts and requirements behind it and get you excited. The second will cover the code involved whilst the third will put it the theory to test and produce some wonderful results while showing you some the endless number of applications it has.
Enough rabble, let's get started. This article is about to describe a powerful way of sending mails in HTML format. You may be wondering what the fuss is about, surely this is quite easy. Not so. For reasons I won't go in to it's not possible to send a mail from Domino and simply have it display in HTML format to its reader. I had known this for some time but had never had to give it much thought until I was asked to do just that during my first week of my latest contract. Mindful that this may well be a test of how good he really is I set about finding out more, determined to find a solution. Now I share with you all what I learnt.
I have to admit they gave me a head-start and pointed me in the right direction. What they knew already was that this was possible using Sun's JavaMail API. When I thought about this I was a little apprehensive. There must be another way I thought and a quick search on the Iris Forum led me to a post by Panu Haaramo about a method that required no extra downloads. The trouble with downloading an API is that this requires you to make changes to the setup of the actual server. Depending where you work this can be could be easy or it could be an uphill struggle.
A little background:
Because we need to send a mail in HTML format we can't do it using the Notes mail router and so we need to use SMTP. To do this we need to first enable it on the Domino server and then learn the syntax that the server expects you to talk to it in.
To enable SMTP you need to edit the server document - it's not as simple as simply adding it to the list of tasks to launch in the Notes.ini file. See below:
Once you've done this and restarted the server you'll notice that the SMTP task launches. We can now send mails through it. To do this we need to know the syntax that this protocol understands. In doing this I came across an extremely useful product called Socket Workbench. Using this we can easily talk to any server on SMTP's port 25. It even comes with this template for a simple message:
HELO YourComputerName (optional)
MAIL FROM: <Sender's E-mail Address>
RCPT TO: <Recipient's E-mail Address>
DATA
From: Sender's Alias <Sender's reply e-mail address>
To: Receiver's Alias <Recipient's e-mail address>
Subject: <Subject Goes Here>
<body goes here>
.
QUIT
The important part here is between the first line and the DATA line. These addresses must be qualified SMTP addresses. If they aren't the sending will fail. Also important is the blank line between the subject and the body - a requirement - as is the period (.) on its own line at the end to signify the end of the message. If you are sending more than one message you don't need to issue the QUIT command until all is done.
A simple test:
With SMTP enabled let's see what happens when I send a simple mail to myself using the Socket Workbench program:
We can see on the console that the SMTP server has accepted a new connection from my PC. Once the above program has sent the whole message and the final period on its own line we see the server confirm that a message has been received. At this point the Notes router takes over and delivers the message to the list of people included using RCPT commands in the message header. Note that these names need to conform to the SMTP RFC standards. Hence we need to know the user's short name (no spaces) and the domain.
Et voila, there is now a message waiting for me in my inbox.
The above example uses the Notes SMTP server and the Notes mail client. This isn't the only option we have. My current role means I'm developing in a Domino/Exchange environment and users only have the Outlook mail client. This method works with any SMTP server. It's actually better sending HTML mails to Outlook as it has much better support for displaying HTML and handling any JavaScript included. If you are stuck with the Notes client I suggest you keep the pages you send as simple as possible.
Taking this one step further:
Just to prove we can indeed use these principles in order to send a mail in HTML form let's see the resulf of sending the following SMTP commands through Socket Workbench to the Domino server.
HELO JakesDominoApp
MAIL FROM: jake@jakehowlett.com
RCPT To: jhowlett@EITS
DATA
From: My Self <me@you.com>
To: A secret list <you@me.com>
Subject: A simple test
Mime-Version: 1.0;
Content-Type: text/html; charset="ISO-8859-1";
Content-Transfer-Encoding: 7bit;
<html>
<body>
<h2>An important link to look at!</h2>
Here's an <a href="http://www.codestore.net">important link</a>
</body>
</html>
.
QUIT
Notice that we now have three extra lines in the mail's header. These let the receiving client know what to do with the content. This is the important part and you should note the order in which each setting is listed. Here's what it looks like in the Notes client:
This is of course a very basic and useless example. What it does show however is that even at the basic level it removes the need for long ugly URLs in Domino format when we need to send automated emails to the user. Worth it alone just for this.
Putting it all in to practice:
As I mentioned earlier we are going to need to use Java to talk to the SMTP server. Don't worry though as the actual code is fairly simple and straightforward. The basis is that with Java we can communicate through a socket which is connected to the server's SMTP port (usually port 25). JavaWorld has an interesting article all about socket programming which you can read if you want to have a go yourself and not have to wait the week it will probably take me to write part 2.
One thing I learnt soon after writing the code that talks directly to the port is that this isn't really such a great idea. As pointed out in O'Reilly's Java Cookbook it is a lot better to simply use the JavaMail API that has been tried and tested by professionals. I'm still going to explain my origianl method though as it works and it's interesting to know exactly what is going on. It's also nice to have this available to you if adding Jar files to the server is not an option.
So in the next part I will discuss how to actually code this and make it available to us as Domino developers.