The Outlook Object Model

You can find the Outlook object-model reference by following these steps:

1. Launch or switch to Outlook, and then click Developer ➢ Visual Basic to switch to the VBA Editor.
2. In the Editor, click Help ➢ Microsoft Visual Basic For Applications Help F1.

   Although it says that F1 is an alternative way to get to the same web page, it's not.

3. Click the Outlook VBA Reference link in the web page.
4. Click the Object Model link on the left side of the web page.

You'll now have access to the whole collection of Outlook 2019 VBA objects, their syntax specifications, useful descriptions, and code examples (one of which is shown in Figure 26.1).

Understanding Where Outlook Stores VBA Macros

As you saw earlier in this book, Word and Excel let you store VBA projects either in a global location (the Normal.dotm template in Word or the Personal Macro Workbook in Excel) or in individual templates or document files. PowerPoint lets you store VBA projects in presentation files and templates.

Outlook, by contrast, doesn't let you store VBA projects in its individual items (such as its email messages or contacts). Instead, Outlook saves all projects in one file called VbaProject.OTM, which is stored in the following folder:

C:UsersRichardAppDataLocalPackagesMicrosoft.Office.Desktop_8wkay0ofk3dbLocalCacheRoamingMicrosoftOutlook

The file will be created as soon as you close Outlook 2019 after having created your first macro.

Instead of Richard in this path, substitute your username, and instead of Desktop_8wkay0ofk3db your location code will differ. So you're best off just using File Explorer to search for VbaProject.OTM. Or if you prefer a far superior file-search utility, download a tool named Everything from Ninite.com.

Understanding Outlook's Most Common Creatable Objects

In Outlook VBA, the Application object represents the entire Outlook application, so you can access any Outlook object by going through the Application object. However, Outlook also exposes various creatable objects, allowing you to reach some of the objects in its object model without explicitly going through the Application object. Recall that “creatable” merely means that when you're writing code involving these objects, using the word Application is optional. You can get the same result by using either of the following code styles:

Application.Explorers

or more simply,

Explorers

Here is a list of Outlook's most common creatable objects; you'll work with most of them in more detail later in this chapter and in the next chapter:

• The Explorers collection contains an Explorer object for each window that displays the contents of a folder.
• The Inspectors collection contains an Inspector object for each window that's open displaying an Outlook item.
• The COMAddIns collection contains a COMAddIn object for each COM (Component Object Model) add-in loaded in Outlook.
• The Reminders collection contains a Reminder object for each reminder.

The most prominent objects in the Outlook user interface are represented in VBA by items with names that are descriptive of their purpose, such as these, for example:

• The MailItem object represents a mail item.
• The ContactItem object represents a contact.
• The TaskItem object represents a task.
• The AppointmentItem object represents an appointment.
• The JournalItem object represents a journal entry.
• The NoteItem object represents a note.

You'll learn how to work with these objects later in this chapter and in the next chapter.

Introducing the NameSpace Object

Here is a new concept: the NameSpace. Among all the VBA-enabled Office applications, only Outlook employs this technique. That the NameSpace approach is unique to Outlook demonstrates beyond all doubt that the various Microsoft Office application teams work—to put it politely—somewhat independently when building their object-model structures.

Working with Namespaces

Many Outlook VBA activities, such as accessing email messages, tasks, or contacts programmatically, require that you use the GetNameSpace method of Outlook's Application object to return a NameSpace object that represents the root object of the data source. Anyway, that's the official version.

Just remember that you use the following syntax to get most jobs done in Outlook VBA:

expression.GetNameSpace(Type)

Here, expression is a required expression that returns an Application object. Type is a required String argument that specifies the type of namespace you want to return. Outlook supports only the MAPI data source, so you always use Type: = “MAPI” with the GetNameSpace method. For example, the following statement returns the NameSpace and uses the CurrentUser property to display the name of the current user in a message box:

MsgBox Application.GetNamespace("MAPI").CurrentUser

ACCESSING OTHER FOLDERS WITHIN THE NAMESPACE OBJECT

Accessing the default folders in the NameSpace object via the GetDefaultFolder method is easy, but often you'll need to access other folders. In this case, you do use the Folders collection.

The following example displays a message box (see Figure 26.2) containing a list of all the folders contained in the namespace:

