Sending HTML mail via SMTP part 1
My favourite articles are the ones I write knowing, at the back of my mind, that they will be really appreciated by those who take the time to read them. This I hope will be one of them. It could just as well be titled Keeping the boss happy Part 2. It has nothing to do with that article but it's one of those things probably more pleasing to those impressed easily than to a developer. Trust me though, this is worth reading. It's one of those things you will just love to show off to anybody willing to watch and listen...
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.
Looking forward to this
For me, HTML Mail would be great because if you send a plain-text mail with a html link via smtp to an outlook client it will be wrapped to the next line after the specified line length (75 or something) and will not be recognized fully when the user clicks it.
Will the code interact with the NAB to take the individual user settings? I mean, regarding the mail format that is set there - can be "Notes Rich text" or "MIME" or "No preference".
Reply
Re: Looking forward to this
It will indeed interact with the Domino Directory (NAB). It will need to do this to find the Short Name and Domain of the user(s) listed in the sendto field.
We need these as for an address to be valid in SMTP it can't have spaces and must have an @DOMAIN on the end.
One problem I'm yet to solve is how to send to a group in an Exchange address book that contains spaces...
Jake -codestore
Reply
Re: Looking forward to this
I must admit that I have never experienced any problems with Lotus Notes and HTML emails. All I use, is
doc.to = "my@email.addy" doc.subject = "Test" doc.body = "here goes the html, the rich textfield or whatever you want"
doc.send(false,"my@email.addy");
Or something similar. No problem, whatsoever sending html mails.. maybe thats just me..
Reply
Show the rest of this thread
Re: Looking forward to this
I read all your articles.
How i can to send HTML mail with pictures (assuming the recipents email client is outlook) includeed in the mail, in other words, when i send a url mail, all the pictures are http hiper links in a http server, but if the client read the email thru modem connection a then it disconnect, all the images are not displayed, because the connection its closed. Then i need send the pictures how mime attachments in the mail.
How i can to do that?
Thanks in advance
PD: sorry by my poor english.
Reply
Great
Just the first idea of getting rid of ugly URLS is enough of a hook for me. Look forward to the next instalment...
tq
Reply
JavaMail API
I Think it would be really great if you added a "part 4" to this series that showed how to hook up the javamail API. You would then have the only complete Notes / Web Mail resource and will allow us to compare both approaches.
Great Article though *****
~Brett
Reply
Re: JavaMail API
Cheers Brett.
You read my mind. The will indeed be an article (Part X) that discusses using the JavaMail API. The whole series could go on for some time...
I guess there won't be much of a comparison as the API is tried and tested by Sun whereas this one tried and "tested" by Jake.
The advantage to my approach being that you don't need to add any extra code libraries to the standard server's Java install.
Thanks for the *****s ;-)
Jake
Reply
Sending HTML mail via SMTP using C++
How do I send the following to the WorkBench to tell it that its a html message
Mime-Version: 1.0; Content-Type: text/html; charset="ISO-8859-1"; Content-Transfer-Encoding: 7bit;
I'm trying to send html using SMTP from C++, and I can't figure out how to tell the SMTP server that this is a HTML body message not a ASCII text message. So my question is, how do you send a command to the SMTP server to tell it that the message body is HTML, using the WorkBench?
Thanks!
Matt
Reply
Am I missing something
Seems like I am kinda late in discovering this wonderful tip provided by Jake.
Was hoping to find someone asking this, but nobody seems to have the problem I am facing...thought I must be missing something.
It's regarding the recipients email addresses:
"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"
My question is how am I gonna know this information if my recipients are 1. not users within my domain (address book) 2. for some reason, the shortname of my users in the address book is actually the full email address. I tried sending to eg. wongirwin@disciples.com@TEAMS, doesn't work, but somehow it works when i use irwin@TEAMS, even though "irwin" is actually the value in the last name field.
Any advise would be much appreciated.
Thanks
Reply
JavaMail isn't that difficult
Hi Jake,
<qoute>The trouble with downloading an API is that this requires you to make changes to the setup of the actual server.</qoute>
I must say I do not totally agree. I imported two files (mail.jar and activation.jar) in a java-agent and voila, works like charm.
I am now fully able to generate MIME messages with all different kind of objects (HTML with inline images and attachements). Had to use this 'cause a customer wanted his emails to look like his letters (including companylogo, crazy or not). Let me know if you like an example! It works both as front-end and back-end (R5.0.9).
regards,
Tom
Reply
Re: JavaMail isn't that difficult
Good work Tom. Sure send it over. About time I wrote a new article. A follow up would be nice to this article. Quite a few people have been asking how to go about doing this...
Jake
Reply
Show the rest of this thread
Problem with setting HTML Mailer up
Perhaps someone could help me here although this topic may have gone cold by now.
I have set up the HTML mailer database in my environment and the Send Msg function works a treat. Using the send URL function however, results in an 'invalid message key' error.
Any help would be much appreciated and Jake, if you read this, thanks for your effort in putting this together it has saved me a heap of work.
Kind Regards JP
Reply
socket workbench
where do i get socket workbench from? Is it a free download product? If not , how much does it cost?
thanks, Jay
Reply
Smtp Mailing
Hi ,
When I am sending mail using the following it gives a message server requires authentication . what i should do ?
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
Reply
Goood
<html> <body> <h1>vikas the great</h1> </body> </html>
Reply
Awesome...
... I have been looking for something like this in the back of my mind while I've been surfing the web for over a month. THANKS.
Reply
Nice, it works with ruby
Thank you, I used the main idea of this article in ruby. It works fine.
- Luis
Reply
I have a question, I have made a mail sender in Visual Basic 2008, and its almost done, the ONLY thing left is for it to be able to send HTML emails.... Any help please??? If I type in html code and send it, it shows up in my inbox as plain text... PLEASE RESPOND TO ME
Reply
This is very cool
Reply