MAPI

MAPI = Messaging Application Programming Interface, the heart of Microsoft's messaging programs. Extended MAPI serves three main purposes:

It's the programming interface used to write components that connect to different mail servers, provide access to custom address books and provide rich storage facilities -- in other words, the components that you can add through see on the Tools | Services dialog in Outlook.
You can use MAPI to develop new types of custom forms, not based on the built-in Outlook forms.
You can create addins for Outlook, Exchange and Windows Messaging that extend the functionality of those clients.

This is an advanced environment, mainly for C++ and Delphi developers.

As Outlook COM add-in developers have painfully learned with the release of Office 2002 Service Pack 2, which blocks the HTMLBody property, Extended MAPI offers no direct way of extracting the HTML content from all messages. As developer Michael Schacter explains (thanks!):

HTML messages in personal folders in Outlook 2000/IMO and in Outlook 2003 have an Extended MAPI property known as PR_BODY_HTML (0x1013001E) or PR_HTML (0x10130102). One is of type PT_STRING8 and the other is PT_BINARY; otherwise they return the same information: the native message HTML.

In Outlook 2000/CW and in Outlook 2002, there is no corresponding property stored in incoming e-mails on personal folders. (It appears that incoming messages on HTTP folders (like Hotmail) and on IMAP folders, do store the PR_BODY_HTML property.) Instead, the HTML is encapsulated in RTF and stored as compressed RTF. A call to MailItem.HTMLBody converts the RTF to HTML on the fly. This is accomplished through RTFHTML.DLL, the functions of which are--to my knowledge--undocumented.

There is a hack (in the best sense of the term) for converting RTF to HTML. However, it is not a very satisfying solution. In the sample code, search for "In actual fact" to see the beginning of the example.

MAPI SDK

For advanced designers, the Microsoft Developer Network offers many online resources and examples of programming with the MAPI SDK. See:

What MAPI Can Do That Outlook Can't

We thought it might be helpful to list some of the things that you can do with MAPI that you cannot do with the Outlook or CDO programming models. This list came from discussions with MAPI developers, a review of the SDK and samples at MSDN, and other resources listed on this page:

Add commands to the toolbars and menus in Outlook 97 and 98 (but not the right-click context menu)
Create and update MAPI profiles
Create new IPM.* forms that do not use one of the built-in Outlook forms as a base
Track the progress of print jobs
Handle selected items in a view in Outlook 97 and 98
Export and restore views
Add new functionality to the Advanced Find feature via the Advanced button
Adding tabs to the Tools | Options and folder Properties dialogs in Outlook 97 and 98
Notifications beyond the application-level events exposed in the Outlook 2000 object model
Improved performance -- up to 50 or 100 times better performance for some operations over multiple items
Add a custom pane to the folder view window
Save an attached OLE object; see OL2002 You Receive the Cannot Save the Attachments Error Message When You Try to Use the OnWrite Extension Event for sample code

Discussion

microsoft.public.platformsdk.mapi newsgroup at msnews.microsoft.com
microsoft.public.platformsdk.messaging newsgroup at msnews.microsoft.com
To subscribe to the MAPI-L mailing list for MAPI programming issues, send a message to LISTSERV@PEACH.EASE.LSOFT.COM with the text "SUBSCRIBE MAPI-L firstname lastname" -- leaving out the quotation marks and filling in your own name.

Samples

Building Outlook Add-ins with ATL-C++ -- using Extended MAPI
Extending Outlook with new features -- Walkthrough on how to build Exchange client extensions (C++)
HOWTO Build a Minimal Exchange Client Extension with VC++
MAPI example code for getting folders and messages (C++)
Although Developing Microsoft Exchange Applications with C++ is out of print, Ben Goetter has released the source code for Internet Idioms, Rich-Text Sentry and other useful Exchange widgets that he created as part of the process of developing sample applications for his book.
CDO 1.2.1 and CDONTS AppFarm Sample Applications -- some MAPI, too
FrmVwr.exe Extended MAPI Form Viewer
SAMPLE CmdLanch.exe Launches EXE from Custom Outlook Menu Item
XCLN: How to Retrieve Last Logon Time of Exchange Users Using Extended MAPI
TOOLFORM: Creating a C or C++ Form
Extended MAPI in DELPHI - Basic techniques, tips, and how-tos with 10 basic applications plus others. Covers address books, message stores, mail items, MAPI tables, AdviseSink, events, restrictions, MAPI profiles, integrated MAPI forms, and much more.
Exchange Hook -- Generic mechanism for adding Exchange/Outlook client extensions that perform actions when you open or close messages. With source code.
MAPI Storage Strategy Sample (Dialogic)
HOWTO Modify Exchange Folder Permissions Using IExchangeModifyTable -- C++ sample
HOWTO Open Message Using Outlook Object Model with Entry ID Obtained from MAPI
HOWTO Use the Outlook Object Model Within an Exchange Client Extension
HOWTO Create an Out-Of-Office Rule with Extended MAPI
HOWTO Determine Which Outlook Object Caused an Exchange Client Extension Event to Fire
HOW TO Retrieve Messages Based on a Particular Criteria
SAMPLE AdContac.exe Adds Sender of Incoming Message to Contacts -- Use this sample as a model for creating custom actions for Rules Wizard
New MAPI function to access native body
How to use named properties to relate Contact Address Book entries to e-mail messages, e-mail addresses, and picture attachments in Outlook 2003
How to use the dispidHeaderItem MAPI property to identify the state of a message that you receive in Outlook 2003
How to use MAPI to manage messages in a .pst file when you are using Outlook 2003 to download messages from an IMAP server
Updated MSLMS Sample -- message store sample from Microsoft's Stephen Griffin