Sub List_All_NameSpace_Folders()
    Dim myNS As NameSpace
    Dim myFolder As MAPIFolder
    Dim mySubfolder As MAPIFolder
    Dim strFolderList As String
 
    strFolderList = "Your Outlook NameSpace contains these folders:" _
        & vbCr & vbCr
 
    Set myNS = Application.GetNamespace("MAPI")
    With myNS
        For Each myFolder In myNS.Folders
            strFolderList = strFolderList & myFolder.Name & vbCr
            For Each mySubfolder In myFolder.Folders
                strFolderList = strFolderList & "*  " & mySubfolder.Name & vbCr
            Next mySubfolder
        Next myFolder
 
    End With
    MsgBox strFolderList, vbOKOnly + vbInformation, "Folders in NameSpace"
 
End Sub

Understanding Inspectors and Explorers

VBA uses two major Outlook objects that most users wouldn't recognize from working with the Outlook user interface alone:

• An Inspector is an object that represents a window displaying a specific Outlook item, such as an email message or an appointment.
• An Explorer object represents a window that displays the contents of a folder, such as a list of emails.

Creating Items

To create new items in Outlook, you use the CreateItem method or the CreateItemFromTemplate method of the Application object. The CreateItem method creates default items, while the CreateItemFromTemplate method creates items based on the templates you specify.

Quitting Outlook

To quit Outlook, use the Quit method of the Application object. This method takes no arguments:

Application.Quit

You may also want to work with the events available to the Application object. See Chapter 27, “Working with Events in Outlook,” for a discussion of how to work with these application-level events and with item-level events.

Using the Display Method

To open an item in an Inspector window, use the Display method. The syntax is as follows:

expression.Display(Modal)

Here, expression is a required expression that returns the type of object you want to display—for example, a ContactItem object or a MailItem object. Modal is an optional Variant argument that you can set to True to make the window modal. A window is modeless by default, or it becomes modeless if you set Modal to False. Making the window modal means that users must close the window before they can work with another window.

Note that the Modal argument isn't available for Explorer and MAPIFolder objects.

For example, the following statement uses the Display method to display the Inbox:

Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox).Display

Using the Close Method

To close a window, use the Close method. The syntax is as follows:

expression.Close(SaveMode)

Here, expression is a required expression that returns the object you want to close. SaveMode is a required argument that specifies whether to save changes (olSave), discard the changes (olDiscard), or prompt the user to decide whether to save the changes (olPromptForSave).

The following example closes the active inspector and saves any changes to its contents:

ActiveInspector.Close SaveMode:=olSave

Remember that this code requires that an inspector be currently open. See the warning earlier in this chapter in the section titled “Working with the Active Inspector.”

Using the PrintOut Method

To print an item, use the PrintOut method. This method takes no arguments. The following example prints the item with the index number 1 in the Inbox:

Application.GetNamespace("MAPI").GetDefaultFolder(olFolderInbox) _
    .Items(1).PrintOut

Using the Save Method

To save an item, use the Save method. This method takes no arguments. The following example creates a new task; assigns it a subject, start date (today), and due date (a week from today); turns off the reminder for the task; and then saves it:

Dim myTask As TaskItem
Set myTask = Application.CreateItem(ItemType:=olTaskItem)
With myTask
    .Subject = "Arrange Review Meeting"
    .StartDate = Date
    .DueDate = Date + 7
    .ReminderSet = False
    .Save
End With

This item will appear in the ToDo list of the MyTasks section of your Outlook Tasks. Look in the lower-left corner of your Outlook window, as shown in Figure 26.3.

Using the SaveAs Method

To save an item as a separate file, use the SaveAs method. The syntax is as follows:

expression.SaveAs(Path, Type)

Here, expression is a required expression that returns the object to be saved. Path is a required String argument that specifies the path and filename under which to save the file. Type is an optional Variant argument that you can use to control the file type used for the file, as shown in Table 26.1.

The following example saves the message open in the active inspector. So before testing this example, be sure that a message has been double-clicked and is, thus, open in its own window separate from the main Outlook window. Remember that code involving the active inspector requires that an inspector be currently open. See the warning, and a way to error-trap this, earlier in this chapter in the section titled “Working with the Active Inspector.”

If the IsWordMail property of the ActiveInspector object returns True, the example saves the message as a .doc file; if the IsWordMail property returns False, the example saves the message as an .rtf file. If no Inspector window is active, the example displays a message box pointing out that problem to the user:

If TypeName(ActiveInspector) = "Nothing" Then
    MsgBox "This macro cannot run because " & _
        "there is no active window.", vbOKOnly, "Macro Cannot Run"
    End
