Outlook 2000 VBA Programmers Reference

This information is based on Dwayne Gifford’s book, Outlook 2000 VBA Programmers Reference

The Folders collection represents the available folders at any given level of the
folder hierarchy. The concept of the Folders collection is recursive in nature, meaning
that you can have as many levels of folders as you want. The screenshot below shows a
typical folder hierarchy indicating the different folder levels.

Blow Up!

You can see that the Mailbox – Dwayne Gifford Folders collection contains a number
of individual Folder objects, Calendar, Contacts, etc. Each folder can contain Outlook
items and MAPIFolders.

The various properties, methods and events of the Folders collection and Folder object
allow navigation to and manipulation of these folders and the items that they contain.

There are two ways to get a reference to a Folders collection. The first is through the
NameSpace object. This will return the root Folders collection

Syntax:

Dim ofcFolders as Folders
Dim onMAPI as NameSpace

Set ofcFolders = onMAPI.Folders

The second is from a MAPIFolder object. This will return the Folders collection
representing all folders contained by the specified MAPIFolder.

Dim ofcFolders as Folders
Dim ofFolder as MAPIFolder

Set ofcFolders = ofFolder.Folders

For example if we choose the Notes folder to be the MAPIFolder then the ofcFolders
collection would contain all folders starting Level 2.

Add Method

The Add method will create and return a new MAPIFolder object in the current Folders
collection.

Set MAPIFolderObject = FoldersCollection.Add(Name [, Type])

Valid OlDefaultFolder constants for this method are as follows:

The following constants are not valid when trying to create a new folder:

Example:

Dim onMAPI As NameSpace
Dim ofChosenFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofChosenFolder = onMAPI.PickFolder
ofChosenFolder.Folders.Add "Inbox 2", olFolderInbox

In the above example, the user is prompted by the Pick Folder dialog to choose one of
their folders. A new folder called "Inbox 2" is then created in the chosen. The
figure below shows the newly created "Inbox 2" MAPIFolder in the original Inbox
MAPIFolder.

Blow Up!

More details on the PickFolder method of the NameSpace object are given in chapter 6.

GetFirst Method

The GetFirst method allows you to navigate to the first MAPIFolder object in the
referenced collection. If there is no MAPIfolder object in the collection then Nothing is
returned.

Set MAPIFolderObject = FoldersCollection.GetFirst

It is always wise to first get a reference to the Folders collection before you use the
Get methods on the collection.

Example:

Dim onMAPI As NameSpace
Dim ofRootFolder As Folders
Dim ofFirstFolder as MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofRootFolder = onMAPI.Folders
Set ofFirstFolder = ofRootFolder.GetFirst
MsgBox ofFirstFolder

This simple example first sets a reference to the root folders collection. It then uses
the GetFirst method to get the first folder within this collection, having first declared
it to be a MAPIFolder. Finally its name is displayed in a message box.

GetLast Method

The GetLast method works in a similar fashion to the GetFirst method except it will
return the last MAPIFolder in the collection. If there are no folders in the collection it
will return Nothing.

Set MAPIFolder = FoldersCollection.GetLast

GetNext Method

The GetNext method moves to the next MAPIFolder in the collection.

Set MAPIFolderObject = FoldersCollection.GetNext

Example:

Dim ofcPersonalFolders As Folders
Dim ofFolder As MAPIFolder
Set ofcPersonalFolders =
Application.GetNamespace("MAPI").Folders.GetFirst.Folders
Set ofFolder = ofcPersonalFolders.GetFirst
Do Until ofFolder Is Nothing
MsgBox ofFolder.Name
Set ofFolder = ofcPersonalFolders.GetNext
Loop

In the example above we walk through the folders of the first Folders collection within
the Root folders collection for the current profile. For my profile the first collection
within the root folder collection is my Personal Folder. A reference is first set to this
folder and then the GetFirst and GetNext methods are used to move through each of the
folders in this collection. A Do Until loop is employed to check when the end of the
Folders collection is reached and the name of each folder is displayed in a message box.

GetPrevious Method

The GetPrevious method provides a way to move to a previous MAPIFolder object in the
current collection

Set MAPIFolderObject = FoldersCollection.GetPrevious

Again, I hate to repeat myself but it is always wise to get a reference to the
collection that you want to work with before you use any of the Get methods of the Folders
collection.

Item Method

The Item method provides a way to reference a particular MAPIFolder. This can be
achieved by using the index number of the MAPIFolder within the collection or by using the
name of the MAPIfolder.

Set MAPIFolderObject = FoldersCollection.Item(Index)

Example:

Dim onMAPI As NameSpace
Dim ofInbox As MAPIFolder
Dim ofFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofInbox = onMAPI.Folders.GetFirst.Folders.Item("Inbox")
Set ofFolder = onMAPI.Folders.GetFirst.Folders(2)

