Selecting an API or technology for developing solutions for Outlook

This article describes the APIs and technologies that you can use to extend Outlook 2013 and Outlook 2016, and helps you decide the appropriate API or technology for your scenario.

Microsoft supports various APIs and technologies that extend Outlook:

  • Starting in Office 2013, the apps for Office platform opens up opportunities to extend Outlook functionality across Outlook clients on the desktop, tablet and smart phone. The platform includes a JavaScript API for Office and a schema for app manifests.

  • The object model, the corresponding Outlook Primary Interop Assembly (PIA), and the Messaging API (MAPI) have been the most commonly used APIs in Outlook solutions.

  • The auxiliary APIs complement MAPI in a few scenarios.

  • Outlook Social Connector (OSC) provider extensibility and the Weather Bar extensibility serve specific scenarios of their niche markets.

This article explains the selection criteria for the Office Add-ins platform, the object model, PIA, and MAPI. Note that Office Add-ins use the JavaScript API for Office and do not call into the object model, and vice versa. Solutions that use the other APIs can use one or more APIs. For example, a COM add-in written in C++ can use the object model, MAPI, and auxiliary APIs in the same solution.

To get the most benefit from this article, you should be familiar with Outlook at the user level and have general software development knowledge. However, you do not need to have a comprehensive understanding of the features that these APIs or technologies support. The article helps answer the following questions:

  • If you have only an idea about the goals of your solution, the target market, and available resources, what other criteria should you consider to select an API?

  • Why would you consider Office Add-ins, and when would you choose to create apps as opposed to add-ins?

  • If your solution has to run on earlier versions of Outlook, including Outlook 2003, how does that affect your API choice?

  • If your solution has to iterate through Outlook folders that contain thousands of items, and you need to be able to modify those items, which API would work best?

  • If your solution relies heavily on Outlook business logic and interacts with other Office applications, is the Outlook object model the best choice?

  • What do the object model and MAPI allow you to extend in Outlook?

  • If you can use either the object model or MAPI to achieve your task, how should you decide which API to use?

Objective evaluation criteria

This section describes criteria that you can use to compare the Office Add-ins platform, object model, PIA, and MAPI to determine which better meets your needs. Different criteria can be more or less important, depending on your projects and available resources.

The tables in this section define evaluation criteria in the following categories:

  • Functional criteria—Describes the things you can and cannot do with the technology.

  • Development criteria—Describes the development tools or information you need to use the technology

  • Security criteria—Describes the security and permissions issues related to the technology.

  • Deployment criteria—Describes the recommended deployment and distribution methods for the technology.

Objective evaluation criteria for the apps for Office platform

Starting in Office 2013, developers can use the Office Add-ins platform to extend web services and content into the context of Office rich and web clients. An Office Add-in is a web page that is developed using common web technologies, hosted inside an Office client application (such as Outlook), and can run on-premises or in the cloud. Of the few types of Office Add-ins, the type that Outlook supports is called mail apps. While the object model, PIA, and MAPI are often used to automate Outlook at an application level, you can use the JavaScript API for Office to interact at an item level with the content and properties of an email message, meeting request, or appointment. You can publish mail apps to the Office Store or an internal Exchange catalog.

End users and administrators can install mail apps on an Exchange mailbox, and use mail apps in the Outlook rich client as well as Outlook Web App. As a developer, you can choose to make your mail app available on only the desktop, or also on the tablet or smart phone. Figure 1 shows an example of a YouTube mail app, which is described in detail in Sample: Create a mail add-in to view YouTube videos in Outlook. The YouTube mail app allows end users select a URL for a YouTube video and watch the video within Outlook or Outlook Web App, on the desktop or tablet.

Figure 1. YouTube mail app is active for the selected message, which contains a URL to a video on YouTube.com

YouTube mail app in Outlook

After a user installs a mail app, the app is available for use in the app bar when the current context matches the activation conditions that the app specifies. A mail apps allows you to specify rules about the currently selected item that activate a mail app only if certain conditions are met. For example, the YouTube mail app that lets you play a YouTube video within Outlook is relevant only when the selected Outlook item contains a URL to a video on YouTube.com. In this case, you would specify that the app should be active only when the selected message contains such a URL.

The following tables show the evaluation criteria for the Office Add-ins platform.

Functional criteria