Else
    If ActiveInspector.IsWordMail Then
        ActiveInspector.CurrentItem.SaveAs "c:	empmessage.doc"
    Else
        ActiveInspector.CurrentItem.SaveAs "c:	empmessage.rtf"
    End If
End If

To test this example, ensure that there's a emp folder on your C: drive.

Creating a New Message

To create a new message, use the CreateItem method of the Application object and specify olMailItem for the ItemType argument. The following example creates a MailItem object variable named myMessage and assigns to it a new message:

Dim myMessage As MailItem
Set myMessage = Application.CreateItem(ItemType:=olMailItem)

Working with the Contents of a Message

To work with the contents of a message, set or get the appropriate properties. These are the most widely useful properties:

• To is the recipient or recipients of the message.
• CC is the recipient or recipients of copies of the message.
• BCC is the recipient or recipients of blind copies of the message.
• Subject is the subject line of the message.
• Body is the body text of the message.
• BodyFormat is the message's formatting type: olFormatPlain for text only, olFormatRichText for text with formatting, and olFormatHTML for HTML formatting.
• Importance is the relative importance of the message. Set it to olImportanceHigh, olImportanceNormal, or olImportanceLow.

The following example creates a new message item and assigns it to the object variable myMessage. It then adds an addressee, a subject, and body text; applies the HTML format; sets the importance to high; and sends the message:

Dim myMessage As Outlook.MailItem
 
Set myMessage = Application.CreateItem(olMailItem)
 
With myMessage
    .To = "[email protected]"
    .Subject = "Preparation for Review"
    .BodyFormat = olFormatHTML
    .HTMLBody = "Please drop by tomorrow and spend a few minutes" _
        & " discussing the materials we need for Darla's review."
    .Importance = olImportanceHigh
    .Display
End With

When this message, shown in Figure 26.4, is created, all the data you fed it appears where you'd expect it to.

Adding an Attachment to a Message

To add an attachment to a message, use the Add method with the Attachments collection, which you return by using the Attachments property of the MailItem object. The syntax is as follows:

expression.Add(Source, Type, Position, DisplayName)

Here are the components of the syntax:

• expression is a required expression that returns an Attachments collection.
• Source is a required String argument that specifies the path and filename of the attachment.
• Type is an optional String argument that you can use to specify the type of attachment.
• Position is an optional String argument that you can use with rich-text messages to specify the character at which the attachment is positioned in the text. Use character 0 to hide the attachment, 1 to position the attachment at the beginning of the message, or a higher value to position the attachment at the specified character position. To position the attachment at the end of the message, use a number higher than the number of characters in the message.
• DisplayName is an optional String argument that you can specify to control the name displayed for the attachment in the message.

The following example attaches to the message referenced by the object variable myMessage the file Corporate Downsizing.pptm stored in the folder Y:Sample Documents, positioning the attachment at the beginning of the message and setting its display name to Downsizing Presentation:

myMessage.Attachments.Add _
    Source:="Y:Sample DocumentsCorporate Downsizing.pptm", _
    Position:=1, DisplayName:="Downsizing Presentation"

To test this, insert this code into the example code from the previous section (“Working with the Contents of a Message”), like this:

Dim myMessage As Outlook.MailItem
Set myMessage = Application.CreateItem(olMailItem)
 
myMessage.Attachments.Add _
    Source:="Y:Sample DocumentsCorporate Downsizing.pptm", _
    Position:=1, DisplayName:="Downsizing Presentation"
 
With myMessage
    .To = "[email protected]"
    .Subject = "Preparation for Review"
    .Body = "Please drop by tomorrow and spend a few minutes" _
        & " discussing the materials we need for Darla's review."
    .BodyFormat = olFormatHTML
    .Importance = olImportanceHigh
    .Send
End With

Sending a Message

To send a message, use the Send method. This method takes no arguments. The following example sends the message referenced by the object variable myMessage:

myMessage.Send

To check whether a message has been sent, check its Sent property. This Boolean property returns True if the message has been sent and False if it has not.

Creating a New Calendar Item

To create a new calendar item, use the CreateItem method of the Application object and specify olAppointmentItem for the ItemType argument. The following example creates an AppointmentItem object variable named myAppointment and assigns to it a new appointment item:

Dim myAppointment As AppointmentItem
Set myAppointment = Application.CreateItem(ItemType:=olAppointmentItem)

Working with the Contents of a Calendar Item

