HTML Mails from XPages – part 2: inline images

I’ve updated the HTML mail SSJS library I wrote about yesterday and have added inline images support. This can come in handy when you want to create HTML newsletters.

Marking an image as “inline” can be done by adding an extra parameter to the addDocAttachment() / addFileAttachment() methods:

mail.addDocAttachment( "5203C670815BC8C4C12579270029C543", "header.gif", true );

The addDocAttachment/ addFileAttachment methods now return the Content ID of the image in the message. That ID can then be used to reference the image in the contents:

var headerImgId = mail.addDocAttachment("5203C670815BC8C4C12579270029C543", 
  "header.gif", true);

mail.addHTML("<img src="" + headerImgId + "" />;");

If I send an email to my GMail account using my library containing only inline images, the email is considered not to have attachments (no paperclip icon in the messages list). If you have also chosen that images from that specific sender can always be shown, they also don’t show up at the bottom of the message (in the section containing all attachments).

To test if everything worked correctly I downloaded a sample HTML email template from, uploaded all images to a sample database and created a mail message. In the downloaded index.html file I removed all line-breaks (rn) and tabs (t) using Notepad++. I then added the HTML (starting at the first table tag) to the message using the addHTML() method. I replaced all referenced images as described above. The message I received in GMail looked exactly how it was supposed to look:


I’ve tested the inline image functionality in GMail and Notes 8.5.3. You can download the library here.

Send a HTML mail from an XPage with only 5 lines of code

Sending an e-mail from an XPage (using SSJS) is not too difficult, especially if you’ve done it before in LotusScript:

var doc:NotesDocument = database.createDocument();

doc.replaceItemValue("form", "Memo");
doc.replaceItemValue("sendTo", "");
doc.replaceItemValue("subject", "hi there!");
doc.replaceItemValue("body", "content here");

It gets a bit more difficult though if you want to send out HTML mails. To create those you need to work with stuff like MIME entities, MIME headers and streams.

I’ve created a SSJS library that makes it easy to create HTML mails. It allows you to do the following:

  • create HTML mails in a really simple way
  • add one or more attachments, either from document or files on the server
  • change the sender (name and email address)

To use the library you first need to add it to your application: create a new SSJS script library, call it xpHTMLMail and copy this code from the XSnippets site to it.

Next, in the code where you want to use it you can import that library by adding the following:

import xpHTMLMail;

To create a basic HTML message you write:

var mail = new HTMLMail();

mail.setTo( "" );
mail.setSubject( "Hi there!" );
mail.addHTML( "&lt;b&gt;Hi there!&lt;b&gt;" );<br clear="none" />mail.send();

You can add more HTML to the body of the email by making subsequent calls to the addHTML() function. The library also has methods to set the CC or BCC users:

mail.setCC( ["", ""] );
mail.setBB( "" );

The setTo(), setCC() and setBCC() methods accept a string or array of strings.

What about attachments?

The class has two methods to add attachments to a message: you can add them either from a document in the current application or from a file on the server.

1. To add a file from a document you need to specify the document’s unid and file name:

mail.addDocAttachment("5203C670815BC8C4C12579270029C543", "jellyfish.jpg");

Note that files from documents are read directly from the document into a stream and added as a MIME entity to the message. The files aren’t extracted first.

2. To add a file that’s store somewhere on the server’s filesystem you need to specify its path and file name:

mail.addFileAttachment( "c:/temp/", "report.pdf");
Changing the sender

The sender of the message can be changed by using the setSender() method. You have to specify an e-mail address and can optionally specify a name:



setSender("", "Some User");