Criteria Mail apps support in apps for Office platform
Application domain The scope of activity of a mail app is virtually any supported message or appointment item in the user's Exchange mailbox that the user has selected and that satisfies the activation conditions. The permissions of a mail app determine its access to the properties and specific entities (such as an email address or telephone number) that exist for that item. For example, a mail app requesting the read/write mailbox permission can read and write all the properties of any item in the user's mailbox; create, read, and write to any folder or item; and send an item from that mailbox.
Major objects The JavaScript API for Office provides a few objects at the top level that are shared by all the types of Office Add-ins: Office, Context, and AysncResult. The next level in the API that is applicable and specific to mail apps includes the Mailbox, Item, and UserProfile objects, which support accessing information about the user and the item currently selected in the user's mailbox. At the data level, the CustomProperties and RoamingSettings objects support persisting properties set up by the mail app for the selected item and for the user's mailbox, respectively. Item-level objects include the Appointment and Message objects that inherit from Item, and the MeetingRequest object that inherits from Message. These represent the types of Outlook items that support mail apps: calendar items of appointments and meetings, and message items such as email messages, meeting requests, responses, and cancellations. Beyond this level in the API are item-level properties (such as Appointment.subject) as well as objects and properties that support certain known Entities objects (for example Contact, MeetingSuggestion, PhoneNumber, and TaskSuggestion). See Overview of Outlook add-ins architecture and features for a summary of the features supported for mail apps.
Data-access model The JavaScript API for Office represents the following features as a hierarchical set of objects: the app's runtime environment, user's mailbox and profile, and data about an item.
Threading models Each mail app executes in its own process separate from the Outlook process.
Application architectures In Outlook, a mail app is a set of HTML and JavaScript web pages hosted as a separate process inside a web browser control which, in turn, is hosted inside an app runtime process that provides security and performance isolation.
Remote usage Mail apps use the JavaScript API for Office to access data about the current user, mailbox, and selected item stored on the corresponding Exchange Server. Provided that they have the appropriate permissions and use the appropriate technique for cross-domain access, mail apps can also call Exchange Web Services and other third-party web services to extend their functionality.
Transactions The JavaScript API for Office does not support transactions.
Availability The JavaScript API for Office is available for mailboxes on Exchange Server 2013, starting in Outlook 2013.

Development criteria

Criteria Mail apps support in apps for Office platform
Languages and tools You can implement mail apps using any common web technology, including HTML5, JavaScript, CSS3, XML, and REST APIs. You can use your preferred web development tool. Alternatively, using Napa, Visual Studio 2012, or a later version of these tools provides conveniences that save you time in development.
Managed implementation Where appropriate in your scenario, you can use managed .aspx pages to implement server-side code for your mail apps.
Scriptable The JavaScript API for Office is directly used in scripts.
Test and debug tools You can use any web development tools you prefer. Napa and Visual Studio provide an integrated development environment that facilitates app testing and debugging. Troubleshoot Outlook add-in activation and Sample: Debug properties of Outlook items provide further help in troubleshooting and debugging mail apps.
Expert availability Programmers who have the required level of web development expertise for Office Add-ins are relatively easy to find. The platform is intended for both professional and non-professional developers.
Available information Information about developing and posting Office Add-ins is available at Build apps for Office and SharePoint. Specific documentation for mail apps is available at Outlook add-ins.
Developer and deployment licensing Refer to License your Office and SharePoint Add-ins for information about the app license framework for Office Add-ins.

Security criteria

Criteria Mail apps support in apps for Office platform
Design-time permissions No special permissions are required to develop mail apps.
Setup permissions By default, end users and administrators can install low-trust mail apps that require restricted or read item permission, and administrators can install high-trust mail apps that require read/write mailbox permission.
Run-time permissions Mail apps request a specific level of permission that is based on a three-tier permissions model: restricted, read item, and read/write mailbox.
Built-in security features The Office Add-ins runtime provides the following benefits to prevent an app from damaging the end user's environment: Isolates the process that the app runs in. Doesn't involve .dll or .exe replacement or ActiveX components. Makes apps easy to install or uninstall by the end user. The administrator and end users have control over the mail apps that are made available and whether to grant the requested permission before installing a mail app. In the case of rich clients, governs the use of memory and CPU to prevent denial of service malicious attacks.
Security monitoring features For mail apps, the following resources are monitored: CPU core usage. Memory usage. Number of crashes. Length of time blocking an application. Regular expression response time. Number of times re-evaluating regular expressions. Administrators can override default settings that govern the resource usage.

Deployment criteria

