Novell is now a part of Micro Focus

Using Messaging APIs

Articles and Tips: article

Senior Editor
Systems Research Department

01 May 1995

Messaging APIs allow developers to build E-mail interfaces into a variety of applications. The leading programmatic APIs in the E-mail industry are MAPI (from Microsoft), VIM (from a consortium of companies), and CMC (from the X.400 API Association. MAPI 1.0, or Extended MAPI, defines a complete architecture for messaging applications. This architecture defines both messaging clients and messaging services.

Simple MAPI is a subset of Extended MAPI and includes the 12 most common API calls. VIM is an open interface defined by Apple, Borland, IBM, Lotus, MCI, Novell, and Oracle. VIM is a complex API that allows developers to access a wide variety of messaging systems on a wide variety of operating systems. CMC 1.0 is an open standard that is widely supported in the industry. It is a simple API (10 calls) that provides a set of high-level functions for mail-enabled applications to send and receive electronic messages. CMC 2.0 will be a complex API that runs on the same level as MAPI 1.0 and VIM 1.0.

Part 2 of this two-part article will discuss Novell's messaging APIs as well as Novell's overall messaging strategy.


E-mail APIs are valuable because developers can use them to build E-mail interfaces into applications. For example, a developer could program a network security application (via an E-mail API) to automatically send a message to the network administrator when an unauthorized attempt is made to access the network. Applications can use E-mail APIs for many different tasks, including looking up addresses, creating messages, and sending messages.

There are two basic types of E-mail APIs: file-format APIs and programmatic APIs. File-format APIs generally allow simple text files to be imported or exported to or from an E-mail system. For example, the ASCII file might include the date, the name of the sender, the recipient's name and address, and the message itself (all of which must follow the format specified by the API). The E-mail system can then import this file, transport it, and export it to the recipient.

In the case of Novell's SMF-71, a prominent file-format API, importing and exporting are not necessary. Instead, NetWare MHS (Message Handling System) regularly scans certain directories and automatically transports files that are compatible with SMF-71.

File-format APIs include the following:

  • Novell's SMF-71 and SMF-70

  • Novell's API Gateway

  • Lotus cc:Mail's Import/Export

  • Microsoft Mail's FFAPI

Programmatic APIs allow applications to communicate directly with an E-mail system using a library of subroutines (which are linked at compile time). Programmatic APIs include the following:

  • CMC

  • MAPI

  • VIM

Along with being file based or program based, E-mail APIs can also be simple or complex, workstation-based or server-based. CMC, for example, is a simple API consisting of approximately 10 functions. VIM, on the other hand, is complex, with approximately 50 functions. MAPI is a workstation API while SMF-71 if a server API.

To further complicate matters, different versions of the same API can be quite different. Simple MAPI, for example, includes a limited number of functions and is quite similar to CMC. Extended MAPI, however, is complex, like VIM. In addition, the soon-to-be-released version of CMC (2.0) is expected to fall into the same category as Extended MAPI and VIM.

The upshot is that E-mail APIs, while undoubtedly valuable to developers, are sometimes difficult to use because of the confusing array of multiple APIs and multiple versions of APIs. The purpose of this DevNote is to give solid introductory information on the leading programmatic E-mail APIs, clarify differences among versions, and tell you how to obtain software development kits (SDKs), specifications, and other information.

This DevNote, which is part 1 of a two-part series, discusses the following APIs:

  • MAPI (Messaging Application Programming Interface), from Microsoft. As noted, true MAPI, or Extended MAPI, is a complex API. Simple MAPI, sometimes called SMAPI, is a subset of Extended MAPI.

  • VIM (Vendor Independent Messaging), a complex API originally developed by Lotus and endorsed by Apple, Borland, and Novell. The current version is VIM 1.0; VIM 2.0 is now in development but has not been officially released.

  • CMC (Common Messaging Call), developed by XAPIA (the X.400 API Association). XAPIA is an open association of companies interested in messaging. Members include Digital Equipment Corp., Hewlett Packard, IBM, Intel, Lotus, Microsoft, Novell, and Oracle. As noted, CMC 1.0 is a simple API, while CMC 2.0 (scheduled for release in mid-1995) is much more complex.

Part 2 of this series will discuss Novell's messaging APIs as well as Novell's overall messaging strategy.


Microsoft MAPI 1.0, also known as Extended MAPI, defines a complete architecture for messaging applications. MAPI is a set of functions that applications can use to create, manipulate, transfer, and store messages.The MAPI architecture can be used for such applications as E-mail, scheduling, personal information managers, bulletin boards, and online services (all of which can run on a broad range of platforms). MAPI also offers a common interface that developers can use to build E-mail-enabled applications independently of the underlying messaging system.

MAPI takes its design from the Windows printing model. Just as Windows enables applications to print to several different sources (via a print spooler and independent printer drivers), MAPI enables messaging applications to run with several different messaging services.

The MAPI architecture defines both messaging clients and messaging services. To use a service, a client must first set up a session, which is a specific connection between the client and MAPI based on data included in a profile (which lists configuration information).

Once the session is established, the client can access MAPI services, which fall into three basic categories:

  • Address Books, which might be thought of as telephone directories. These are a collection of one or more lists of message recipients. Each list is known as a container. Custom address books are supported.

  • Message Transports, which transfer messages among clients. MAPI message transports support interaction among a variety of hardware platforms and messaging systems.

  • Message Stores, which organize and store messages and allow them to be accessed. Messages are kept in folders, which are organized hierarchically. In addition, the user can alter messages and then put them back in their folders. A user who received a Microsoft Excel spreadsheet as an OLE object in a message, forexample, could run Excel from within the message, modify the file,and then save the modified file as part of the message.

MAPI Programming Interfaces

As Figure 1 shows, Microsoft offers a variety of programming interfaces for MAPI 1.0, allowing developers in many different development environments to use MAPI.

Figure 1: This shows the OLE Messaging Interface as a layer that is built on top of Extended MAPI 1.0.

The OLE Messaging Library does not provide access to all of the Features of Extended MAPI. For example, it is intended primarily for clients and is not appropriate for service providers.

The following table details the programming interfaces offered for MAPI 1.0.


MAPI customcontrols

User interfacefor Visual Basic users.

Simple MAPI

Simplifiedinterface containing 12 common API calls.

OLE MessagingLibrary 1.0

Programmableobjects for use by Visual Basic and VBA developers.


API calls forC and C++ users (described later in thisDevNote)

Extended MAPI

OLE interfacesfor C and C++ programmers.

MAPI Functions

The following is a partial list of MAPI calls:



Open a container,user, or distribution list


Display userdialog box for addressing


Display detailsdialog box for a given entry


Find a recipientusing a partial name


See if twoEntryIDs refer to same object


Create EntryIDfor one-off address


Obtain notificationswhen book changes


Obtain per-recipientoptions for given type

Property MgmtAPIs

Utilized forin-detail property processing

AddressBook Containers


Obtain listof container's recipients


Obtain listof subcontainers


Copy entriesto a container


Create newentry in container


Delete container,user, or distribution list

Property MgmtAPIs

Utilized forin-detail property processing



Obtain a listof available properties


Obtain selectedvalues


Start workingon a property


Set value ofselected properties


Copy contentsof current object


Make changespermanent


Delete selectedproperty list


Release requiredstorage


Obtain associatednames


Obtain andassign IDs to associated names


Obtain texterror message



Open folderor message


Obtain notificationswhen an object changes


Define a folderfor incoming messages


Return wherereceived messages are placed


See if twoEntryIDs refer to the same object


Delete currentmessage from queue


Log off frommessage store

Property MgmtAPIs

Utilized forin-detail property processing



Obtain infoon subfolders of current folder


Obtain summaryinfo on messages in folder


Define searchcriteria and begin search


Obtain searchcriteria for a search results folder


Open a messageor subfolder of current folder


Move or copya folder into current folder


Move or copymessages into current folder


Create newfolder


Check a message'sstatus


Specify 32-bitstatus associated with a message


Create newmessage


Remove subfolderof current folder


Remove messagesfrom a folder


Specify defaultcontents sort order for a folder

Property MgmtAPIs

Utilized forin-detail property processing



Obtain a message'srecipients


Obtain a message'sattachments


Open attachment


Create newattachment


Remove attachment


Save changes to a message


Set message-readflag, send report to sender


Save changes,mark message ready for sending


Utilized forin-detail property processing



Save changesto attachment

Property MgmtAPIs

Utilized forin-detail property processing

Simple MAPI

As mentioned, Simple MAPI is a subset of MAPI and contains the 12 most common API calls, as follows:


Start MAPIsession


End MAPI session


Free memoryallocated by messaging subsystem


Send standardmail message


Send standardmessage via dialog box


Categorizeincoming messages


Read messages


Store messages


Delete messages


Create setof recipients via dialog box


Display addressbook details via dialog box


Change friendlyname to address book entry

Simple MAPI can be found in the Visual Basic MAPI custom control.

Simple MAPI is quite similar to CMC 1.0, and most vendors, including Novell, are encouraging developers to use CMC 1.0 instead. Even Microsoft itself is moving in this direction and includes CMC 1.0 as part of MAPI 1.0.

Microsoft SDKs and Specifications

Simple MAPI is now part of the Windows SDK. Future versions of Windows will include Extended MAPI. To access the Simple MAPI SDK on CompuServe, type GO MSNETWORKS at the CompuServe prompt and move to section 17.

The Microsoft Mail SDK allows C or C++ programmers to access MAPI calls, create custom commands and message types, link and synchronize MS Mail directories with other leading E-mail and messaging systems with FFAPI, and transfer files between messaging systems using FFAPI.

To obtain MAPI documentation and executable files from the Internet, use anonymous ftp to access Move to the ADVSYS/MAIL/PCMAIL/DOCS directory and download the following files: MPAI=VR1.ZIP, SMAP=VSE.ZIP, and MAPI=VSD.ZIP.

Microsoft Corp. One Microsoft Way Redmond, WA 98052-6399 Telephone: 800-227-4679


VIM is an API that allows developers to access a wide variety of messaging systems, including cc:Mail, Notes, and MHS, on a wide variety of OSes, such as DOS, Windows, OS/2, Macintosh, and UNIX.

VIM is an open interface, and the specification is publicly available free of charge. The spec has been defined by members of the VIM consortium and is not controlled by any single company. The members of the VIM consortium are Apple, Borland, IBM, Lotus, MCI, Novell, and Oracle. Many other companies have announced support for VIM.

The goal of the VIM consortium was to establish a standard messaging interface for application developers that is available in all VIM-compliant mail systems as well as to include advanced features that take advantage of specific features in underlying mail systems. Therefore, VIM includes a set of 45 functions that all VIM-compliant mail systems must provide, and an optional set of 10 functions that may not be available in all mail systems.

Applications that have the requirement to run on all VIM-compliant systems have to be designed to use only the minimal set. Applications that want to take advantage of the more advanced, optional features have to check if those functions are supported by the underlying mail system.

Relationship Between VIM and Other Messaging APIs

Apple's OCE (Open Collaborative Environment) is a System 7 extension that offers store-and-forward messaging services, security, and directory services. Apple is implementing VIM on top of OCE.

The small set of MAPI functions that will be available on non-Windows platforms is basically equivalent to VIM's two Simple Messaging Interface (SMI) function calls. The large majority of MAPI calls, the equivalent of VIM's 45 minimal set and 10 optional set, will not be available on non-Windows platforms.

Lotus plans to offer a VIM-to-MAPI integration layer in the absence of Microsoft's support for VIM.

XAPIA APIs are primarily designed for X.400 transport and message-store services, while VIM offers access to a wide variety of transport, store, and delivery services in addition to X.400. Nevertheless, Lotus is a member of both XAPIA and the VIM consortium and is therefore interested in supporting both standards when appropriate. Lotus's cc:Mail Router X.400, for example, supports both XAPIA and VIM APIs.

Just as Extended MAPI incorporates CMC 1.0, the next version of VIM (2.0) will replace the SMI functions with CMC 1.0.

The VIM Framework

VIM makes mail and messaging services available through a well-defined interface. A messaging service enables its clients to communicate with each other in a store-and forware manner. VIM defines messaging as the data exchange mechanism between VIM-aware applications. The underlying messaging system takes care of the routing and delivery of messages within that messaging system. Messages are delivered to a message container. Each VIM-aware application is associated with and has access to tone or more message containers.

A VIM-aware application may have access to one or more address books. Address book services are defined by VIM in a messaging context to support storing information about users, groups, applications, etc., including the location of their message containers. Applications can use the address book services to look up these addresses in order to communicate with them.

VIM Functions

SimpleMessaging Interface


Sends standardmail message via user interface


Sends a standardmail message



InitializeVIM for this process


Return implementationfeatures and limits


Return defaultvalues required for login


Open authenticatedsession


Get currentauthenticatedd username


End the session


Terminate VIMfor this process


Return textassociated with a status code

MessageCreation and Submission


Create newmessage


Create replyto or forward existing message


Set value ofmessage header attribute


Add an itemto a message


Submit messagefor delivery


Close messagewithout sending it



Open specifiedmessage container


Enumerate messagesin a container


Enumerate attributevalues over container


Remove messagefrom container


See if newmessages have been delivered to a container


Count unreadmessages in an inbox


Extract messageand store in a file


Open messageextracted with VIMExtractMessage


Close specifiedmessage container

MessageAccess and Attributes


Open a messagefor further access


Mark a messageasbeing read and send return receipt if appropriate


Get messageheader attributes


Get multivaluemessage header attributes


List itemsin a message


Read an item into a buffer or file


Open an item for reading


Read a piece of a message item


Close a message item


List recipients of a message


Open a forwarded message


Get and verify a message's digital signature

Address Books


Return available address books


Open a named address book


Set currentsubtree for hierarchical address book


Get currentsubtree for hierarchical address book


List entries in address book


Create a new address book entry


Search address book for specified entry


Get attributes for address book entry


Add or change attributes for address book entry


Get names ofnamed attributes for address book entry


Get named attributesfor address book entry


Add or changenamed attributes for address book entry


Remove entry from address book


Add member name to a group


Remove member name from a group


List members of a group


Close address book

VIM 2.0

The specification for VIM 2.0 (also called VIM2) is now in draft form. Changes include the following:

  • Vendor-specific enhancements

  • Clarifications and corrections

  • Gateway development issues

  • IBM VIC calendaring proposal

  • Administrative API enhancements

  • Definition of header files

  • Resolution of multiplatform issues

  • Message container enumeration method

  • Error code for reporting authorization failure

  • Mechanism for sorting messages in a container

  • Technique for displaying/alerting user to new messages

  • Procedure for removing items from message being composed

  • Additional vendor selectors

  • Replacement of SMI calls with CMC 1.0 calls

VIM2 replacement functions include the following:

  • VIM2OpenSession

  • VIM2OpenMessageContainer

New functions for VIM2 include the following:

  • VIM2CreateMessageContainer

  • VIM2RemoveMessageContainer

  • VIM2MoveMessageContainer

  • VIM2EnumerateMessageContainer

  • VIM2SetMessageContainerAttributes

  • VIM2MoveMessage


The Lotus VIM Developer's Toolkit contains the following:

  • A developer's guide that contains information about Lotus's implementation of VIM and a description of the various VIM functions and parameters

  • Include files with all VIM definitions to be included in the application source code

  • Import libraries, DOS static-link libraries, and DOS object files to be linked with the application object code

  • A Visual Basic runtime DLL

VIM runtime libraries will be an integral part of cc:Mail and Notes products. The first products to bundle the VIM runtime components were cc:Mail for Windows 2.0, cc:Mail for OS/2 WPS 1.0, and Notes 3.0.

Lotus continues to support and enhance Import/Export, a file-based API.

C, C++, and Visual Basic can be used for calling any VIM and SMI function. SMI functions can be accessed by any macro language, including Ami Pro, Excel, and Visual Basic.

The VIM spec is in the public domain and can be obtained from Lotus by calling 800-343-5414.

Online information can be obtained from the cc:Mail BBS--415-691-0401, file area 23, and CompuServe--LOTUSB, Section 11 and LOTUSC, Section 15.

Contact Lotus for further information.

Lotus Developer Relations Group: 800-DEV-RELS, 617-693-4448.


The Common Messaging Call (CMC) API provides a set of high-level functions for mail-enabled applications to send and receive electronic messages.

CMC is considerably simpler than either Extended MAPI or VIM. In addition, it is an open standard that is widely supported in the E-mail industry.

The interface is designed to be independent of the actual messaging protocol employed between sender and recipient. The interface will support the creation and reception of standard message formats such as X.400 and SMTP (RFC822) as well as proprietary message formats. This is achieved through generic definition of capabilities common tomost messaging protocols, plus a mechanism for defining extensions, which can be used to invoke protocol-specific services.

Another important consideration in the design of this API is to minimize the number of function calls needed to send or receive a message. For example, a mail-enabled application can send a message with a single function call and receive a specific message with two calls.

The CMC API is designed to be complementary to existing XAPIA and X/Open APIs, such as XMHS and XMS.

The CMC interface is designed to allow c common interface over virtually any electronic messaging service. For each CMC implementation, the view/capabilities presented by CMC must be mapped to the view/capabilities of the underlying messaging service.

To maximize interoperability between CMC applications that use similar underlying messaging services, it is critical that a common mapping be defined by the industry segment representing the relevant messaging protocol or interface.

To that end:

  • XAPIA will define the common mapping between CMC and the X.400 protocol, from the perspective of other XAPIA-defined X.400 APIs.

  • Standards bodies, vendors, or vendor groups representing a specific messaging protocol or interface are encouraged to define a common mapping between CMC and the relevant messaging protocol or interface.

To maximize interoperability between CMC applictions that use differing underlying messaging services, it is critical that mapping definitions be designed with such interoperability in mind.

To that end, the following guidelines are offered. This list is not comprehensive.

  • Map message text strings to international character sets, wherever appropriate or possible.

  • Map message attachment types to commonly recognized attachment types, wherever appropriate or possible.

The CMC specification defines the CMC API at two levels of abstraction. It defines a "generic" interface independent of any particular programming language, and a C language interface based on the American National Standard for the C programming language. The generic interface is included to guide the development of other language-specific specifications, such as Pascal.

In order for an implementation of the CMC API to conform to the specification, the implementation must meet the following criteria:

  • All functions and data structures must be implemented as defined. Statements elsewhere in the specification which describe features as optional or with exceptions take precedence over this criterion.

  • The implementation must be able to send and receive at least the CMC IPM message type.

  • Character set support is up to the underlying implementation. Support for an implementation-defined default character set is required. Optionally, other character sets maybe supported. Counted string support is not required.

  • All extensions are optional. Vendors are encouragedto support the CMC-defined standard extension set specified in the CMC spec.

    It is further encouraged that standard extension sets are developed for any proprietary or nonproprietary messaging services for which a CMC interface is provided, to accommodate features specific to that messaging service, and that the extension set be registered with XAPIA.

  • Minimum conformance for an extension set will be defined by the creator of the extension set.

CMC Functions



Send a mail message


String-based function to send mail

Receiving Messages


Perform an action on a message


List summary info on certain messages


Read and return a specified message

Looking Up Names


Look up addressing information



Free memory allocated by messaging service


Terminate a session with messaging service


Establish asession with messaging service


Determineinfoabout installed CMC service

The CMC 1.0 spec also covers functional architecture, data structures, and programming examples.

Programming Example

The following example shows query configuration, logon, and logoff.

/* local variables used */

CMC_return_code Status;

CMC_boolean  UI_available;

CMC_session_id Session;

/* find out if UI is available with this implementation before starting */

Status = cmc_query_configuration (

         NULL,   /* Default service. */

         NULL,   /* Prompt for username. */

         NULL,   /* Prompt for password. */

         NULL,   /* Default character set. */

         (CMC_ui_id)NULL, /* Default UI ID.  */

         CMC_VERSION, /* Version 1 CMC calls. */

         CMC_LOGON_UI_ALLOWED, /* Use UI to display

                             errors. */

         &Session,  /* Returned session ID. */&
         NULL,   /* No extensions. */

   /* error handling */

 /* Do various CMC calls  */

 /* Log off from the implementation */

 Status = cmc_logoff (

           Session,   /* Session ID.  */

           (CMC_ui_id)NULL, /* No UI will be used.*/

           0,    /* No flags.  */

           NULL);   /* No extensions. */

   /* error handling */

CMC 2.0

CMC version 2.0, also known as Full CMC, is scheduled for release in mid-1995. CMC 2.0 is much more complex than 1.0, as shown by the size of the specifications: the 1.0 spec is 90 pages long while the 2.0 spec is 250 pages long. The list of functions has grown from 10 to more than 40. Full CMC functions fall into the following categories:

  • Composition

  • Enumeration

  • Messaging

  • Stream

  • Name Handling

CMC Specification

The CMC 1.0 specification is available from a variety of sources. On CompuServe it is in the GENCOM forum, XAPIA selection, under the filename CMC_V1.ZIP.

The spec is also posted on the Internet in WinWord format. It is available on in /DEVELOPR/MAPI. Filenames are as follows:

CMCSPC.PS.ZIP  Postscript


   CMCSPC.RTF.ZIP  Rich Text


Copies of the spec can also be obtained from Omnicom PPI at 800-666-4266, and PSC at 800-268-7737.


Other XAPIA APIs include the following:

  • CSA (Calendaring and Scheduling API). Allows calendaring and scheduling capabilities to be integrated into desktop applications such as project management, workflow, and electronic forms.

  • XOM (X/Open Object Management), from X/Open Company Limited and XAPIA. The XOM spec defines the relationship between messaging objects and directory objects. X/Open defines Object Management as "the creation, examination, modification, and deletion of potentially complex information objects."

  • X.400 Gateway API. Programmatic interface allowing messages to pass between a mail-enabled application or a proprietary mail system and an X.400 message service.

  • XDS (API to Directory Services). Programmatic interface to X.500 directory service providers that allows application programs to query the directory system.

  • XMS. Message store API that defines how an application program submits E-Mail messages to and received messages from the X.400 message store.

For more information on XAPIA, send E-mail to Leslie Schroeder in the XAPIA office:



The following documents were used in preparing this article:

"A Short Tour of Microsoft MAPI," published by Microsoft Corp., not dated.

Common Messaging Call API, Version 1.0, published by the X.400 API Association, Jun. 1, 1993.

Common Messaging Call API, Version 2.0, Draft 7, published by the X.400 API Association, Jan. 30, 1995.

Ferris E-Mail Analyzer, published by Ferris Networks, Inc., Apr. 1994.

Ferris E-Mail Analyzer, published by Ferris Networks, Inc., May 1994.

Microsoft Mail Software Development Kit product brief, published by Microsoft, 1993.

Microsoft Messaging Application Program Interface (MAPI), a white paper published by Microsoft Corp., 1992.

New Riders' Guide to E-Mail and Messaging, by Larry Morris, New Riders Publishing, 1994.

SMF v71 Programmer's Reference, published by Novell Inc., 1992.

"Snappy MAPI: The Messaging Application Programming Interface," by Mark S. Burgess, Data Based Advisor, Feb. 1994, pp. 158-162.

Vendor-Independent Messaging Interface Functional Specification, Version 1.0, published by Apple Computer Inc., Borland International Inc., Lotus Development Corp., and Novell Inc., Mar. 23, 1992.

Vendor-Independent Messaging Interface Functional Specification, Version 2.0 draft, published by Apple Computer Inc., Borland International Inc., Lotus Development Corp., and Novell Inc., May, 1994.

"VIM Developer's Toolkit Q's and A's," published by Lotus Development Corp., Jul. 30, 1993.

XAPIA literature from the X.400 API Association, published 12/94, 1/95, and 2/95.

X/Open OSI-Abstract-Data-Manipulation (XOM) API, CAE Specification, published by X/Open Company Limited and the X.400 API Association, Dec. 1991.

* Originally published in Novell AppNotes


The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates