MAPI Support for Pegasus Mail v3.0 and later.

This help document describes briefly how to use the Simple MAPI and MAPI 1.0 interfaces for Pegasus Mail under Microsoft Windows. We strongly recommend that you spend some time familiarizing yourself with this document before attempting to use either MAPI interface.

Overview of MAPI

Which version is right for you?

Using the Simple MAPI interface

Using the MAPI 1.0 interface

Pegasus Mail System, Copyright © 1990-98, David Harris, All Rights Reserved.

"Microsoft", "Exchange", "Windows" and other words used in this document  are, may be, or probably will be trademarks of Microsoft Corporation.


Overview of MAPI
An overview of MAPI

MAPI (Mail Application Programming Interface) is a standard devised by Microsoft that theoretically allows applications that know nothing about mail to send and receive mail messages.

When it was originally devised, it was a largely ad-hoc specification for use with the now defunct Microsoft Mail product; this version of the specification was never formally released from its beta status, but evolved into what is now commonly called Simple MAPI. It is a simple interface, although poorly documented, and is still the most commonly-used MAPI format.

With the advent of Windows 95, Microsoft overhauled the MAPI specification. This process took them nearly two years and countless CD-ROMS filled with hundreds of thousands of pages of almost incomprehensible technical writing. The result was called MAPI 1.0, but was actually in essence Microsoft Exchange. MAPI devolved from being an open specification to which all developers could write, to being a hugely complex, difficult interface that served to entrench Microsoft's Exchange product in the marketplace. Under MAPI 1.0, the Windows Messaging product (Exchange) acts as a broker for services provided by third-party modules called Service Providers. This archive installs a Transport Service Provider allowing Windows Messaging users to send mail via Pegasus Mail.

It is important to note that the MAPI modules provided for Pegasus Mail are send-only implementations - they do not include the functionality necessary to allow applications to retrieve mail, only to send it. We plan to enhance our MAPI support in future.


Which version is right for you?

If you want to send mail using the Windows 95 Windows Messaging product, or via Microsoft Exchange, or if you want to send mail using Microsoft Office 97 or later, then you will need to install the MAPI 1.0 interface.

If you want to send mail via most other applications, the Simple MAPI interface is an easier and cleaner choice.

Note that you can generally only have one MAPI implementation on your system: you cannot usuall install both the Simple MAPI implementation and Windows Messaging on the same system. Some applications may allow you to install the Simple MAPI modules for Pegasus Mail by copying the MAPI.DLL and MAPI32.DLLs from this archive into the same directory as the application - experimentation is the way to determine whether or not this is possible for any given application. Usually, though, it's one or the other.

If you choose to install the Simple MAPI interface onto a system where the Windows Messaging MAPI DLLs are already installed (or MAPI DLLs from other vendors), then the existing versions of these files will automatically be placed in a directory called OLD_MAPI in your Windows System directory by the installer.


Using the Simple MAPI interface

You cannot use the Simple MAPI interface until you have run Pegasus Mail at least once on your system (this is necessary to create certain registry keys used by the MAPI interface).

After that, using the Simple MAPI interface is simplicity itself. Simply choose "Send..." from your application's "File" menu. What happens next depends on the application -- some may ask you for an address, while others may transfer you directly to Pegasus Mail with a new message window open. The MAPI module will run Pegasus Mail automatically if it is not already running.

At a technical level, you can access the MAPISendDocuments and MAPISendMail functions from any language capable of loading the DLL. MAPILogon will start Pegasus Mail if it is not running. MAPILogoff is supported but ignored.


Using the MAPI 1.0 interface

Using the MAPI 1.0 interface for Pegasus Mail is rather more complex than using the Simple MAPI module. The key to making it work is to create an appropriate Windows Messaging user profile specifying the Pegasus Mail Transport as the message carrier.

To create a suitable profile, follow these steps:

1: Click the "Start" menu, choose "Settings", and open the "Control Panel".

2: Double-click the "Mail" icon.

3: Click the "Show profiles" button

4: Click the "Add" button

5: In the Wizard window, click "Manually configure information services"

6: Give your profile a name

7: In the "Services" tab, click "Add". Add the following information services to your profile:

Pegasus Mail Transport

Personal Address book

Personal Folders

8: Save your profile.

Now, when you choose Send from your application's File menu, you will be asked to Windows Messaging: specify this profile, and you will have access to Pegasus Mail as a transport.

When sending mail, you will need to add addresses to your Personal Addressbook: when you do this, you will need to enter the E-mail type PMAIL to indicate that the message should be sent via Pegasus Mail; if you do not do this, the message will be placed in the Windows Messaging outbox and will never be sent.