Criteria Mail apps support in apps for Office platform
Server platform requirements The user's mailbox for which a mail app is installed must be on Exchange Server 2013 or a later version.
Client platform requirements For a mail app to run on the Outlook rich client, Outlook 2013 and Internet Explorer 9, or a later version of these applications, must be installed on the local computer.
Deployment methods You can publish mail apps to the Office Store or to an Exchange catalog that makes the app available to users on that Exchange Server. Administrators or users can then choose to install a mail app from the Office Store or Exchange catalog, by using either the Exchange Admin Center (EAC) or by running remote Windows PowerShell cmdlets. You can access the EAC from the Outlook Backstage view or Outlook Web App, or by directly signing into the EAC for your mailbox. For more information, see Deploy and install Outlook add-ins for testing.
Deployment notes Once you install a mail app on Outlook or Outlook Web App, the mail app is available for that mailbox on both Outlook clients.

Objective evaluation criteria for the object model and PIA

Solutions that run on the client computer can use the Outlook object model or PIA to programmatically access Outlook items, such as contacts, messages, calendar items, meeting requests, and tasks. Unlike MAPI, the Outlook object model and PIA can provide event notifications for Outlook user-interface changes, such as changing the current folder or displaying an Outlook inspector.

Note

For a solution to access data that is stored in a Microsoft Exchange mailbox or a personal folders (.pst) file, Outlook must be installed and configured on the client computer on which the application is running. > The Outlook object model and PIA support the same functionality to extend Outlook. The PIA defines managed interfaces that map to the COM-based object model and that a managed solution can interact with. In the remaining discussions in this section, most of the functional, security, and deployment criteria apply to the object model and the PIA in the same way. For more information about how the PIA facilitates interoperability between COM and the .NET Framework, see Introduction to interoperability between COM and .NET and Architecture of the Outlook PIA.

The following tables show evaluation criteria for the Outlook object model and PIA.

Functional criteria

Criteria Outlook object model or PIA
Application domain Add-ins or standalone applications that use the Outlook object model or PIA typically handle user-specific messages, customize the Outlook user interface, or create custom item types for specialized solutions such as customer relationship management (CRM) solutions that integrate with Outlook. The Outlook object model or PIA is sometimes used for message processing in an informal workflow process, especially where application development on the Microsoft Exchange Server is not permitted. Unlike browser-based clients, cached-mode operation allows Outlook solutions to work when the user is offline or disconnected from the corporate network.
Major objects The top-level object in the Outlook object model and PIA is the Outlook Application object. Explorers, Conversation, Inspectors, Views, NavigationPane, SolutionsModule, FormRegion, and related objects represent elements of the Outlook user interface. The NameSpace, Stores, Folders, Accounts, AccountSelector, AddressEntries, ExchangeUser, and related objects support extending Outlook sessions, profiles, user accounts, message stores, and folders. At the data level, a number of item-level objects, such as MailItem, AppointmentItem, ContactItem, and TaskItem, represent the built-in Outlook item types. The PropertyAccessor, Table, Search, ItemProperties, UserDefinedProperties, Attachments, Categories, Recipients, RecurrencePattern, Reminders, Rules, and related objects support customizing and manipulating item-level objects.
Data-access model The Outlook object model and PIA represent all data as a hierarchical set of objects and collections.
Threading models All calls to the Outlook object model and PIA execute on Outlook's main foreground thread. The only threading model that the Outlook object model supports is single-threaded apartment (STA). Calling the Outlook object model or PIA from a background thread is not supported and can lead to errors and unexpected results in your solution.
Application architectures Typically, COM add-ins and other Office applications use the Outlook object model to extend Outlook. Managed solutions can use the Outlook PIA and the COM interoperability layer of Visual Studio and the .NET Framework to access the Outlook object model. Visual Studio provides templates and additional class libraries and manifests to facilitate Office document and application customizations. For more information about using Visual Studio to develop managed add-ins for Outlook, see Architecture of Application-Level Add-Ins and Outlook Solutions. The Outlook object model also supports Visual Basic for Applications (VBA) macros and Windows Scripting Host (WSH), but does not support Windows Service applications.
Remote usage The Outlook object model and PIA can be used only on a computer on which Outlook is installed. The Outlook object model can be used to access information stored in Exchange that is available in the Outlook application.
Transactions The Outlook object model and PIA do not support transactions.
Availability The Outlook object model is currently available in all versions of Outlook. The PIA is available in versions of Outlook since Outlook 2003. There have been extensions and improvements with each new version of Outlook.

Development criteria

