MORE INFORMATION
Microsoft provides programming examples for illustration only, without
warranty either expressed or implied, including, but not limited to, the
implied warranties of merchantability and/or fitness for a particular
purpose. This article assumes that you are familiar with the programming
language being demonstrated and the tools used to create and debug
procedures. Microsoft Support professionals can help explain the functionality
of a particular procedure, but they will not modify these examples to
provide added functionality or construct procedures to meet your specific
needs. If you have limited programming experience, you may want to contact
the Microsoft fee-based consulting line at (800) 936-5200. For more
information about the support options available from Microsoft, please see
the following page on the World Wide Web:
Note: Visual Basic Scripting Edition (VBScript) code must use the numeric
value of the constants that are defined in the Outlook object library. You
can find a listing of these values in the Microsoft Outlook object library
Help file (Vbaoutl.hlp) under the "Microsoft Outlook Constants" Topic.
Referencing Existing Folders
GetDefaultFolder Method:
Default folders are those that are at the same level as the Inbox that
receives incoming mail. If you have more than one Inbox in your profile,
pressing CTRL+SHIFT+I always selects the default Inbox. The default folders
are those that most users work with on a regular basis, such as the
Calendar, Contacts, and Tasks folders. You can easily refer to these
folders using the GetDefaultFolder method. GetDefaultFolder takes one
argument, which is the type of folder you want to refer to. The following
examples assign the object variable MyFolder to the default Contacts
folder:
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set MyFolder = olns.GetDefaultFolder(10)
Folders Object:
You can use the Folders object to refer to any folder that is visible in
the Outlook folder list. This object is typically used to refer to an
Exchange public folder or any other folder that is not a default Outlook
folder.
The following examples illustrate how to refer to a public folder called
"My Public Folder." Note that you typically start at the top-most folder
and work your way down to the folder you need to reference. Also note that
the folder names are case-sensitive and must exactly match the names as
they appear in the Outlook folder list.
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set MyFolder1 = olns.Folders("Public Folders")
Set MyFolder2 = MyFolder1.Folders("All Public Folders")
Set MyFolder3 = MyFolder2.Folders("My Public Folder")
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set MyFolder1 = olns.Folders("Public Folders")
Set MyFolder2 = MyFolder1.Folders("All Public Folders")
Set MyFolder3 = MyFolder2.Folders("My Public Folder")
The following examples illustrate how you can refer to a folder called
"Business Tasks," which is a subfolder of the default Tasks folder.
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set MyTasksFolder = olns.GetDefaultFolder(olFolderTasks)
Set MyFolder = MyTasksFolder.Folders("Business Tasks")
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set MyTasksFolder = olns.GetDefaultFolder(13)
Set MyFolder = MyTasksFolder.Folders("Business Tasks")
Parent Property:
If you already have a reference to an Outlook item or folder, then you can
use its Parent property to create a reference to the folder the item or
folder is located in.
The following examples return the name of a folder for a particular item:
' Automation code example.
Set ol = New Outlook.Application
Set MyItem = ol.CreateItem(olMailItem) ' Create new item.
MyItem.Save ' Save it to Inbox.
Set MyFolder = MyItem.Parent ' MyFolder = Inbox.
' VBScript code example.
' Returns the folder of the current item.
Set MyFolder = Item.Parent
GetSharedDefaultFolder:
You can use this method if someone has given you delegate permissions to
one of their default folders. In addition, you must have already connected
to the folder in Outlook by clicking the File menu, clicking Open Special
Folder, and then clicking Exchange Server Folder.
For more information about accessing the folders of other people, please
see the following article in the Microsoft Knowledge Base:
160302 OL97: How to Open Someone Else's Calendar or Other Folder
Once Outlook is set up to use someone else's folder, the
GetSharedDefaultFolder method is used in the same fashion as
GetDefaultFolder, except you specify one additional argument -- the name of
the other person's folder you want to reference. This example first
resolves the other person's name to verify that it is a valid name that can
be used with the GetSharedDefaultFolder method.
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set myRecipient = olns.CreateRecipient("John Smith")
myRecipient.Resolve
If myRecipient.Resolved Then
Set JohnFolder = olns.GetSharedDefaultFolder _
(myRecipient, olFolderContacts)
End If
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set myRecipient = olns.CreateRecipient("John Smith")
myRecipient.Resolve
If myRecipient.Resolved Then
Set JohnFolder = olns.GetSharedDefaultFolder _
(myRecipient, 10)
End If
GetFolderFromID:
This method would typically be used only in more complex solutions where a
solution keeps track of both the StoreID and EntryID of a folder so that it
can be quickly referenced at a later time.
For more information about using the GetFolderFromID method, please see
the following article in the Microsoft Knowledge Base:
170991 OL97: Programming with EntryIDs, StoreIDs and GetItemFromID
Creating and Referencing New Folders
Folders.Add Method:
Using the Add method on the Folders collection allows you to create a new
folder. The first argument specifies the name of the folder and the second
argument specifies the type of folder. The following example adds a
Business Tasks folder under your default tasks folder. Because the folder
type is not specified, it will inherit the type of the parent folder.
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set MyTasksFolder = olns.GetDefaultFolder(olFolderTasks)
Set MyNewFolder = MyTasksFolder.Folders.Add("Business Tasks")
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set MyTasksFolder = olns.GetDefaultFolder(13)
Set MyNewFolder = MyTasksFolder.Folders.Add("Business Tasks")
Creating and Referencing New Items
CreateItem Method:
The CreateItem method creates a new default Outlook item. If you need to
create an item based on a custom form you have created, use the Items.Add
method below. The CreateItem method is conveniently located off of the top-
level application object in the Outlook object model. The method takes only
one argument, a constant indicating the type of item to create.
' Automation code example.
Set ol = New Outlook.Application
Set MyTaskItem = ol.CreateItem(olTaskItem)
MyTaskItem.Display
' VBScript code example.
Set MyTasktem = Item.Application.CreateItem(13)
MyTaskItem.Display
Items.Add Method:
Using the Add method on the Items collection allows you to create a new
item based on any message class, whether it is a default Outlook message
class such as IPM.Contact, or a message class for a custom form, such as
IPM.Contact.MyForm. In order to use the Items.Add method, you must first
reference the folder where you want to create a new item.
For more information about message classes, please see the following
articles in the Microsoft Knowledge Base:
176567 OL97: Working with Form Definitions and One-Off Forms
170301 OL97: How to Update Existing Items to Use a New Custom Form
The following examples use the Items.Add method to create a new item based
on a custom contact form called MyForm:
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set myFolder = olns.GetDefaultFolder(olFolderContacts)
Set MyItem = MyFolder.Items.Add("IPM.Contact.MyForm")
MyItem.Display
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set myFolder = olns.GetDefaultFolder(10)
Set MyItem = MyFolder.Items.Add("IPM.Contact.MyForm")
MyItem.Display
The following examples use the Items.Add method to create a new default
contact item:
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set myFolder = olns.GetDefaultFolder(olFolderContacts)
Set MyItem = MyFolder.Items.Add
MyItem.Display
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
Set myFolder = olns.GetDefaultFolder(10)
Set MyItem = MyFolder.Items.Add
MyItem.Display
NOTE: If you use the Items.Add method, it does not matter what the default
form for the folder is. You can specify any valid message class as long as
it has been published in the folder or has been published in the personal
or organizational forms library.
CreateItemFromTemplate Method:
Use the CreateItemFromTemplate method to create a new item based on an
Outlook template file (.oft) or .msg file format. Because most forms are
published in a folder or forms library, this method is not commonly used.
Probably the most common reason to use this method would be if you were
creating a Microsoft Visual Basic Setup program to install forms for an
Outlook solution. This would typically be done for users who do not have
network access or typically work off-line in Outlook. The Visual Basic
program would do the following:
- Automate Outlook.
- Use CreateItemFromTemplate to open a form from a network share
or floppy disk.
- Using the Outlook object model, publish the form for later use.
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
' Set MyItem to an .oft file on a floppy disk.
Set MyItem = ol.CreateItemFromTemplate("A:\Contact.oft")
' Set MyForm to the item Form Description for publishing.
Set MyForm = MyItem.FormDescription
' Name the form, which also sets its message class.
MyForm.Name = "My Contact"
' Publish the folder to the Contacts folder.
MyForm.PublishForm olFolderRegistry, MyFolder
' Close and do not save changes to the item.
MyItem.Close olDiscard
Referencing Existing Items
Using Items(I) or For Each...Next:
Typically these approaches are used to loop through all of the items in a
folder. The Items collection contains all of the items in a particular
folder, and you can specify which item to reference by using an index with
the Items collection. This is typically used with the For I = 1 to n
programming construct.
If you are using VBScript version 2.0 or later, you can instead use the For
Each...Next programming construct to loop through the items in the
collection without specifying an index. Both approaches achieve the same
result.
The following examples use the Items(I) approach to loop through all of the
contacts in the Contacts folder and display their FullName field in a
dialog box.
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
' Get the number of items in the folder.
NumItems = MyFolder.Items.Count
' Set MyItem to the collection of items in the folder.
Set MyItems = MyFolder.Items
' Loop through all of the items in the folder.
For I = 1 to NumItems
MsgBox MyItems(I).FullName
Next
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(10)
' Get the number of items in the folder.
NumItems = MyFolder.Items.Count
' Set MyItem to the collection of items in the folder.
Set MyItems = MyFolder.Items
' Loop through all of the items in the folder.
For I = 1 to NumItems
MsgBox MyItems(I).FullName
Next
The following examples use the For Each...Next construct to achieve the
same result as the preceding examples:
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
' Set MyItems to the collection of items in the folder.
Set MyItems = MyFolder.Items
For Each SpecificItem in MyItems
MsgBox SpecificItem.FullName
Next
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
' Set MyFolder to the default contacts folder.
Set MyFolder = olns.GetDefaultFolder(10)
' Set MyItem to the collection of items in the folder.
Set MyItems = MyFolder.Items
For Each SpecificItem in MyItems
MsgBox SpecificItem.FullName
Next
Using Items("This is the subject"):
You can also use the Items collection and specify a text string that
matches the Subject field of an item. This approach is not commonly used.
The following examples display an item in the Inbox whose subject contains
"Please help on Friday!"
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
' Set MyFolder to the default Inbox.
Set MyFolder = olns.GetDefaultFolder(olFolderInbox)
Set MyItem = MyFolder.Items("Please help on Friday!")
MyItem.Display
' VBScript code example.
Set olns = Item.Application.GetNameSpace("MAPI")
' Set MyFolder to the default Inbox.
Set MyFolder = olns.GetDefaultFolder(6)
Set MyItem = MyFolder.Items("Please help on Friday!")
MyItem.Display
Find Method:
Use the Find method to search for an item in a folder based on the value of
one of its fields. If the Find is successful, you can then use the FindNext
method to check for additional items that meet the same search criteria.
The following examples search to see if you have any high priority
appointments.
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNamespace("MAPI")
Set myFolder = olns.GetDefaultFolder(olFolderTasks)
Set MyTasks = myFolder.Items
' Importance corresponds to Priority on the task form.
Set MyTask = MyTasks.Find("[Importance] = ""High""")
If MyTask Is Nothing Then ' the Find failed
MsgBox "Nothing important. Go party!"
Else
MsgBox "You have something important to do!"
End If
' VBScript code example.
Set olns = Item.Application.GetNamespace("MAPI")
Set myFolder = olns.GetDefaultFolder(13)
Set MyTasks = myFolder.Items
' Importance corresponds to Priority on the task form.
Set MyTask = MyTasks.Find("[Importance] = ""High""")
If MyTask Is Nothing Then ' the Find failed
MsgBox "Nothing important. Go party!"
Else
MsgBox "You have something important to do!"
End If
Restrict Method:
The Restrict method is similar to the Find method, but instead of returning
a single item, it returns a collection of items that meet the search
criteria. For example, you might use this method to find all contacts who
work at the same company.
The following examples display all of the contacts who work at ACME
Software:
' Automation code example.
Set ol = New Outlook.Application
Set olns = ol.GetNameSpace("MAPI")
Set MyFolder = olns.GetDefaultFolder(olFolderContacts)
Set MyItems = MyFolder.Items
MyClause = "[CompanyName] = ""ACME Software"""
Set MyACMEItems = MyItems.Restrict(MyClause)
For Each MyItem in MyACMEItems
MyItem.Display
Next
' VBScript code example.
' Requires VBScript version 2.0 or later.
Set olns = Item.Application.GetNameSpace("MAPI")
Set MyFolder = olns.GetDefaultFolder(10)
Set MyItems = MyFolder.Items
MyClause = "[CompanyName] = ""ACME Software"""
Set MyACMEItems = MyItems.Restrict(MyClause)
For Each MyItem in MyACMEItems
MyItem.Display
Next
GetItemFromID Method:
This method would typically be used only in more complex solutions where a
solution keeps track of both the StoreID and EntryID of an item so that it
can be quickly retrieved at a later time.
For more information about using the GetItemFromID method, please see the
following article in the Microsoft Knowledge Base:
170991 OL97: Programming with EntryIDs, StoreIDs and GetItemFromID