Sending mail from LotusNotes using C#

Introduction

I know that there are already a few examples about how to send mail messages from LotusNotes using C#. None of them provide deep details about how everything is working in the background. This knowledge is needed if you need to send more complex mails and most importantly - fix errors if your application encounters any. In other words this will contain information about how to send mail messages from LotusNotes and how everything works in the background (down to the object level).

Background

No background is required here - just a basic knowledge of programming (C# preferably).

Using the code

In order to use this you need to have LotusNotes DLL referenced to the project. You can get it from IBM or Google. The name is NSQL32.DLL. I usually include the file into the project first and then reference it. After referencing you should have a "Domino" in the list (just as shown bellow).

Let's get started

Alright. So - in order to send mail messages using LotusNotes, we'll have to follow this sequence:

1. Create NotesSession
2. Initialize it (your password will be required)
3. Get connection to database
4. Create document
5. Alter properties of that document (To, Cc, Bcc, Subject, Body, and so on)
6. Do something with the document (send it, save i,t or something else)

Code for the above would look as follows:

1. Create NotesSession and initialize it.

Domino.NotesSession nSession = new Domino.NotesSession();
nSession.Initialize("put your password here");

2. Get connection to database.

Domino.NotesDatabase nDatabase = 
  nSession.GetDatabase("Server Name", "nsf location on the server");
//set the server to "" when sending from local machine

3. Create document and start setting the properties for it.

Domino.NotesDocument nDocument = nDatabase.CreateDocument();
/*create string variable that will be passed to function. This way we setup To field value*/
string[] recipients = 
  {"1@recipient.com", "2@recipient.com", "3@recipient.com"};

//setup Form
nDocument.ReplaceItemValue("Form", "Memo");
nDocument.ReplaceItemValue("SentTo", recipients); //To field
nDocument.ReplaceItemValue("Subject", "Message subject"); //message subject
nDocument.ReplaceItemValue("Body", "Something in the message body"); //set body text
nDocument.SaveMessageOnSend = true //save message after it's sent
nDocument.Send(false, recipients); //send

So - that's it about sending. Now... what just happened... LotusNotes is storing everything in object layers and our created document has the following objects underneath:

For now - the most important one for us is "Items". The type of it is object[] (object array). It contains properties for our mail item. In other words, what we have set:

1. Form --> Memo.
2. To field values.
3. Subject.
4. Message body text.

Each of these items is stored in that array. In this case Form[0], SendTo[1], Subject[2], and Body[3]. All have the following properties:

Also please note that the values that we set not just goes to "Text" field, but it also goes to Values. If you look at the SendTo[1] you will see that there are three mail addresses under the Text property, but also you can see three objects under the Values property:

So - this is the explanation for "why we need to store the addresses in string[] rather than string". This is because LotusNotes works this way - stores each address as a separate object. The same is with almost all the rest of LotusNotes (attachments, cc, bcc, and so on).

Also - this Text property is very useful when you read the items (easier to code then use object array under Values property). For example if you would like to read all LotusNotes database and take only sender and subject - it would be much easier to access it through Text property using the GetFirstItem("item name") method then to loop though all objects in the array (in most of cases it's only one object).

Well- that should be it for a brief explanation about the structure of Lotus Notes document when sending very simple mail messages. There would be no drastic change for a complex message too - just more properties and more mess :)

P.S.: make sure you encapsulate everything with try, CATCH, and finally blocks!

Thank you all in advance for the feedback!

Cheers!