Criteria Outlook object model or PIA
Languages and tools You can implement Outlook object model applications by using any COM or automation-compatible language, such as Visual Basic or C#, as well as non-COM languages, such as native C or C++. Microsoft Office development tools in Microsoft Visual Studio 2010 are the preferred tools for development of managed add-ins for Outlook 2010 and Outlook 2007. Microsoft Visual Studio 2005 Tools for the Microsoft Office System are the preferred tools for Outlook 2003. You can also use Office development tools in Visual Studio 2010 to create solutions for 32-bit and 64-bit versions of Outlook. When you build a solution in Office development tools in Visual Studio 2010 or Microsoft Visual Studio Tools for the Microsoft Office System, specifying the Any CPU option for the target platform results in managed solutions that work for both 32-bit and 64-bit versions of Outlook 2010.
Managed implementation The Outlook PIA enables the Outlook object model to be used in a managed-code environment, which is supported by a rich set of class libraries and support technologies that address many limitations of VBA and COM add-ins. The PIA is a COM wrapper that acts as a bridge between the managed and COM environments. For more information, see Why Use the Outlook PIA.
Scriptable The Outlook object model can be used in scripts.
Test and debug tools No special debugging tools are needed to use the Outlook object model or PIA. On the other hand, you can use Visual Studio to provide an integrated development environment that facilitates application testing and debugging.
Expert availability Developers who can successfully develop applications by using the Outlook object model or PIA are relatively easy to find. The Outlook object model and PIA are intended for add-ins created by using widely available development tools, such as Visual Studio. These tools provide design-time environments that simplify the development process.
Available information Information about programming by using the Outlook object model is available in both Microsoft and third-party resources. For more information about the Outlook object model, see the Outlook 2010 Developer Reference. For more information about the Outlook PIA, see the Outlook 2010 Primary Interop Assembly Reference. For examples of managed Outlook solutions developed by using Office development tools in Visual Studio, see Outlook Solutions with Visual Studio.
Developer and deployment licensing Refer to your Exchange and Microsoft Developer Network (MSDN) subscription licensing agreements to determine whether additional licenses are required for Outlook and Outlook object model use in your applications.

Security criteria

Criteria Outlook object model or PIA
Design-time permissions No special permissions are required to develop applications by using the Outlook object model or PIA.
Setup permissions No special permissions are required to install applications that use the Outlook object model or PIA. However, local administrator rights are required to install Office and Outlook.
Run-time permissions No special permissions are required to run applications that use the Outlook object model or PIA.
Built-in security features The Outlook object model and PIA communicate with Exchange by using MAPI and with Active Directory by using Active Directory Service Interfaces (ADSI). The current security context of the user who is running the application is used to determine what resources that code can access. By default, add-ins are trusted for full access to all objects, properties, and methods in the Outlook object model or PIA. IT administrators can exercise control over which add-ins and objects can access the Outlook object model or PIA. The Outlook object model and PIA prevent code that is run outside the Outlook process from accessing secure objects and methods.
Security monitoring features Outlook monitors the following metrics of an add-in to determine whether it should disable the add-in: Startup Shutdown Folder switch Item open Invoke frequency Administrators can use group policy to override user settings and control the add-ins that run on the user's computers. For more information, see Performance criteria for keeping add-ins enabled.

Deployment criteria

Criteria Outlook object model or PIA
Server platform requirements The Outlook object model and PIA are client-side technologies.
Client platform requirements Applications that use the Outlook object model or PIA to access Exchange data require that Outlook be installed on the local computer.
Deployment methods Applications that use the Outlook object model or PIA are distributed by using standard application installation software.
Deployment notes Because Outlook should not be installed on the Exchange Server, applications that use the Outlook object model or PIA cannot be run on the Exchange Server.

Objective evaluation criteria for MAPI

You can use MAPI to access items and folders in public and private stores, as well as to access the properties stored with each item. All versions of Outlook use MAPI. You can create clients that use MAPI, and can create MAPI servers and MAPI forms handlers, as well. The information in this section applies only to MAPI client applications.

Note

MAPI is a mature mechanism used to access information in Exchange or in a personal folders (.pst) file, and MAPI provides some capabilities that are not available in any other API. However, MAPI does not work well outside an intranet, maintains an open connection for the duration of the MAPI session, and can be difficult to learn. MAPI does not enforce Outlook business logic, so you must take special care to ensure that Outlook business logic is maintained.

The following tables show evaluation criteria for MAPI.

Functional criteria

