Loading User Information from Channel 9

Something went wrong getting user information from Channel 9

Latest Achievement:

Loading User Information from MSDN

Something went wrong getting user information from MSDN

Visual Studio Achievements

Latest Achievement:

Loading Visual Studio Achievements

Something went wrong getting the Visual Studio Achievements

Outlook from the Managed World

  In this article, we will step through creating an email message and a contact using VSTO.

Difficulty: Easy
Time Required: 1-3 hours
Cost: Free
Software: Visual Studio 2005

When I read the announcement that Visual Studio 2005 Tools for Microsoft Office (VSTO 2005) had added support for Microsoft Outlook (currently in beta), I downloaded it immediately! After all, my digital universe revolves around email, and being able to easily extend Outlook in custom ways has always been a wish of mine. Writing add-ins for Outlook certainly isn't a new capability, but it was never as easy to write useful, secure code as it is now.

My first step was to download the VSTO Outlook Beta installer. Then, to speed up the learning curve, I downloaded the conveniently supplied snippets. Including the snippets, even this early build is immensely helpful and a great way to jumpstart your creativity. As you will see, the extensibility is quite broad, and in fact we will only be able to scratch the surface with this article. Don't worry though; I'll revisit it again in future columns.

The application we will create today is basically a Hello World for Outlook. We'll step through creating an email message and a contact. The supplied code samples in this article are written in C#, however Visual Basic source code is also included with the code download for this article. Developing with VSTO requires a version of Visual Studio greater than Express Edition. The current beta of Visual Studio can be downloaded from http://lab.msdn.microsoft.com/vs2005/get/. Of course, Microsoft Office Professional 2003 (Service Pack 1) is also a requirement for this article, or at least Outlook 2003 SP1. Be aware that Outlook Express will not function as a replacement for Outlook.

The first step after installing the above is to create an Outlook Add-in project in the Office project templates section in Visual Studio. Notice that alongside the Excel and Word templates, there is a new option for Outlook. Specify a name and click OK.

Click here for larger image

Creating the Outlook Add-in project (click image to zoom)

Actually working with the new features could have proved to be difficult, but it turns out that the object model and available events just make sense. The project template adds a few references for general VSTO and specifically for Outlook. It also creates a setup project to simplify deployment. The main class file is ThisApplication.cs and contains a Startup and Shutdown event handler similar to other VSTO project types.

To avoid presenting too much material at once, in our example creating these items will occur when the add-in starts up and we will not use a menu or any user input to trigger it. Though not realistic, it makes it easier to step into this new functionality. Keep in mind though, that you can create custom menus on the standard menu bar, or respond to events such as the currently active folder, new messages arriving, or an appointment reminder.

Creating mail items, contacts, and folders is easy using the snippets, but be sure to read the readme that appears after installing them. Though the snippets are installed, they will not appear in the Insert Snippet menu item until added through the Visual Studio Snippets Manager (Tools | Code Snippets Manager menu command).

In order to create a new mail message, you will first need to obtain a reference to an Outlook.MAPIFolder object. This encapsulates an Outlook folder like Inbox, Draft, Outbox, or user-created folders. In order to get the default Outbox folder call the GetDefaultFolder method of the MAPI namespace object:

Visual C#

