Andrei Smolin

How to customize Outlook Today page programmatically?

In this post, I will show you how to create a custom Outlook home folder page in VBScript and in .NET (VB, C#, C++).

In fact, there are 2 ways of customizing Outlook Today:

  • It can be modified by the user, you just need to open Outlook help (see the Help menu) and enter “customize Outlook today” in the Search For field.
  • Or, if you are a developer, you may want to add some functionality to Outlook Today programmatically. Let’s dig deeper into this.

Outlook Today is a set of HTML pages that use VBScript to display some Outlook-related information. If you open the Properties window for Personal Folder and navigate to the Home tab, you’ll see that the default page address is as follows:

res://C:\Program Files\Microsoft Office\OFFICE11\1033\outlwvw.dll/outlook4.htm

That is, the first Outlook Today page is shown from resources of some Outlook-related .DLL and this implies that no source code is available for Outlook Today.

On other words, the developer can only replace Outlook Today with a custom page. Let’s create such a page: open NotePad and copy / paste the text below:

<title>VBScript: the first try</title>

So, our custom page consists of the html tag that contains the head and body tags. The page is empty, as you can see. Now let’s add a button:

<input type="button" value="Go" onClick="greeting()"/>

The button caption is “Go” and when you click on the button, the greeting function is called. Now let’s add the function:

<script type="text/vbscript">
function greeting()
   document.write("<p>Hello, developer!</p>")
end function

This simple function prints a paragraph containing the greeting.

Now we are ready to plug the page into Outlook:

  • Right-click on a folder and choose Properties in the context menu. Note that if the folder is Personal Folders, it means that we replace the Outlook Today page with our custom one.
  • Specify the page location and tick the checkbox that shows the page.

Folder Properties dialog in Outlook

Note that the Address textbox in the screenshot above corresponds to the WebViewUrl property of the MAPIFolder class (Folder in Outlook 2007). Accordingly, the checkbox labeled as “Show home page by default for this folder” corresponds to the WebViewOn property. These properties allow you to set an HTML page for any Outlook folder on the fly. For instance, you can replace the Outlook Today page with your custom one. If you use these properties, you should keep in mind that Outlook 2002 has a well-known bug confirmed by Microsoft: when you set WebViewUrl, the page will show up after the user switches to another folder, and then switches back to the folder with the home page (see for details).

Here is the page:

An HTML page shown in Outlook

At this stage, you can move in the following directions:

However, Outlook Today can display some information about tasks, e-mails / messages and appointments and meetings. To get these data as well as information about contacts, notes and other Outlook items, you have to dig into the Outlook object model:

  • Open Outlook
  • Choose Tools | Macros | Visual Basic Editor in the menu or just press Alt+F11
  • In the VB IDE, choose View | Object Browser in the menu or just press F2

The object browser allows choosing the object model to browse in its topmost combo. Then you choose a class in the left pane and see class members in the right pane.

VBA Object Browser

Application is the most important Outlook class. It provides the Session property of the NameSpace type. The NameSpace class contains Folders. Each folder (of the Folder type in Outlook 2007, MAPIFolder in Outlook 2000-2003) contains Items and other Folders. Each Item provides the Class property the value of which is a constant uniquely identifying every item type: MailItem, TaskItem, ContactItem, etc. To get help on a class or a class member just press F1. When reading help, pay attention to the availability and other aspects of using this or that class or class member in VBScript. For instance, Outlook events are not available in VBScript.

The following sample function uses the Outlook object model to demonstrate how you can apply the above-mentioned information. The function lists top-level folders in the current Outlook session:

function greeting()
   on error resume next
   dim OutlookApp
   on error resume next
   set OutlookApp = GetObject(, "Outlook.Application")
   if OutlookApp is Nothing then
      document.write("<p>Hello, developer!</p>")
      exit function
      document.write("<p>Hello, Outlook developer!</p>")
   end if
   on error goto 0
   dim folderCount
   folderCount = OutlookApp.Session.Folders.Count
   document.write("<p>There are " & folderCount & " top-level folders in this session. ")
   document.write("Here they are:</p><ul>")
   for i = 1 to folderCount
      dim fldr
      set fldr = OutlookApp.Session.Folders.Item(i)
      document.write("<li>" & fldr.Name & "</li>")
   document.title = "VBScript: the first try"
end function

When I click the button, the function shows the following output in my Outlook 2003. You can do the same in Outlook 2000, 2002 (XP) and Outlook 2007:

Custom HTML page shown in Outlook

As you can see, it is quite simple.

Add-in Express allows .NET developers to avoid such an extreme. It introduces the Advanced Outlook Form Regions technology, which among other features, empowers Outlook developers to quickly create custom forms / views in Outlook Today style.

Add-in Express provides a form class designed for deep integration with Outlook windowing: structures, chains, and procedures. To control the form, it supplies a special component, the Outlook Forms Manager. Let’s try this way.

In an Outlook COM add-in project, you add the above-mentioned form using the Add New Item dialog:

Add-in Express Outlook Form in the Add New Item dialog in Visual Studio 2008

Then you add a Forms Manager to the Add-in module:

Outlook Forms Manager added to the add-in module

In the properties window, you choose the Forms property and add an item to the collection:

Specifying item settings

This item tells the Outlook Forms Manager to show the form specified in the FormClassName property when the user navigates to the folder specified in the FolderName property. The form will be shown as the home page for that folder: this is specified by the value of the ExplorerLayout property.

Here is how my custom Outlook Today form works in Outlook 2007. Please remember that you can achieve the same result in Outlook 2000, 2002 and Outlook 2003:

Custom .NET form shown as a home folder page in Outlook

And this way is a really simple and easy one! Note that you can debug your form in the same manner as you debug any .NET project: specify the external program to run and press F5. As to deploying the form, Add-in Express provides both MSI and ClickOnce ways.

Andrei Smolin
Add-in Express Team Leader


  • acai nakita says:

    Just to add to this article. You must ensure that IE is set as your defult browser, otherwise this does not work.

  • Andrei Smolin (Add-in Express Team) says:

    I’ve just got a test html shown as a Home Page in Outlook 2010 with Firefox 5.0 set as the default browser. I tested showing a custom pane in the way described in the article: this works, too.

    If you can provide more info about your environment, I could try help you in resolving this issue. You can send me an email: please find the support email address in {Add-in Express installation folder}\readme.txt. And please make sure your email contains a link to this blog. Thank you.

  • Ara Nikita says:

    I tried the VBScript method in a local HTML file and I get the message Hello, developer! which means the outlook application obeject is nothing. Using Outlook 2013. I cannot get reference to Outlook application.

  • Andrei Smolin (Add-in Express Team) says:

    Hello Ara,

    For me, it works correctly in Outlook 2016. In my Outlook+Exchange, I’ve specified the path to the HTML file on the Properties dialog of the top-level folder of the default message store. The HTML file is there:

Post a comment

Have any questions? Ask us right now!