Criteria MAPI
Application domain Client applications that use MAPI access a user mailbox or public folder information stored in Exchange, and user directory information stored in Active Directory. Client applications that use MAPI are typically email clients, such as Outlook, and applications that require complex email processing.
Major objects MAPI objects are all obtained through the IMAPISession : IUnknown interface. The session object provides the client access to objects for working with MAPI profiles, status, message service provider administration, message store tables, and address books. The message store table contains objects for the message store, folders, messages, attachments, and recipients. The address book tables contain objects for messaging users and distribution lists.
Data-access model MAPI represents messages and users as a hierarchical set of objects.
Threading models There are no specific threading prohibitions. However, applications that use free-threading should avoid sharing MAPI objects among threads due to the high costs of marshaling the object. MAPI and MAPI service providers use free-threading.
Application architectures MAPI client applications are typically Windows Forms-based client applications. However, you can use MAPI to write N-tier applications.
Remote usage MAPI uses remote procedure calls (RPCs) to communicate with the Exchange Server. Typically RPCs are intentionally blocked from passing through Internet firewalls.
Transactions MAPI does not support transactions.
Availability A MAPI stub currently ships with all versions of Windows. Office installs its own MAPI subsystem when it installs Outlook. No changes to MAPI are anticipated at this time.

Development criteria

Criteria MAPI
Languages and tools You can directly access MAPI by using C or C++. Other languages that can access the C/C++ calling convention may be able to access MAPI. The use of managed languages, such as Visual Basic or C#, is not supported. You must compile separate MAPI solutions for 32-bit and 64-bit versions of Outlook.
Managed implementation MAPI is an unmanaged component. Use of MAPI is not supported under the COM interoperability layer of Visual Studio and the .NET Framework.
Scriptable MAPI cannot be directly used in scripts.
Test and debug Tools No special debugging tools are needed to debug applications that use MAPI. On the other hand, you can use MFCMAPI. MFCMAPI uses MAPI to provide access to MAPI stores through a graphical user interface, and facilitates investigation of issues when you extend Outlook by using MAPI.
Expert availability Expert MAPI programmers can be difficult to find, and learning the technology can take a significant amount of time. In addition to the Microsoft communities, there are only a small number of high-quality third-party websites that provide helpful MAPI development information.
Available information Both Microsoft and third-party books that describe MAPI programming are available.
Developer and deployment licensing No special licensing is required for developing applications that use MAPI.

Security criteria

Criteria MAPI
Design-time permissions The developer must have permissions to access the data in the Exchange store. Exchange stores user and distribution list information in Active Directory, so developers who create MAPI client applications that access that information must have the ability to retrieve and set that information.
Setup permissions Setting up MAPI-based applications typically requires the user to be a local administrator, or to have rights to install software.
Run-time permissions Running a MAPI-based application usually requires only that the user has sufficient permissions to access the data on an Exchange store or personal folders (.pst) file.
Built-in security features MAPI profiles can be password protected on most platforms.

Deployment criteria

Criteria MAPI
Server platform requirements The Exchange Server on which user data is stored for users of the MAPI client application must be properly configured to allow access by MAPI clients.
Client platform requirements The client application installer should verify that the proper version of MAPI is available on the computer, and that it is properly configured by using the Mapisvc.inf file.
Deployment methods Applications that use MAPI can be deployed to client computers by using standard software distribution technologies.
Deployment notes The installer should verify that the correct version of MAPI is available.

Decision factors for the apps for Office platform

Because Office Add-ins use web technologies, they are best for connecting to services in the cloud or on-premises, and bringing the services into the context of the rich client and web client. By requesting appropriate permissions, mail apps also allow reading, writing, or sending items in a mailbox.

The following are common reasons why mail apps are a better choice for developers than add-ins:

  • You can use existing knowledge of and the benefits of web technologies such as HTML, JavaScript, and CSS. For power users and new developers, XML, HTML, and JavaScript require less significant ramp-up time than COM-based APIs, including the object model and MAPI.

  • You can use a simple web deployment model to update your mail app (including the web services that the app uses) on your web server without any complex installation on the Outlook client. In fact, any updates to the mail app, with the exception of the app manifest, do not require any updating on the Office client. You can update the code or user interface of the mail app conveniently just on the web server. This presents a significant advantage over the administrative overhead involved in updating add-ins.

  • You can use a common web development platform for mail apps that can roam across the Outlook rich client and Outlook Web App on the desktop, tablet, and smartphone. On the other hand, add-ins use the object model for the Outlook rich client and, hence, can run on only that rich client on a desktop form factor.

  • You can enjoy rapid turnaround of building and releasing apps via the Office Store.

  • Because of the three-tier permissions model, users and administrators perceive better security and privacy in mail apps than add-ins, which have full access to the content of each account in the user's profile. This, in turn, encourages user consumption of apps.

  • Depending on your scenarios, there are features unique to mail apps that you can take advantage of and that are not supported by add-ins:

    • You can specify a mail app to activate only for certain contexts (for example, Outlook displays the app in the app bar only if the message class of the user-selected appointment is IPM.Appointment.Contoso, or if the body of an email contains a package tracking number or a customer identifier).

    • You can activate a mail app if the selected message contains some known entities, such as an address, contact, email address, meeting suggestion, or task suggestion.

    • You can take advantage of authentication by identity tokens, and of Exchange Web Services.

