Sending HTML emails, the final word

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:

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.


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"?...


  1. ReplyTo Address Format

    First let me thank you on posting this article. Although this is a windows only solution, it still offers functionality that is very easy to implement.

    I was able to add a replyto field to the message by adding in an additional line and parameter to the SendMail sub procedure.

    [<code class="lotusscript">ret = sendData( sock, Chr(13) & Chr(10) & |ReplyTo: | & ReplyToField)</code>]

    I guess you could add in any SMTP variable by following the same logic.

    Great work as usual!

  2. Socket Programming in Geneal

    I just wanted to mention that now that you have the basic framework for socket programming you have the capabilities to do other neats things than just sending emails via SMTP. For instance, you could connect to an IRC server and set up a public access Knowledge Base or HelpDesk without your db being web-accessible (not open to port 80). Or you could create a web crawler and store the relevant info to the db.


    1. Re: Socket Programming in Geneal

      Thank you for this Epic Lotus Tale, it helped a lot :-] I was working on an automated email program from VB and it does the trick perfectly.

      I modified the code to make it fully any-vb-app compliant , and if NE1 interested , i can post it over here ...

      Viva ASCII Art

    2. Sending HTML emails: authentication?

      Is it possible to use these scripts where you have to specicfy SMTP Server username and password to send email? If yes, how?!!

      Thanks for any help,


  3. Any way to ADD Attachments?

    The Agent ot send HTML mails works really fine; but: how can we add an attachment to mails generated?

      • avatar
      • Jeff Gosden
      • Tue 12 Nov 2002

      Re: Any way to ADD Attachments?

      Sending file attachments is fairly straight forward once you understand how MIME multipart/mixed headers work.

      However the key is, to encode your attachments into base64 first. This is fairly easy using Jakes' Java based version of the HTML mailer as there are a ton of base64 conversion libraries kicking around for Java.

      However, all is not lost, the following site:


      Contains a LSS for Domino, look for the "Base64.lss" library file.

      All credit should go to Julian Robichaux who is the author of the site.

      Show the rest of this thread

      • avatar
      • javier arce
      • Mon 10 Jan 2005

      Re: Any way to ADD Attachments?

      you better upload the attach to a web server, and post a link to it on the email ...

    1. Re: Any way to ADD Attachments?

      How can we annex an file to mails generated? Thanks!

  4. Extra Tips

    This is a great article, I've used it already to help format some previously nasty looking reports. While I was using this code I stumbled on a couple things that I thought I would share with everyone.

    First, if you try to schedule the agent, make sure that you have rights to run unrestricted agents on the server.

    Second, if you are sending long messages you will want to change the receiveData and sendData functions in the Script Library to return long instead of int.

      • avatar
      • Jake Howlett
      • Wed 11 Dec 2002

      Re: Extra Tips

      Read the message posted before your own.

  5. Problem with larger html emails


    Everything is working just fine form me, but when I tried to send a large email (around 37700) i get an overflow error in the SendData function. The BUFLEN is 37744. Is there any way around this?


    / Paul

  6. Domino 6 Native HTML

    This is a great article, thanks so much for taking the time to put it together! However, as we've found, using Windows APIs for a production level app, can have it's problems.

    We were wondering, whether anyone has taken the time yet to do this same example using Notes 6? All the classes are available now to do MIME and HTML emails. I just haven't seen an example and I'm lazy.

    Anyone know of an example of HTML email in Notes 6 yet?

      • avatar
      • Jake Howlett
      • Fri 17 Jan 2003

      Re: Domino 6 Native HTML

      Courtesy of Brian Eriks:

      http://www-10.lotus.com/ldd/sandbox.nsf/9a483ebd35b173d3852567a6006f6c0e/7479a9b ac473cf9185256a72006b8a19?OpenDocument

  7. W2000 OK, NT fail

    Hello, i have used this library in my own database. In W2000 platform all works rigth. But not in Windows NT4.0 SP6

    I get this message: "Operation is disallowed in this session"

    This happen when i call: ret = WSAStartup(&H101, wsadata)

    Is there a problem to run this in Windows NT4.0 SP6????

    Thanks in advanced.

    e-mail me please: dcelery@isaltda.com.uy

    1. Re: W2000 fail


      i have used this library in my own database, in client notes OK, but in WEB I get this message: "Operation is disallowed in this session"

      This happen when i call: ret = WSAStartup(&H101, wsadata)

      My platform is Windows 2000.


      e-mail me please: bgrfilho@ig.com.br

  8. Sending invitations from agents

    Hi All!

    I am new to Lotus Programming. I want to create an agent that will do teh following

    1. The agent should find out the user's task by querying the table in Oracle. 2. The agent should then send an invitation sent as an email to him/her saying "You have a schedule named ........." 3. If the user clicks the accept button the task should then be added to his/her calendar.

    Part (1) is done. I do not know how to do Part (2) and Part(3). Please help me.

  9. Links to notes documents

    This is a wicked tool - I've been wondering for a while about HTML emails and the java version kinda scared me off...

    However, I have a question I wondered if someone knew the answer to.

    I have a purely notes-client based database, that sends mail to users with a link to a document in the database. Using the normal @Mailsend(blah blah) works fine obviously, and including the [IncludeDOcLink] parameter adds a link (that opens the document IN the notes client).

    In the example on the mail send agent, the link was "http://....." so when it opens up, it does so in the default web browser. I need a 'notes-client' link, as achieved by the @mailsend(....[includedoclink]) command.

    Any ideas anyone?

    Thanks, Jon.

      • avatar
      • Jake
      • Fri 7 Nov 2003

      Re: Links to notes documents

      You need to make a link in the format:

      <a href="notes://...">

      To see the format needed, do a copy as link on a document and then paste in to a text editor.

      Should do the trick. Let me know if not.


      Show the rest of this thread

    • avatar
    • Andy
    • Mon 19 Jan 2004

    Rich Text functionality

    Hi Jake

    I like this ...

    Is it possible to use this method to send a formatted rich text field by email?

    Or would this require me to use something like MidasLSX to generate HTML from the RTF first, then email that?

    Any pointers you may have most appreciated...

      • avatar
      • Jake
      • Mon 19 Jan 2004

      Re: Rich Text functionality

      Andy. I'm not 100% sure, but you might be able to use the new MIMEEntity classes in Domino 6.


  10. Thanks Jake, yet again

    This has saved me a lot of hassle. My current client requires a very rich html newsletter email, and I have 3 days to achieve it!

    I'm revamping my own site at the moment, and would like to add a link to Codestore as one of my developer resource sites. Are you ok with this?

    Thanks again, Niall.

      • avatar
      • Jake
      • Thu 20 May 2004

      Re: Thanks Jake, yet again

      Hi Niall. Glad it helped.

      Link away! After all, there's not much I could do to stop you. And why would I ;o)


  11. HTML email via LS - agent variables

    I'm not sure what I should be putting in for the following 2 variables. For testing purposes, I am using your SendMail form. Eventually, if this works, I will be moving this code into a scheduled agent.

    Let HostNameOrIP = "" ' Address of SMTP server to contact (IP or HostName) LEAVE as localhost if on same server

    Let SMTPName = "FakeSMTP" ' The name you identify yourself as to the SMTP server

    I've currently left the variables as is. However, I get the error message "Relay rejected for policy reasons.". When I remove my SMTP restrictions from the server | configuration document, this then works. However, that is not the solution I am looking for.

    Do the above variables have anything to do with my error?

    Can I still use this code while leaving my relay restrictions as they are?



  12. Problem creating new Socket

    In trying to use the examples, I can't get past creating a new Socket. Whenever I call to create a new Socket, I get a java.long.SecurityException. This exception is coming from lotus.notes.AgentSecurityManager.checkConnect(AgentSecurityManager.java:171). I have had all of the agents digned by an admin ID, but the result is still the same.

    I'm at a loss and hope someone can shed some light on this problem.



      • avatar
      • aeq
      • Tue 19 Oct 2004

      Re: Problem creating new Socket

      Solo requieren firmar la base de datos.


      • avatar
      • Noel
      • Tue 12 Jul 2005

      Re: Problem creating new Socket

      Any one still reading this blog?

      Hide the rest of this thread

      1. Re: Problem creating new Socket

        yep - looking for a quick fix for the Overflow error for larger emails (previously raised by Paul Lernmark)...

        1. Re: Problem creating new Socket

          If I change the sendData (and receiveData) functions to return Long instead of Integer then larger emails can be sent (no Overflow error).

          Problem is now I'm getting "Type mismatch on external name: SENDDATA" errors from other agents that use the same script library. Odd ...

          I see Jake referred Chris King (Thu 5 Dec 2002) to a previous post - I wonder which one...?

  13. Html Emails from Access database

    Hi Cab you please tell me if it is possivble to send html e-mails using an access database and word. And by the way the writing goes under the blue box on this page.

    Looking forward to hearing from you.

    1. Re: Html Emails from Access database

      Good day, can i ask you favor please. What is the code in sending for a one form or maybe a one database while I fill up in a one form. Please can u give me a code for that for the HTML. Hope you will not ignore my message.

  14. No more line wraps!

    This is exactly what I was looking for, Jake.

    I don't need to send anything fancy. Just a very long message in the email body that won't wrap at 80 characters.

    We have an application that uses email to send replies to Remedy. I haven't been able to figure out if it is my Notes client or the Domino server that is wrapping my text, but the the code at the other end breaks when it hits the end of the first line.

    I have been trying desperately to do away with using a very awkward HTML file that they supplied.

    My tests indicate that this method is going to work perfectly!

  15. How to know the length of mybuf to read ?

    I have adapted this slightly so that it sends a tcp stream to a server and then waits for the response. However, the response can be anywhere from 60 characters to around 5k. Can anyone assist with the code to know when to stop reading the buffer ?



Your Comments


Navigate other articles in the category "Agents"

« Previous Article Next Article »
Creating HTTP Requests using Microsoft's XML Parser   None Found

About This Article

Author: Jake Howlett
Category: Agents
Hat Tip: Anders Åbjörn
Keywords: Mail; HTML; Socket;


wsock32.lss (13 Kbytes)
sendmail10.zip (82 Kbytes)


Print Friendly

Let's Get Social

About This Website

CodeStore is all about web development. Concentrating on Lotus Domino, ASP.NET, Flex, SharePoint and all things internet.

Your host is Jake Howlett who runs his own web development company called Rockall Design and is always on the lookout for new and interesting work to do.

You can find me on Twitter and on Linked In.

Read more about this site »