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.
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])
Name | Data type | Description |
Name | String | Required, the name of the folder that you see in Outlook. |
Type | Long | Optional, can be one of the OlDefaultFolder constants. If no type is supplied then the new MAPIFolder will inherit its Type from the parent MAPIFolder. |
Valid OlDefaultFolder constants for this method are as follows:
Constant | Value | Description |
olFolderCalendar | 9 | Creates a new Calendar folder |
olFolderContacts | 10 | Creates a new Contacts folder |
olFolderDrafts | 16 | Creates a new Drafts folder |
olFolderInbox | 6 | Creates a new Inbox folder |
olFolderJournal | 11 | Creates a new Journal folder |
olFolderNotes | 12 | Creates a new Notes folder |
olFolderTasks | 13 | Creates a new Tasks folder. |
The following constants are not valid when trying to create a new folder:
Constant | Value | Description |
olFolderDeletedItems | 3 | Represents a DeletedItems folder |
olFolderOutbox | 4 | Represents a Outbox folder |
olFolderSentMail | 5 | Represents a SentMail 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.
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)
Name | Data type | Description |
Index | Variant | Required, either a long representing the position of the MAPIFolder object within the collection or its name as a string. |
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
Name | Data type | Description |
Index | Long | Required, represents the position of the MAPIFolder object within the collection that you wish to remove. |
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)
Name | Data type | Description |
Folder | MAPIFolder | The new MAPIFolder object that is being added to the Folders collection. |
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)
Name | Data type | Description |
Folder | MAPIFolder | The MAPIFolder object that is being changed to the Folders collection. |
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)
Name | Data type | Description |
DestinationFolderObject | MAPIFolder | Required, the Folder object that you wish to hold the copy in |
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])
Name | Data type | Description |
DisplayMode | Long | Optional, one of the OlFolderDisplayMode constants. If omitted olFolderDisplayNormal is use by default. |
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.
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.
olFolderDisplayNormal (0) displays the Explorer just as it appears when you open
Outlook.
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)
Name | Data type | Description |
DestinationFolderObject | MAPIFolder | Required, the destination Folder object that you wish to move the FolderObject to. |
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:
Constant | Value | Description |
olAppointmentItem | 1 | An Appointment item |
olContactItem | 2 | A Contact item |
olJournalItem | 4 | A Journal item |
olMailItem | 0 | A Mail item. This is the default item for Outlook and the default type for all MAPIFolder objects that hold Mail type Items. |
olNoteItem | 5 | A Note item |
olPostItem | 6 | A Post item |
olTaskItem | 3 | A Task Item |
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:
IPM.Activity | IPM.Appointment | IPM.Contact |
IPM.Note | IPM.StickyNote | IPM.Task |
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.
Folder Name | DefaultMessageClass | DefaultItemType |
Calendar | IPM.Appointment |
1 |
Contacts | IPM.Contact |
2 |
Deleted Items | IPM.Note |
0 |
Drafts | IPM.Note |
0 |
Inbox | IPM.Note |
0 |
Journal | IPM.Activity |
4 |
Notes | IPM.StickyNote |
5 |
Outbox | IPM.Note |
0 |
Sent Items | IPM.Note |
0 |
Tasks | IPM.Task |
3 |
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.
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