However, the following features are unique to add-ins and may make them a more appropriate choice than mail apps in some circumstances:

  • You can use add-ins to extend or automate Outlook at an application-level, because the object model and PIA have extensive integration with Outlook features (such as all Outlook item types, user interface, sessions, and rules). At the item-level, add-ins can interact with an item in read or compose mode. With mail apps, you cannot automate Outlook at the application level, and you can extend Outlook's functionality in the context of only the read-mode of the supported items (messages and appointments) in the user's mailbox.

  • You can specify custom business logic for a new item type.

  • You can modify and add custom commands in the ribbon and Backstage view.

  • You can display a custom form page or form region.

  • You can detect events such as sending an item or modifying properties of an item.

  • You can use add-ins on Outlook 2013 and Exchange Server 2013, as well as earlier versions of Outlook and Exchange. On the other hand, mail apps work with Outlook and Exchange starting in Outlook 2013 and Exchange Server 2013, but not earlier versions.

For more information about scenarios that the object model and PIA support, see the next section, Decision factors for the object model or PIA. For a comparison of the Office Add-ins platform with other extensibility technologies for Office, see The background on apps for Office and SharePoint.

Decision factors for the object model or PIA

Major baseline scenarios supported by the Outlook object model or PIA

In general, use the object model or the PIA if your solution customizes the Outlook user interface or relies on Outlook's business logic. Following are the major baseline scenarios for which Outlook solutions use the object model or the PIA.

Scenarios supported by the object model or PIA since Outlook 2007

In addition to the baseline scenarios, if your Outlook solution supports any of the scenarios shown in the following list, and your solution is intended to run on Outlook 2007 or a later version but not earlier versions, you can use the object model or the PIA as well. This section specifies the main objects or members that you can use in the Outlook object model to extend each scenario (with the exception of the IDTExtensibility2 interface in the Visual Studio automation object model, and the IRibbonExtensibility interface in the Office object model, which you can integrate with the Outlook object model).

Scenarios supported by the object model or PIA since Outlook 2010

If your Outlook solution is intended to run on Outlook 2010 and not earlier versions, you can choose to use the object model or the PIA to support the scenarios shown in this next section. This section specifies the main objects or members that you can use in the Outlook object model to extend each scenario (with the exception of the IRibbonControl, IRibbonExtensibility, and IRibbonUI interfaces that are in the Office object model, which you can integrate with the Outlook object model).

Scenarios supported by the object model or PIA since Outlook 2013

If your solution is intended to run on Outlook 2013 and not any earlier version, you can use the object model or the PIA to support the scenarios shown in the following resources.

Decision factors for MAPI

In general, you use MAPI to access data on a MAPI-based server such as the Microsoft Exchange server, and to do tasks such as the following:

  • Create a custom service provider such as an address book provider, transport provider, or store provider.

  • Create a sink process.

  • Create or manipulate a profile.

  • Run an application as a Windows NT service.

  • Run tasks on a background thread. For example, enumerating numerous items in a folder and modifying the items' properties in a background thread can optimize performance.

For more information and code samples, see the Outlook MAPI Reference and MFCMAPI.

In addition, if your solution runs on a version of Outlook earlier than Outlook 2007, and scenarios such as the following apply to your solution, you should use MAPI to extend those scenarios.

  • Set and get built-in item-level properties that are not exposed in the object model.
  • Manage accounts, attachments, Exchange distribution lists, Exchange users, or stores.
  • Store private data for solutions.
  • Manage a message store for an account.

Since Outlook 2007, the object model has supported a range of features that, prior to Outlook 2007, developers had to resort to MAPI or other APIs such as Microsoft Collaboration Data Objects (CDO) 1.2.1 and Microsoft Exchange Client Extensions. So if any of the scenarios in the previous list applies to your solution, but your solution runs on Outlook 2007 or Outlook 2010, you can and should use the Outlook object model or PIA to support these scenarios. For more information about Outlook 2007 enhancements that unify Outlook development technologies, see What's New for Developers in Outlook 2007 (Part 1 of 2).