Note: We haven't been able to find the source code downloads for all of the above samples, although some may be in the Exchange 5.5 SDK Final Version

MAPI Profiles:

HOWTO Add an Additional Mailbox to a MAPI Profile
HOWTO Create MAPI Profiles Without Installing Outlook -- Visual C++ sample for creating MAPI profiles on Exchange Server when no MAPI client has been installed.
HOWTO: Assign an S/MIME Certificate to a MAPI Profile for Use with Outlook
How to create MS Exchange profiles in MS Outlook with MAPI, Part I, Part II, Part III, Part IV
SAMPLE Profman2.exe - MAPI Profile Manager v2.0

Tools

Exchange Inspector	Free tool for examining the MAPI properties of items in Exchange mailboxes and public folders and in the Global Address List. Triggers Outlook security prompts.
MAPI33	.NET wrapper around Extended MAPI.
MAPI Explorer	Explore the internal structure of the various objects components of persistent MAPI data.
MAPIProp	Free COM component designed to read MAPI-properties of CDO and Outlook Object Model objects for Microsoft Outlook 2000, 2002/XP, 2003 without triggering security prompts. Microsoft Visual C++ 6.0 source code included.
MAPI Toolkit	Library for simplifying the task of creating applications, especially MAPI service providers, that interact with the Microsoft Messaging API system library. Free.
MAPIViewer	Provides an Explorer-like interface for browsing MAPI stores and viewing items and their properties. Free.
MDBViewer	MAPI property and object viewer included with Exchange Server.
Outlook Spy	Developer utility for finding out what's going on inside Outlook, via the Outlook object model, CDO and MAPI. You can edit and delete most properties, drag properties from one item to another, copy values to the clipboard, run scripts, monitor events.
RAPWare Easy MAPI	Developer toolkit for Delphi for partial use of Extended MAPI interfaces (for example, to send messages without triggering Outlook Email Security Update prompts).
Visual MAPI	Automatic code generator for MAPI (i.e. CDO) projects in Visual Basic or VBA. Donationware. Requires the VB 6.0 runtime.

Problems

Known problems (general):

Outlook 2003 issues:

Outlook 2002 uses a different design for connecting to MAPI transports. Therefore, some third-party MAPI transports may not work as expected. See:

Outlook 2002 issues, many fixed in Office XP Service Pack 1):

Outlook 2002 issues fixed in SP3:

Outlook 2000:

PRB CreateMsgService Fails with MAPI_E_NOT_FOUND Against Outlook 2000

More Information

Alexander Gorlach - weblog covering MAPI issues for C++ programmers
Microsoft Exchange and MAPI Development Frequently Asked Questions (Ben Goetter)
Mapi Forms Need IDispatch Interfaces to Be Implemented (MSKB)
MAPI or CDO -- performance tests for accessing the GAL
Microsoft sending-mail-from-code FAQ
OL2000 The PrepareForm() and ShowForm() Functions Do Not Work
INFO The Basics of Exchange Client Extensions
OL98 New Optional Programming Interface Supported for Outlook Extensions
HOWTO Force a Particular Internet Encoding by Using MAPI
INFO Entry IDs of Outlook Special Folders
INFO Outlook Named Properties Are Not Supported by MAPI-CDO
How to set up a MAPI profile manually -- White paper on the registry structure of Outlook MAPI profiles and how to use MAPI to add new entries. The author has successfully used this technique to add a MAPI store provider to Outlook 2000 in Internet Mail Only mode, where MAPI profiles are not directly supported.
Information about the new flag in the PR_STORE_SUPPORT_MASK property that indicates support for Unicode in Outlook


	© 2002-6 TurtleFlock, LLC All right reserved. About OutlookCode.com Send comments to webmaster@outlookcode.com Designed and Implemented by TerraLink USA FrontPage Integration by RobsonDesignWorks


get Sue's code \| forums \| share your own code \| registration