How to write an email into a specific folder using HCL C API

HCL Domino Domino Forum
1

I am working with the HCL Notes C API and need to write (save) an email directly into a specific folder inside an NSF database.

Currently, when I create a new email using NSFNoteCreate, set the necessary items (From, Subject, Body, etc.), and save it using NSFNoteUpdate, it goes into the **default View ** like sent , inbox,By Sender but i want this email should be write into the specific folder.

:one: What is the correct method in the HCL C API to write a new email directly into a specific folder inside the NSF database?

:four: Please provide detailed guidance or a step-by-step explanation of how to write emails into a specific folder using the HCL C API, including:

  • Which APIs to call
  • In what sequence
  • Any flags or note class configurations needed
  • Any caveats regarding the default All Documents view.
2

Hi @Rakesh

Here’s a step-by-step guide to writing an email into a specific folder in an NSF database using the HCL Domino C API:

  1. Open the NSF Database
    Use NSFDbOpen to get a handle to the database.

    DBHANDLE hDB;
STATUS error = NSFDbOpen("mail\\user.nsf", &hDB);

  2. Create a New Note (Email Document)
    Use NSFNoteCreate to create a new note.

    NOTEHANDLE hNote;
error = NSFNoteCreate(hDB, &hNote);

  3. Set Required Fields for an Email
    Use NSFItemSetText to populate the note with standard mail fields.

    NSFItemSetText(hNote, "Form", "Memo");
NSFItemSetText(hNote, "SendTo", "recipient@example.com");
NSFItemSetText(hNote, "Subject", "Test Email");
NSFItemSetText(hNote, "Body", "This is a test email.");

  4. Save the Note to the Database
    Use NSFNoteUpdate to commit the note.

    error = NSFNoteUpdate(hNote, UPDATE_FORCE);

    Flag: UPDATE_FORCE ensures the note is saved even if it’s not marked as changed.

  5. Get the Note ID of the Saved Document
    Use NSFNoteGetNoteID to retrieve the note’s ID.

    NOTEID noteID;
error = NSFNoteGetNoteID(hNote, &noteID);

  6. Locate the Target Folder
    Use NIFFindView to get the NoteID of the folder (view) by name.

    NOTEID folderNoteID;
error = NIFFindView(hDB, "CustomFolderName", &folderNoteID);

    Note: The folder must already exist. This function searches by name and returns the folder’s NoteID.

  7. Add the Note to the Folder
    Use NSFDbPutNoteInFolder to place the note into the folder.

    error = NSFDbPutNoteInFolder(hDB, noteID, folderNoteID, ADD_TO_FOLDER);

    Flag: ADD_TO_FOLDER adds the note to the folder without removing it from others.

  8. Close Resources
    Always clean up:

    NSFNoteClose(hNote);
NSFDbClose(hDB);

Caveats and Considerations:

All Documents View

  • The All Documents view is not a folder; it’s a system view that shows all documents.
  • You cannot explicitly add a document to the All Documents view—it appears there automatically unless filtered out.
  • Use folders for user-defined organization; use views for dynamic filtering.

Folder vs. View

  • Folders are a type of view but support manual document placement.
  • Views are typically dynamic and based on selection formulas.

Note Class

  • You don’t need to set a specific NOTE_CLASS when creating a mail memo.
  • The “Form” field with value “Memo” is sufficient to classify it as a mail document.

Best Regards,
Jho Ann Leanne Labayani
Technical Support - Application Development Team
HCL TechnologiesPreformatted text

1 Like
3

Thank you @Jho Ann Leanne Labayani for the detailed step-by-step guidance.

However, I am using the HCL C API Toolkit 12.0.2, and in this toolkit:

  • NSFNoteGetNoteID
  • NSFDbPutNoteInFolder

are not available. I have also checked the official HCL C API documentation, and I could not find these functions listed.

Because of this, I am unable to follow the suggested approach directly.

Could you please clarify:

:one: Are these functions part of a different SDK or an internal API?

:two: Is there an alternative approach using only the functions available in the C API Toolkit 12.0.2** to add a newly created note into a specific folder inside the NSF database?

4

Hi @Rakesh

You may use NSFNoteGetInfo instead of NSFNoteGetNoteID to get the NoteID.

For the function to put the Notes document in a specific folder, you may use FolderDocAdd to add documents to the folder.

Please refer to the documentations below for more information.

NSFNoteGetInfo

FolderDocAdd

Best Regards,
Jho Ann Leanne Labayani
Technical Support - Application Development Team
HCL Technologies