Decision factors for the Auxiliary APIs

The Outlook auxiliary APIs can integrate with Outlook business logic or MAPI in some scenarios where the object model or MAPI does not provide a solution. Use the Outlook auxiliary APIs in the following scenarios:

  • Account management: Manage account information, manipulate accounts, provide notification on account changes, and protect accounts from spam.
  • Data degradation: Wrap an object in a preferred character format rather than exposing the object in its native format.
  • Rebasing calendars and time zone support: Rebase Outlook calendars to support daylight saving time.
  • Free/busy status: Provide free/busy information on calendars.
  • Contact pictures: Determine the display of a contact's picture in Outlook.
  • Item currency: Determine whether an Outlook item has unsaved changes.
  • Categorizing an item: Categorize an Outlook item after sending the item.

For more information about the auxiliary APIs, see the Additional resources—Auxiliary APIs section.

Automating Outlook by in-process vs. out-of-process Solutions

Note

The discussion of automating Outlook in this section and the next is outside the scope of Office Add-ins, which are intended to extend the functionality of the Office client or web application but not to automate it.

Outlook supports automation by using add-ins that run in the same foreground process as the Outlook process, and by standalone solutions that run in their own separate process outside of the Outlook process. Generally, to automate Outlook, use an add-in to interact with Outlook through the object model, PIA, or MAPI, and in less common scenarios, through an auxiliary API (such as HrProcessConvActionForSentItem). Use an out-of-process solution only when it's necessary (for example, when you're writing a MAPI client application that uses the Tzmovelib.dll file to rebase Outlook calendars for customers, or enumerating numerous items in a folder and modifying the items' properties in a background thread to optimize performance).

Add-ins are the preferred solution to automate Outlook, because Outlook trusts only the Application object passed to the add-in during the OnConnection(Object, ext_ConnectMode, Object, Array) event of the add-in. You can avoid the display of security warnings of the Object Model Guard by deriving all objects, properties, and methods from this Application object. If the add-in creates a new instance of the Application object, Outlook does not trust that object, even if the add-in is on the list of trusted add-ins. Any objects, properties, and methods derived from such an Application object will not be trusted and the blocked properties and methods will invoke security warnings. For more information about the Outlook Object Model Guard, see Security Behavior of the Outlook Object Model.

Automating Outlook by managed vs. unmanaged solutions

Outlook supports automation by add-ins and standalone applications, written in managed or unmanaged languages. The more commonly used managed languages are C# and Visual Basic. C++ and Delphi tools are more common in unmanaged development. Available expertise is one consideration when choosing between managed and unmanaged development.

If your solution uses only the object model, you can consider developing a managed solution by using the PIA, or Office development tools in Visual Studio. The Office development tools in Visual Studio provide project templates and visual designers that simplify creating custom user interfaces and developing Office solutions.

On the other hand, because MAPI was developed years before the .NET Framework, and Microsoft does not provide managed wrappers for MAPI, Microsoft does not support using MAPI in managed code. If you are using MAPI, you must develop an unmanaged solution. For more information, see The support guidelines for client-side messaging development.

Niche APIs and technologies

The Outlook Social Connector (OSC) and Weather Bar support extending very specific scenarios in Outlook.

Outlook Social Connector (OSC) provider extensibility

The Outlook Social Connector (OSC) provider extensibility supports developing a provider for a social network to allow users to view, in Outlook and other Office client applications, friends and activities updates on that social network. Figure 6 shows the OSC displaying in the People Pane the activities of a person in social network sites.

Figure 6. The OSC displaying social network data in the People Pane

Outlook Social Connector pane

The OSC in Outlook allows users to view, in the People Pane, an aggregation of emails, attachments, and meeting requests from a person in Outlook. In an organizational environment, users who collaborate on a SharePoint site can see document updates and other site activities of this person on the SharePoint site. Outlook Social Connector provider extensibility supports developing a provider for the OSC to synchronize and surface social network updates in Outlook. Common OSC providers (such as Facebook and LinkedIn) are installed by default with Outlook. Depending on the social network sites that an Outlook user has signed into, the user can see, in the People Pane, updates such as photos, status, and activities on the corresponding social networks.

Weather Bar extensibility

