The Principal Field

We all know that you can spoof the email address of an email sent by LotusScript. You just set the Principal field. Right? Well, what if it doesn't work as expected?

I've always taken it for granted that Principal fields work. Until today that is, when I had some real problems getting it to work. Off to the forum I went to try the near-impossible task of tracking down the Agent FAQ Julie Thingymebob is always referring to. I finally found the article on troubleshooting agents. In it, it says there are three ways to specify the Principal field:

  1. doc.Principal="Joe User/Org@NotesDomain"

    Where Joe User/Org has a Person record with an InternetAddress of your choosing. (Note that the string @NotesDomain must be present.)

  2. doc.Principal="CN=Joe User/O=Org"

    Where Joe User/Org has a Person record with an InternetAddress of your choosing.

  3. doc.Principal=User@acme.org@NotesDomain <mailto:User@acem.org@NotesDomain>

    (Note that the string @NotesDomain must be present.)

If you are having trouble getting Principal to work this should help. Well, it would help if there weren't such obvious errors in it. Take a look at number three. Apart from the typo it should be obvious to see that the string isn't marked as a string and so would in fact cause an error. Then there's the mailto: bit. I'm not sure what that bits about but I'm pretty sure it shouldn't be there. The correct line should be:

doc.Principal="User Name <User@acme.org@NotesDomain>"

Note that the @NotesDomain gets stripped off and so mail clients see a proper SMTP-format from address of "name here <email@company.com>". However, some clients, such as Thunderbird, display both from and sender if there's a difference. TO change the apparent sender you need to change the InetFrom field. But, this shouldn't include the @NotesDomain part.

doc.Principal = "User Name <User@acme.org@NotesDomain>"
doc.InetFrom = "User Name <User@acme.org>"

Note that the user and their associated email address must actually exist in order for mail routing to work properly.

While we're on the topic. Is it Principal or Principle? There seems to be confusion in the forum as to whether it's one or the other. It is of course the former, but I think Dictionary dot com can help us all (me included) understand why:

prin ci pal
adj. First, highest, or foremost in importance, rank, worth, or degree; chief..
prin ci ple
n. A basic truth, law, or assumption: the principles of democracy.

Another note: If you're using MIME headers to send HTML emails, like I was, you need to set these two fields after setting the MIME content (article on that in the pipeline).