To work with the contents of a calendar item, set or get the appropriate properties. These are the most widely useful properties:

• Subject is the subject of the appointment.
• Body is the body text of the appointment.
• Start is the start time of the appointment.
• End is the end time of the appointment.
• BusyStatus is your status during the appointment: olBusy, olFree, olOutOfOffice, or olTentative.
• Categories is the category or categories assigned to the item.
• ReminderSet determines whether the appointment has a reminder (True) or not (False).
• ReminderMinutesBeforeStart is the number of minutes before the event that the reminder should occur.

The following example creates a new AppointmentItem object and assigns it to the object variable myAppointment. It then sets the subject, body, start date (2:30 PM on the day seven days after the present date), and end date (one hour after the start); marks the time as busy; assigns the Personal category; sets a reminder 30 minutes before the appointment; and saves the appointment. You'll see the results in Figure 26.5:

Dim myAppointment As Outlook.AppointmentItem
Set myAppointment = Application.CreateItem(ItemType:=olAppointmentItem)
With myAppointment
    .Subject = "Dentist"
    .Body = "Dr. Schmitt " & vbCr & "4436 Acacia Blvd."
    .Start = Str(Date + 7) & " 2.30 PM"
    .End = Str(Date + 7) & " 3.30 PM"
    .BusyStatus = olBusy
    .Categories = "Personal"
    .ReminderMinutesBeforeStart = 30
    .ReminderSet = True
    .Save
End With

The AppointmentItem object has a grand total of 71 properties. If you want to explore more of them, take a look at this MSDN web page:

http://msdn.microsoft.com/en-us/library/office/jj900814.aspx

Creating a Task

To create a new task item, use the CreateItem method of the Application object and specify olTaskItem for the ItemType argument. The following example creates a TaskItem object variable named myTask and assigns to it a new task item:

Dim myTask As TaskItem
Set myTask = Application.CreateItem(ItemType:=olTaskItem)

Working with the Contents of a Task Item

To work with the contents of a task item, set or get the appropriate properties. These are the most widely useful properties:

• Subject is the subject of the task.
• Body is the body text of the task.
• Start is the start time of the task.
• DueDate is the due date of the task.
• Importance is the importance of the task. Set it to olImportanceHigh, olImportanceNormal, or olImportanceLow.
• Status is the status of the task: olTaskNotStarted, olTaskWaiting, olTaskDeferred, olTaskInProgress, or olTaskComplete.
• PercentComplete is the percentage of the task completed.
• Companies specifies the companies associated with the task.
• BillingInformation is the company or department to bill for the task.

The following example creates a TaskItem object variable named myTask and assigns to it a new task item. It then sets the subject and body of the task, specifies a due date in the future, sets the status to olTaskInProgress and the percentage complete to 10, specifies the company involved and who to bill, sets the importance to High, and then saves the task:

Dim myTask As TaskItem
Set myTask = Application.CreateItem(ItemType:=olTaskItem)
With myTask
    .Subject = "Create a business plan"
    .Body = "The business plan must cover the next four years." & _
        vbCr & vbCr & "It must provide a detailed budget, " & _
        "staffing projections, and a cost/benefit analysis."
    .DueDate = Str(Date + 28)
    .Status = olTaskInProgress
    .PercentComplete = 10
    .Companies = "Acme Polyglot Industrialists"
    .BillingInformation = "Sales & Marketing"
    .Importance = olImportanceHigh
    .Save
End With

The TaskItem object has 69 properties. If you want to explore more of them, take a look at this MSDN web page:

https://msdn.microsoft.com/en-us/library/office/jj871952.aspx

Assigning a Task to a Colleague

To assign a task to a colleague, use the Assign method of the TaskItem object, and then use the Add method of the Recipients collection to add one or more recipients. Finally, you can use the Send method to send the task to your colleague.

The following example creates a task, uses the Assign method to indicate that it will be assigned, specifies a recipient, and sends the task:

Dim myTaskAssignment As TaskItem
Set myTaskAssignment = Application.CreateItem(ItemType:=olTaskItem)
With myTaskAssignment
    .Assign
    .Recipients.Add Name:="Peter Nagelly"
    .Subject = "Buy Bagels for Dress-Down/Eat-Up Day"
    .Body = "It's your turn to get the bagels on Friday."
    .Body = .Body & vbCr & vbCr & "Remember: No donuts AT ALL."
    .DueDate = Str(Date + 3)
    .Send
End With