Starting in Outlook 2013, the Weather Bar allows developers to plug in a third-party weather web service for the Weather Bar, to provide weather conditions data for a user-chosen location. The Weather Bar in Outlook displays weather conditions and forecast for a geographic location. A user can choose one or multiple locations, and conveniently see weather data in the Weather Bar in the calendar module. Figure 7 shows the Weather Bar displaying a three-day forecast for New York, NY.

Figure 7. Weather Bar in Outlook

Weather Bar showing forecast for New York.

By default, Outlook uses weather data provided by MSN Weather. The Weather Bar supports third-party weather data web services which follow a defined protocol to communicate with Outlook. As long as a third-party weather data service supports this protocol, users can choose that weather data service to provide weather data in the Weather Bar.

See the Additional resources—primary references, resources, and code samples section for more information about using OSC provider extensibility and the Weather Bar extensibility.

Conclusion

To determine the best API or technology for your solution, you must first define the goals of your solution:

  • The versions of Outlook you intend your solution to support.

  • The high-priority scenarios of your solution. Does your solution mainly interact with the content and properties of a message or appointment item? Or does your solution automate Outlook at an application level? If so, do these scenarios involve enumerating, filtering, or modifying folders that contain many Outlook items?

First, verify whether the mail app support in the Office Add-ins platform meets your needs. See the Functional Criteria section of Objective evaluation criteria for the apps for Office platform to determine whether the major objects and features support your scenarios. See the section Decision factors for the apps for Office platform to verify whether mail apps are a better choice than add-ins for your scenarios. In general, develop your solution as an app, if possible, to take advantage of the platform's support across Outlook clients over different form factors.

If your scenarios require you to extend beyond message and appointment items, or require you to automate Outlook at an application level, try to match your scenarios with those outlined in the section Decision factors for the object model or PIA. If the object model (or PIA) of your target Outlook versions supports your scenarios, and your solution does not manipulate folders with many items, you should implement your solution as an add-in, in either a managed or unmanaged language.

If the object model (or PIA) of a target Outlook version does not support some of your scenarios, verify whether the scenarios in the Decision factors for MAPI or Decision factors for the Auxiliary APIs section meet your needs. If MAPI meets your needs, you should implement your solution in unmanaged code. If an auxiliary API solves one of your scenarios, you can use managed or unmanaged code.

If your solution uses MAPI, you must implement it in unmanaged code, such as C++. Otherwise, the decision to use managed or unmanaged code to create the solution generally depends on your available resources and their expertise. As for deciding whether to implement the solution as an add-in or standalone application, choose an add-in to avoid the user constantly invoking the Outlook Object Model Guard, unless your scenario requires manipulation of folders that contain numerous items. In the latter scenario, implementing the solution to run as a background thread can optimize Outlook performance.

If your scenarios include showing social network information or updates in Outlook, you should use the OSC provider extensibility to create a COM-visible DLL. You can do this in either a managed or unmanaged language.

If you are interested in plugging in a third-party weather data service to the Weather Bar, you can follow the protocol defined by Weather Bar extensibility and provide the appropriate web services. You can create these web services in a managed language.

Once you have decided on the APIs or technologies to use in your solution, you can refer to additional documentation and code samples in the Additional resources—primary references, resources, and code samples section for more information.

Office Add-ins platform overview provides a good introduction of Office Add-ins, including the architecture and development life cycle.

See Outlook add-ins for a detailed roadmap of resources about developing mail apps.

See also: Object model and PIA

The following resources provide more information about using the object model and PIA.

Accounts—multiple accounts in profile

Address book and Exchange users

Attachments

Attachments: selection in inspector

Automating Outlook

Categories

Contacts: check address and full name

Conversations

Events

Explorer: inline response

Items: basic properties, fields, and forms

Items: customizing properties

Items: enumerating, filtering, and sorting

Items: flag as tasks

See the following task-related properties in some item objects such as the MailItem object:

Items: selection in explorer

Miscellaneous: business cards, rules, and views

Security

Sharing

Solutions: solution-specific folders

Solutions: storing data

User interface: customizing form regions

User interface: customizing since Outlook 2007

User interface: customizing since Outlook 2010

User interface: solutions-specific folders

See also: Auxiliary APIs

The following resources provide more information about the Outlook auxiliary APIs.

Account management

Categorizing items

Contact pictures

Data degradation

Free/busy status

Item currency

Rebase calendars

See also: Primary references, resources, and code samples

The following resources provide more information about the primary Outlook references, resources, and code samples.

Major references and resources

Code samples