In this example we get references to two different folders. For the first variable,
ofInbox, we pick the folder by its name. The second variable, ofFolder, is set to the
second folder within the first folder in the root folders using the index of the folder.
For my personal setup this gives me a reference to the Contacts folder, although this may
differ for you. Because Item is the default method it is not necessary to type it
explicitly, as shown in the last line of code.

Remove Method

The Remove method will take the MAPIFolder referenced by the index parameter and
permanently remove it from the Folders collection.

FoldersCollection.Remove Index

Be aware that when a folder is removed with this method, it will remove ALL folders and
items within that folder without providing a warning.

Example:

Dim onMAPI As NameSpace
Dim ofFolder As MAPIFolder
Dim iFor As Integer
Set onMAPI = Application.GetNamespace("MAPI")
Set ofFolder = onMAPI.GetDefaultFolder(olFolderInbox)
ofFolder.Folders.Add "Inbox 3", olFolderInbox
For iFor = 1 To ofFolder.Folders.count
If ofFolder.Folders.Item(iFor).Name = "Inbox 3" Then
ofFolder.Folders.Remove iFor
Exit For
End If
Next

In this example we first add a MAPIFolder to the ofFolder object. We then walk through
the Folders collection to locate the MAPIFolder. Once we do locate it we use the Remove
method to delete it from the collection and exit the For…Loop.

Application Property

The Application property returns the Application object for the Folders collection.
This will be the Outlook Application object.

Set ApplicationObject = FoldersCollection.Application

Class Property

The Class property returns a unique value that identifies an object’s type. This
will be one of the OlObjectClass constants and in this case will be olFolders or 15.

Long = FoldersCollection.Class

Count Property

The Count property returns a long integer representing the number of MAPIFolder objects
in the collection.

Long = FoldersCollection.Count

Example:

Dim onMAPI As NameSpace
Dim ofcPersonalFolders As Folders
Dim ofFolder As MAPIFolder
Dim iFor As Integer
Set onMAPI = Application.GetNamespace("MAPI")
Set ofcPersonalFolders = onMAPI.Folders.Item("Mailbox – Dwayne
Gifford").Folders

For iFor = 1 To ofcPersonalFolders.Count
Set ofFolder = ofcPersonalFolders.Item(iFor)
MsgBox ofFolder.Name
Next

In this example a reference is set to the Folders collection of the Mailbox –
Dwayne Gifford folder. The Count property is then used to set the upper limit of the
For…Next construct, which is used to display the name of each of the folders within
the collection.

Parent Property

The Parent property returns the parent object of the Folders collection. This we either
be the NameSpace object or a MAPIFolder object.

Set MAPIFolderObject= FoldersCollection.Parent

Session Property

The Session property returns the NameSpace object for the current collection. You
should already have this object if you have a reference to a Folders collection.

Set NameSpaceObject = FoldersCollection.Session

For the Folders collection events to be fired it is necessary to use the WithEvents
keyword and set a reference to a Folders collection within a sub that will be called
before the event. For illustration purposes only I have set a reference to the Deleted
Items folders collection.

Example:

Dim WithEvents ofcFolders As Folders
Private Sub Class_Initialize()
Set ofcFolders = Application.GetNamespace("MAPI"). _
GetDefaultFolder(olFolderDeletedItems).Folders
End Sub

FolderAdd Event

The FolderAdd event occurs when a new MAPIFolder object is added to a collection.

Sub FoldersCollection_FolderAdd(ByVal Folder As MAPIFolder)

Example:

Private Sub ofcFolders_FolderAdd(ByVal Folder As MAPIFolder)
If Folder.UnReadItemCount <> 0 Then
MsgBox "This folder has unread items. You may _
want to reinstate it.", vbExclamation
End If
End Sub

In this example the user is warned if they delete a folder with unread items in it.
Firstly ofcFolders is set to be the Deleted Items Folders collection. This will be called
when an object based on this class is instantiated.

Within the FolderAdd event, a newly created folder is checked for unread items. If they
exist, the user is warned.

FolderChange Event

The FolderChange event occurs when one of the MAPIFolder objects, in the chosen Folders
collection, is changed.

Sub FoldersCollection_FolderChange(ByVal Folder As MAPIFolder)

FolderRemove Event

The FolderRemove event occurs when one of the MAPIFolder objects is deleted from the
chosen Folders collection.

Sub FoldersCollection_FolderRemove()

MAPIFolder Object

A MAPIFolder object is a container that can hold either folders or Outlook items, or
more likely both. A reference to a MAPIFolder object can be set by using the:

GetDefaultFolder, GetFolderFromID and GetSharedDefaultFolder method s of the NameSpace
object

Item, GetFirst, GetLast, GetNext and GetPrevious methods of a Folders collection

Syntax:

Set ofFolder = onMAPI.GetFolderFromID(sEntryID, sStoreID)

or

Set ofFolder = onMAPI.GetDefaultFolder(olFolderInbox)

or

Set ofFolder = onMAPI.GetSharedDefaultFolder(orRecipient, olFolderInbox)

or

Ser ofFolder = onMAPI.Folders.Item("Inbox")

or

set ofFolder = onMAPI.Folders.GetFirst

These methods are covered fully in chapter 6 and earlier in this chapter.

CopyTo Method

The CopyTo method takes the currently referenced MAPIFolder and makes a copy of it and
its contents in the specified destination MAPIFolder.

MAPIFolderObject.CopyTo(DestinationFolderObject)

Example:

Dim onMAPI As NameSpace
Dim ofStart As MAPIFolder
Dim ofDestination As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofStart = onMAPI.GetDefaultFolder(olFolderInbox)
Set ofDestination = onMAPI.GetDefaultFolder(olFolderOutbox)
ofStart.CopyTo ofDestination

In this example we are creating a copy of the Inbox folder in the Outbox folder. If
there is already a folder called Inbox here then the method will add a sequence number to
the end of the new object. The CopyTo method is likely to be used to create back-ups of
important folders.

Delete Method

The Delete method provides a way to remove a MAPIFolder object. It will delete this
MAPIFolder object from its parent Folders collection.

MAPIFolderObject.Delete

This method works in the same way as the delete option on the GUI. However, if the
folder is located within the Deleted Items folder, there is no warning massage or option
to cancel the delete.

Display Method

The Display method displays a new Explorer for the MAPIFolder with the current object
as the active MAPIFolder. An Explorer is an Outlook window that shows the contents of a
folder. So if you already have an Outlook window open for the user, this method will open
a new Outlook window in front of the user with the contents of the specified MAPIFolder
visible. It will not make any changes to the old Explorer. The Explorer object is fully
covered in chapter 7.

MAPIFolderObject.Display

Example:

Dim onMAPI As NameSpace
Dim ofFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofFolder = onMAPI.GetDefaultFolder(olFolderInbox)
ofFolder.Display

In the above example the ofFolder variable is set to the default Inbox folder. Then a
new Explorer object is opened with this MAPIFolder object as the active folder.

GetExplorer Method

The GetExplorer method returns an invisible Explorer object that has the specified
MAPIFolder object as its active folder. Once you have this Explorer object you can use the
Activate method of the Explorer object to show it.

MAPIFolderObject.GetExplorer([DisplayMode])

The result of using each of the OlFolderDisplayMode constants is shown below.

OlFolderDisplayFolderOnly (1) displays, next to the Folder name, a drop-down list of
folders available. All navigation buttons are also available. Notice the figure below has
all navigation buttons on the toolbar.

Blow Up!

olFolderDisplayNoNavigation (2) displays the current MAPIFolder and the user is unable
to navigate to any other MAPIFolder object. Notice that the navigational buttons on the
toolbar are invisible.

Blow Up!

olFolderDisplayNormal (0) displays the Explorer just as it appears when you open
Outlook.

Blow Up!

Example:

Dim onMAPI As NameSpace
Dim ofFolder As MAPIFolder
Dim oeExplorer As explorer
Set onMAPI = Application.GetNamespace("MAPI")
Set ofFolder = onMAPI.GetDefaultFolder(olFolderDrafts)
Set oeExplorer = ofFolder.GetExplorer(olFolderDisplayNoNavigation)
oeExplorer.Activate

This code was used to show the second Explorer object in the set of three above,
displaying the default Drafts folder with no folder navigation available. The Activate
method of the Explorer object is used to show the MAPIFolder to the user. Note that the
optional display mode parameter only comes into play when the Explorer object methods are
used to show it and not the Display method of the MAPIFolder.

MoveTo Method

The MoveTo method moves a MAPIFolder to a specified MAPIFolder object.

MAPIFolderObject.CopyTo(DestinationFolderObject)

Application Property

The Application property will return the parent application object of the MAPIFolder
object. This will be the Outlook Application object.

Set ApplicationObject = MAPIFolderObject.Application

Class Property

The Class property returns a unique value that identifies the object’s type. This
will be one of the OlObjectClass constants and in this case will be olFolder or 2.

Long = MAPIFolderObject.Class

DefaultItemType Property

The DefaultItem property returns the default item type for the MAPIFolder. This
property specifies what type of Outlook item a folder possesses by default, i.e. if you
create a new item without supplying the Type then its type will be set according to the
DefaultItemType of the folder it is added to.

Long = MAPIFolderObject.DefaultItemType

The value returned will be one of the following OlItemType contants:

DefaultMessageClass Property

The DefaultMessageClass property returns, as a string, the Message Class, or type of
message, for the MAPIFolder. This is the MessageClass property that, if not otherwise
explicitly set, is assigned to an Outlook item by default when added to a folder. This
value identifies the default Inspector object in which an item will be shown.

String = MAPIFolderObject.DefaultMessageClass

The possible values that will be returned are as follows:

There is a one to one relationship between this property and the DefaultItemType
property

Example:

Dim onMAPI As NameSpace
Dim ofcRoot As Folders
Dim ofPersonalFolder As MAPIFolder
Dim ofcPFolders As Folders
Dim ofFolder As MAPIFolder
Set onMAPI = Application.GetNamespace("MAPI")
Set ofcRoot = onMAPI.Folders
Set ofPersonalFolder = ofcRoot.Item("Mailbox – Dwayne Gifford")
Set ofcPFolders = ofPersonalFolder.Folders

For Each ofFolder In ofcPFolders
Debug.Print ofFolder.Name, ofFolder.DefaultMessageClass, ofFolder.DefaultItemType
Next

This example walks through my Personal folders and displays both the
DefaultMessageClass and DefaultItemType properties in the Immediate Window. The results
are shown below.

Description Property

The Description property sets or returns a string value that provides information about
the MAPIFolder. This property can be viewed in the Description box that you see in the
Properties box for the MAPIFolder. For compatibility it corresponds to the PR_COMMENT
property used in MAPI.

Blow Up!

String = MAPIFolderObject.Description

MAPIFolderObject.Description = String

I would suggest that if you are creating important MAPIFolders through code on a
user’s machine then it is worth using this Description property to tell the user the
purpose of the folder and that it should not be deleted.

EntryID Property

The EntryID property returns a unique ID for the MAPIFolder. It is created when the
MAPIFolder is created or moved to a different folder. It may be used in conjunction with
the GetFolderFromID method of the NameSpace object.

String = MAPIFolderObject.EntryID

This property is here for backwards compatibility with MAPI.

Folders Property

The Folders property returns the collection of folders that belong to the specified
MAPIFolder, i.e. the sub-folders of the current object.

Set FoldersCollection = MAPIFolderObject.Folders

These Folders collections are recursive in nature, i.e. any one of the MAPIFolder
objects in the Folders collection can contain its own Folders collection. The only way to
ensure that you are at the bottom of a hierarchy of folders is to check that the Count
property of the Folders collection equals 0.

Items Property

The Items property returns the collection of items within the specified MAPIFolder
object.

Set ItemsCollection = MAPIFolderObject.Items

From this collection we have the ability to navigate around and work with the various
Outlook Items. The Items collection and each of the Outlook items are covered fully in
chapters 12 to 18.

Name Property

The Name property returns a string that represents the name of the MAPIFolder object.
You can also set the name value using this property. The Name property of the folders is
shown when you view the Outlook folders hierarchy.

String = MAPIFolderObject.Name

MAPIFolderObject.Name = String

If, within a particular Folders collection, you try to set the Name property of a
MAPIFolder to the name of an already existing MAPIFolder an error will be raised.

Parent Property

The Parent property returns the parent object for the current object. In this case
since we are looking at a MAPIFolder object the parent will the MAPIFolder object directly
above it in the folders hierarchy.

Set MAPIFolderObject = MAPIFolderObject.Parent

UnReadItemCount Property

The UnReadItemCount property returns a long integer representing the number of messages
within the current MAPIFolder that have not been read.

Long = MAPIFolderObject.UnReadItemCount

StoreID Property

The StoreID property returns a unique ID of the MAPIFolder object. This value is set
when the object is created or moved to a new Folders collection. It is not clear why two
unique ID’s, i.e. the EntryID and the StoreID are required.

String = MAPIFolderObject.StoreID

Session Property

The Session property returns the NameSpace object for the current session. This will be
the MAPI.

Set NameSpaceObject = MAPIFolderObject.Session

WebViewAllowNavigation Property

The WebViewAllowNavigation property returns or sets a Boolean value indicating the
“navigation mode” for the Web view.

Boolean = MAPIFolderObject.WebViewAllowNavigation

MAPIFolderObject.WebViewAllowNavigation = Boolean

By setting this to True the user has ability to use the Back and Forward buttons for
Web navigation.

WebViewOn Property

The WebViewOn property returns or sets a Boolean value indicating the Web “view
state” for the current MAPIFolder object. If set to True then Outlook is told to
display the Web page specified in the WebViewURL property.

Boolean = MAPIFolderObject.WebViewOn

MAPIFolderObject.WebViewOn = Boolean

WebViewURL Property

The WebViewURL property returns or sets a string value indicating the URL of the web
page assigned to this MAPIFolder object.

String = MAPIFolderObject.WebViewURL

MAPIFolderObject.WebViewURL = String

This information is based on Dwayne Gifford’s book, Outlook 2000 VBA Programmers Reference