There are lots of topics that get endless discussion in the Notes forums. One of the perennials is the small matter of sending e-mails in HTML format. To which there are as many solutions as there are reasons to want to do it in the first place. Recently I discussed doing it with Java in a three part series of articles. However, Java is not everybody's cup of tea and is a level more complicated than the familiar LotusScript. What we want is the best of both worlds. That's what I hope this article will result in.

The actual final result is a database that I've already made available for you to download from my blog entry for Friday 27th of September. Why write this article then? Well, to give the code a more permanent home with more explanation of how it all works in order to get people comfortable with its use.

You might be wondering why you'd want to send HTML emails from Notes. Doesn't R6 do this for us? Well, yes and no. The reason I discuss methods like this is that it is often nice to have your code that handles workflow logic to send people emails with status updates and links. We are normally restricted to these mails being of a very simple format. With HTML mails we can send people what we like. Hence the interest.

How does this approach work:

In a similar way to my Java approach the method that Anders Åbjörn showed me talks directly to the SMTP server using communication through sockets. This might sound complicated but you don't really need to worry yourself about the ins and outs if you don't want to. Just skip to the next section.

In order to communicate using LotusScript and Sockets we need to use the WinSock32 DLL. Hence, here comes the crunch, this method will only work with servers on the Windows platform. Sorry.

To talk to the SMTP server from an agent does require quite a lot of procedures. However, luckily, Anders has kindly wrapped them all up in an LSS file for us. He also assures me that you can communicate with any text-based protocol using this procedures. Nice.

Using this wrapper we can connect to the SMTP server on port 25 and send it a mail message, line-by-line, in the order required by the protocol. I discussed this in detail in this article. Probably worth a read if you want to understand what exactly is going on. Now, on to using the wrapper code.

Writing the LotusScript:

In the database that I've included with this article I have added Anders' code to a Script Library called "SendMailLib". This then gets included with any agents we write using the a Use clause in its Options:
Use "SendMailLib"

If you want to look at the code in it then feel free. Personally I have chosen to try and steer clear of this extra level of complication. Hey, if it works do we need to know how.

In the database I've used a simple form that send a mail to a user every time a document is created with it. To do this I've added a WebQuerySave agent to the form and this agent uses the wrapper library. This agent sends a simple mail with the text from one field included in it and a link to the document itself. Let's look at the code required by the agent. As a simple example here's a call to send a mail to me with a reminder in big letters:
SendMail "Jake Howlett", "jhowlett@EITS", "Reminder", "<h1>Do something lazy-bones!</h1>"

What's the SendMail function? It's a routine in the agent that does all the communication with the wrapper's methods. Without looking at the whole code here are some of the important parts. You might see the similarities between this and the approach used when using Java socket programming. First we connect to the socket:
Dim sock As Long
Dim ret As Long
sock = openConnection("SMTPServerNameIP", 25)

Now that we have the connection to the server open we send all the required parts of the standard SMTP message, one line at a time. First we say hello:
ret = sendData(sock, "HELO JakeHere" & Chr(13) & Chr(10))

There are then a set of commands we need to send in a certain order followed by the body of the message and we tell the server we are finished:
ret = sendData(sock, "QUIT" & Chr(13) & Chr(10))

Before closing the connection:
closeConnection(sock)

This is only the very basics of what's required but it shows how the code works in essence by sending commands to the server. Also in the actual code there are steps where we wait for and act on key responses from the SMTP server. If you want to get to know how it works then take a look in the agent in the database. The bits you need to understand are in the agent itself.

Summary:

Hopefully with the basic example that this agent and the database offers you have the code needed to take it a step further. There are only really a few limitations that you might encounter. Apart from them you pretty much go about sending mail in any format as and when you want. Maybe I should have called this article "Keeping your boss happy part 3"?...