If anybody knows of any other gotchas on this subject please add them. This post is merely some notes on what I learnt today. If I'm wrong in any way or there's more to it than this please speak up.


    • avatar
    • Joe
    • Tue 21 Mar 2006 11:17 AM

    I inherited an app once that created/saved a new doc in the mail.box - think they jut set the From field. Seemed to work.

    • avatar
    • Christian K
    • Tue 21 Mar 2006 11:33 AM

    Sometimes you may want the sender field to display something like "Automatic mailer". An easy way to achieve this is to create a special user with fist name Automatic and surname mailer. This users internet address my be shortname@somedomain.com. It simplifies the agent if you add the shortname to the username field. This way you can get away with

    doc.Principal = "shortname"

    If you sign the agent by this special user "Automatic mailer", the sender information in the mail will be simplified (no information about designer or server domain will show up).

    This will be equivalent to sending from "Automatic mailer <shortname@somedomain.com>"

  1. @Joe :: Problem with putting things in the mail.box is that you can not be assurred that mail.box will exist... we use 3 mail boxes (everyone should have more than one) so they are named mail1.box - mail3.box... and if you are writing to one directly and it becomes currupted you are SOL until you fix it... It really is a bad practice... there are probably other reasons why it is bad but those two alone stop me...

  2. Always remember the "Principal is your pal" :)

  3. mail.box works fine for me. I would never go back to the Principal stuff and I am happy that it still works (as it is not supported and considered a security risk).

  4. Did you note that the use of Principal is no longer in the documentation? As of Notes 6 this makes it (obviously) an undocumented feature (also Julie admitts, that she's still using it all the time). As far as I get it, the "official" way to go would be a run-on-behalf-of agent by now.

    • avatar
    • Eric
    • Wed 22 Mar 2006 06:00 AM

    I use the following code after setting the MIME content:

    Memo.DisplaySent = sReplyTo

    Memo.tmpDisplaySentBy = sReplyTo

    Memo.INetFrom = sReplyTo

    Where "sReplyTo" is the e-Mail adres which you want to show in the e-Mail and where the receiver is replying to.

  5. I run into this problem some weeks again and after some investigation, I came up with this code to send a memo:

    Sub SendEMail(SendTo As String, Subject As String, BodyText As String)

    Dim Session As New NotesSession

    Dim CurrentDatabase As NotesDatabase

    Dim MailDocument As NotesDocument

    Dim RichTextItem As NotesRichTextItem

    Set CurrentDatabase = Session.CurrentDatabase

    Set MailDocument = CurrentDatabase.CreateDocument

    MailDocument.Form = "Memo"

    MailDocument.Principal = "Application Name@NotesDomain"

    MailDocument.DisplaySent = "Application Name@NotesDomain"

    MailDocument.ErrorsTo = "Error-InBox@Internet.Domain"

    MailDocument.ReplyTo = SendTo

    MailDocument.SendTo = SendTo

    MailDocument.Subject = Subject

    Set RichTextItem = New NotesRichTextItem(MailDocument, "Body")

    Call RichTextItem.AppendText(BodyText)

    Call MailDocument.Send(False)

    End Sub

    • avatar
    • David
    • Wed 22 Mar 2006 03:30 PM

    I've been writing to mail.box for years. Works like a charm. We too have 3 mail.boxes, but I haven't had any issue with corruption. I guess you could just check to see if mail1.box was up, if not move the next and/or load balance if you are sending a lot of mail during an scheduled time.

    I know it's not supported and not documented, but you know what, so are many other things that do work.

    • avatar
    • Fredrik
    • Thu 23 Mar 2006 12:41 AM

    mail.box is an old friend, as long you handle the possibility of server configuration being altered, and mail.box becomes mail1.box a.s.o.

  6. This is what I found.

    Use the Principal field only - no effect

    Use Principal field and DisplaySent field - message is sent as agent signer on behalf of display email address

    Use Principal, DispaySent and INetFrom fields - message sent as coming from display email address.


    Call mailDoc.ReplaceItemValue("Principal", |my_display@xxxx.com@NotesDomain|)

    Call mailDoc.ReplaceItemValue("DisplaySent", |my_display@xxxx.com@NotesDomain|)

    Call mailDoc.ReplaceItemValue("ErrorsTo",|my_display@xxxx.com@NotesDomain|)

    Call mailDoc.ReplaceItemValue("INetFrom", "my_display@xxxx.com")

    will be sent out as though it has come from my_display@xxxx.com.

    This is the header of an email sent this way to an Outlook server

    Microsoft Mail Internet Headers Version 2.0


    From: my_display@xxxx.com


    To: Dietrich.Willing@blaablaablaa.com

    Message-ID: <OFBB3A441D.935102DA-ONCA257451.008326CF-CA257451.008326CF@the actual domain>

    Sender: my_display@xxxx.com


    • avatar
    • mark
    • Tue 1 Jul 2008 10:58 AM

    We have an application where a small number of people who do not have Notes IDs but who authenticate using LDAP need to fill in a form that uses a Domino email list in the Bcc to send a message. The WQO looks up the sender's email & the WQS writes principal, replyto etc as described above. It works when the email is received in Notes but not when sent to Exchange (no message is received or returned - presumably as an antispam measure). Anyone know a good way to trap outgoing message headers from Domino so I can debug this - otherwise it looks like writing direct to mbox, mbox1, mbox2


    • avatar
    • Jake Howlett
    • Wed 2 Jul 2008 05:21 AM

    Hi Mark,

    Have you tried using WireShark? {Link}

    I've used it on a windows client to see what my browser's sending/receiving but I'm sure it could be used on the server to do the same.


  7. hi Mark

    I *love* Socket Workbench for this - See www.sigmasolutions.com.au. You can get an evaluation copy from them like I did.

    It is fantastic at trapping the messages on a communication path and especially useful when debugging SMTP email. You direct your domino server to send on port 26, you get Socket Workbench to listen on port 26, and then resend on port 25. You then get to see everything in between or send your own messages using the inbuilt client tool.


    • avatar
    • Jimmie Mo Jimmie
    • Fri 20 Feb 2009 10:16 AM

    I used pricipal and

    Memo.DisplaySent = sReplyTo

    Memo.tmpDisplaySentBy = sReplyTo

    Memo.INetFrom = sReplyTo

    worked but I dropped the @NotesDomain and it works to all email providers. I have no idea why.

    • avatar
    • PaulE
    • Tue 15 Dec 2009 04:19 AM

    aagghh, Just completely bitten on the arse by

    "doc.Principal=User@acme.org@NotesDomain <mailto:User@acem.org@NotesDomain>"

    thanks for the solution!

  8. Mail.box works far better than the Lotus Method... you end up with that stupid 'Sent on Behalf of" thing on the email that causes the wrong people to get responses to email when people respond manually using the lotus tools.. Lotus has a signature.. use that to verify the sender but preventing coders from changing the From field is a joke.

    • avatar
    • Jean
    • Mon 21 Jun 2010 10:13 AM

    using Notes 8.0.2. email notice executed from a call to script lib, from query save event. So I can't use the "signed agent" method. the following following works for me,

    Memo.DisplaySent = sReplyTo

    Memo.tmpDisplaySentBy = sReplyTo

    Memo.INetFrom = sReplyTo

    but if I add, Memo.Principal = sReplyTo, it did not work.

    • avatar
    • Patrick
    • Thu 10 Mar 2011 09:33 AM

    I'd LOVE to be able to get to the bottom or this, but I still can't.

    Here's what I'm experiencing:

    This works great IF the agent is RunOnServer or run by the Amgr:

    EscMail.Principal="Fname Lname <email@xxxx.com@NotesDomain>"

    EscMail.INetFrom = "Fname Lname <email@xxxx.com>"

    but if it's run from Notes Client I get the annoying "on behalf of" in the email when it

    arrives in Outlook (even though the agent signer and the person executing it, ME,

    are the same).

    I've tried using different combinations of Principal, DisplaySent, tmpDisplaySentBy,

    From, and INetFrom, and I can't find anything that works consistantly when run

    from client and from server.

    Any ideas out there???

Your Comments


About This Page

Written by Jake Howlett on Tue 21 Mar 2006

Share This Page

# ( ) '


The most recent comments added:

Skip to the comments or add your own.

You can subscribe to an individual RSS feed of comments on this entry.

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 »

More Content