Outlook.MAPIFolder outBoxfolder = this.GetNamespace("MAPI").GetDefaultFolder( 

Visual Basic

Dim outBoxfolder As Outlook.MAPIFolder = 

Correction (9/7/2005, thanks to Sue Mosher, Outlook MVP): You should actually use the Application.CreateItem method, which is the standard (and simpler) technique for creating a new item in one of the default folders.

Once you have a reference to the folder, you can add an item to it. Because the Outbox is generally intended for mail items, that is what we will add, but remember that Outlook supports any item type being added to any folder. To create and add a new mail item, call the Items.Add method of the folder object:

Visual C#

Outlook.MailItem mailItem = (Outlook.MailItem)outBoxfolder.Items.Add(Outlook.OlItemType.olMailItem);
Visual Basic
Dim mailItem As Outlook.MailItem = 

At this point you have a mail item to manipulate. You can set the Subject, Body, and To properties, add a reminder, attach files, display the message, and of course send it:

Visual C#

mailItem.Subject = "Coding4Fun Sample";
mailItem.Body = "This email was created using VSTO 2005 Outlook support.";
mailItem.To = "emailaddress@emailaddress";

Visual Basic

mailItem.Subject = "Coding4Fun Sample" 
mailItem.Body = "This email was created using VSTO 2005 Outlook support."
mailItem.To = "emailaddress@emailaddress"

Sending the message simply requires calling the Send method, while displaying the message is accomplished with the Display method (modally or not). If you do not call the Send or Save method, the message will not persist unless you display the message to allow the user to save or send it. This model is consistent with the various item types.

If you have added the snippets, you can create a mail item in two quick steps: insert the snippet, and then fill in the placeholder fields. You should probably create a new method to contain your message sending code, then right-click and select Insert Snippet, and navigate to the Outlook | Create sub-menu. You will see all of the above code, including helpful TODO comments, and commented out Send and Display calls.

Click here for larger image

A sample message (click image to zoom)

There is no snippet for adding a task item (yet anyway), so for our final sample, let's create a new task. The API is so well thought-out, that once you can create an email, creating a task is a snap. As before, obtain a reference to the folder, this time the Tasks folder. Also as before, remember that any folder will hold a task. This feature is useful for linking items and maintaining isolation between business or project boundaries. Once again, the folder is one of the defaults, so call GetDefaultFolder, this time with the olFolderTasks enumerated folder name:

Visual C#

Outlook.MAPIFolder tasksFolder = this.GetNamespace("MAPI").GetDefaultFolder( 

Visual Basic

Dim outBoxfolder As Outlook.MAPIFolder = 

Next, add a new instance of a task item. Notice that you are not calling a constructor. Each item type is actually an interface. Items must be created as children of a folder, not as stand-alone objects:

Visual C#

Outlook.TaskItem taskItem = (Outlook.TaskItem)tasksFolder.Items.Add(Outlook.OlItemType.olTaskItem);

Visual Basic

Dim taskItem As Outlook.TaskItem = 

Next, set the appropriate properties. In this case, the task's subject, owner, percentage complete, and status. Status is an enumerated type representing Complete, Deferred, In Progress, Not Started, and Waiting.

Visual C#

taskItem.Subject = "Finish Coding4Fun article!";
taskItem.Owner = "Bob";
taskItem.PercentComplete = 0;
taskItem.Status = Microsoft.Office.Interop.Outlook.OlTaskStatus.olTaskInProgress;

Visual Basic

taskItem.Subject = "Finish Coding4Fun article!"
taskItem.Owner = "Bob"
taskItem.PercentComplete = 0
taskItem.Status = Microsoft.Office.Interop.Outlook.OlTaskStatus.olTaskInProgress

The final step is to save the task. This step must be called, or the task will be lost when Outlook is closed or the object goes out of scope.

Visual C#


Visual Basic



VSTO support for Outlook makes it painless to create add-ins for Outlook in managed code. You can create all of the common entity types such as email messages, contacts, and tasks, respond to events, create HTML folder views, and also add application menus. Download Visual Studio 2005, the beta VSTO Outlook installer, then give this application a try. Get started at http://lab.msdn.microsoft.com/vs2005/get/.

Additional Resources

VSTO support for Outlook (Beta)

Outlook Add-in Snippets


Follow the Discussion

  • Eva LiEva Li

    Compile error for GetNamespace(...). Any suggestions?



  • Eva LiEva Li

    After install the downloaded code, the project can not be loaded to VS 2005.

  • Eva LiEva Li

    I installed VSTO 2005. However the Office folder does not show in my VS 2005 under my Visual C#. I tried re-booting my system and uninstall, reinstall. It still does not show. Do you know why?


  • shailesh jogeshailesh joge

    this code should also in c# users

  • ruchiruchi

    how can we receive mails from inbox folder?

  • BalajiBalaji

    I am getting a compiler error for


    please tell  me what to do

  • Clint RutkasClint I'm a "developer"

    do you have VSTO and VS Pro?

  • chancechance

    I got the GetNamespace error when I first tried the code as well.  I had to change it to the following to get it to work:

    Outlook.MAPIFolder outBoxFolder = (Outlook.MAPIFolder)outlookObj.Session.GetDefaultFolder(Outlook.OlDefaultFolders.olFolderOutbox);

  • Clint RutkasClint I'm a "developer"

    @Chance:  Thanks

  • ganeshaganesha

    how can we search for a particular mail in inbox

  • Darren BrownDarren Brown

    Whats does outlookObj refer to in the code above.

  • Clint RutkasClint I'm a "developer"

    @Darren Brown:  I see no reference to outlookObj, what line number / code base are you looking at?

  • HazarHazar


    I use outlook tasks so often, but in the real world I categorize tasks importance as follows:

    1. Urgent and Important

    2. Urgent

    3. Important

    4. Not urgent and not important

    And I want to change this in outlook when creating new tasks: I want to change the default "High, Low and Normal" values for the importance field...

    Can you please help me with that?

  • shmarovshmarov

    Does anybody load .msg file by using VSTO? How can i do it?


  • Deaddog4201Deaddog4201


    public void CreateMessage()


               // Create a new mail item.

               Microsoft.Office.Interop.Outlook._Application outlookObj = new Microsoft.Office.Interop.Outlook.Application();

               Microsoft.Office.Interop.Outlook.MAPIFolder outBoxFolder = (Microsoft.Office.Interop.Outlook.MAPIFolder)outlookObj.Session.GetDefaultFolder(Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderOutbox);

               Microsoft.Office.Interop.Outlook.MailItem mailItem = (Microsoft.Office.Interop.Outlook.MailItem)outBoxFolder.Items.Add(Microsoft.Office.Interop.Outlook.OlItemType.olMailItem);

               mailItem.Subject = "Coding4Fun Sample"; //TODO: Change the Subject field of the e-mail item.

               mailItem.Body = "What ever you want in the body" //TODO: Change the body of the e-mail item.

               mailItem.To = "emailaddress@emailaddress"; //TODO: Change the recipient's address.

               mailItem.Display(false); //true to make the window modal. The default value is false.


           public void CreateTask()


               // Create a new task item.

               Microsoft.Office.Interop.Outlook._Application outlookObj = new Microsoft.Office.Interop.Outlook.Application();

               Microsoft.Office.Interop.Outlook.MAPIFolder tasksFolder = (Microsoft.Office.Interop.Outlook.MAPIFolder)outlookObj.Session.GetDefaultFolder(Microsoft.Office.Interop.Outlook.OlDefaultFolders.olFolderTasks);

               Microsoft.Office.Interop.Outlook.TaskItem taskItem = (Microsoft.Office.Interop.Outlook.TaskItem)tasksFolder.Items.Add(Microsoft.Office.Interop.Outlook.OlItemType.olTaskItem);

               taskItem.Subject = "Finish Coding4Fun article!";

               taskItem.Owner = "Bob";

               taskItem.PercentComplete = 0;

               taskItem.Status = Microsoft.Office.Interop.Outlook.OlTaskStatus.olTaskInProgress;




  • MilindMilind

    Can I set mailItem.from of MailItem ?

  • Clint RutkasClint I'm a "developer"

    @Milind no you cannot looking at the API.  http://msdn.microsoft.com/en-us/library/bb208402.aspx

  • Clint RutkasClint I'm a "developer"

    @vusman requires Outlook for the APIs to succeed.  VSTO are extentions for developing against Office.  This is pretty old article as well, stuff may have changed in the new versions since then.  http://msdn.microsoft.com/en-us/vsto/default.aspx is the VSTO page for everything.

  • vusmanvusman

    can this code work for users that dont have Microsoft Outlook installed on their PCs

Remove this comment

Remove this thread


Comments Closed

Comments have been closed since this content was published more than 30 days ago, but if you'd like to continue the conversation, please create a new thread in our Forums,
or Contact Us and let us know.