MAPI stands for Messaging Application Programming Interface, the system component that the Microsoft corporation has included into its Windows® operating system and the API to use that component with Windows applications.
The MAPI infrastructure provides an additional level of abstraction. Windows applications do not deal directly with a groupware server (or any other "data store"). Instead, applications send Messaging requests (such as "list my mailboxes", "retrieve message number X", etc.) to the MAPI component, and the MAPI component uses the installed "Connector" modules to send those requests to an Exchange® server, to locally stored "personal folders", to a fax server, etc.
The expandable nature of the MAPI architecture allows for creation of additional "Connectors" that can interact with various server products. One of the problems that such a Connector has to solve is data format: Windows applications send data objects via MAPI to Connector modules in the so-called "MAPI object" format that has very little in common with any Internet format. The CommuniGate Pro MAPI Connector converts the MAPI data into one of the standard Internet formats and stores the converted "messaging objects" as standard Internet messages in a CommuniGate Pro Mailbox. When reading those Mailboxes, the CommuniGate Pro MAPI Connector converts messages back into the "MAPI object" format and passes the converted objects back to MAPI and Windows applications (such as Outlook).
The CommuniGate Pro MAPI Connector acts as a "MAPI provider". It accepts Messaging API requests from Microsoft Outlook (Outlook 2002, Outlook XP and later) running in the "groupware" mode, and from other Windows applications. The MAPI Connector converts these requests into extended IMAP commands and sends them to the CommuniGate Pro Server.
The CommuniGate Pro MAPI Connector also performs data conversion between proprietary
Microsoft "objects" data formats and the standard Internet data formats.
Because the standard Internet formats are used, messages stored with the CommuniGate Pro MAPI Connector can be read using any standard POP3 or IMAP mail client, the CommuniGate Pro WebUser Interface, or any XIMSS-based client.
The CommuniGate Pro MAPI Connector uses TCP/IP networks and should be configured to connect to any non-TLS (clear text) IMAP port of your CommuniGate Pro server (the port 143 is the standard IMAP port).
The CommuniGate Pro MAPI Connector supports both clear text and secure (SSL/STARTTLS) connections, and it can use plain text and secure CRAM-MD5 login methods.
The CommuniGate Pro MAPI Connector contains two code parts (shared libraries).
The starter code part should be installed on Windows workstations. It provides
the configuration interface and it is used to connect to the CommuniGate Pro server.
The main MAPI Connector functionality is implemented as a shared library stored in the Server application directory, and it is called the server code part.
When the MAPI Connector starter code connects to the CommuniGate Pro Server, the Server sends the server code part of the MAPI Connector to the client computer.
This method allows you to deploy "regular" MAPI Connector updates by updating your CommuniGate Pro Server software only, without running the MAPI Connector Installer on all client workstations.
You need to install the MAPI Connector starter code part shared library (a .dll file) on Microsoft Windows workstations. Download the MAPI Connector archive and unpack it. The unpacked folder contains the Setup.exe file.
Start the unpacked Setup.exe application to install or update your CommuniGate Pro MAPI Connector software. After successful install, the application may ask you to re-create your Mail Profile.
You can use the same Setup.exe application to uninstall the MAPI Connector software from the workstations.The MAPI Connector Setup.exe program can be started in the silent mode (without any user interface dialogs) using the following command-line parameters:
|install or upgrade the MAPI connector
|remove the MAPI connector
|do not ask for profile configuration
|do not display error messages
The cgmxui32.inf file can be used to automatically set the the MAPI Connector Account Settings and Shared Accounts. Download this file and modify it to fit your needs, then place it into the same directory where the Setup.exe application resides. The application will use it during the installation process.
When the CommuniGate Pro MAPI Connector is installed on a client workstation, you can create a Mail Profile that will tell Outlook and other applications to use the CommuniGate Pro MAPI services.
If you use Outlook 98 or Outlook 2000 check that it is configured to run in the "groupware mode". Start Outlook, and
select the Options item from the Tools menu. The Options dialog box appears. Select the
Mail Services Tab and click the Reconfigure Mail Support button to open the E-mail Service Options
dialog box. Check that the Corporate or Workgroup option is selected.
Note: you may need the MS Office installation CD-ROM to complete Outlook mode switching.
Note: the latest versions of the MAPI Connector (1.54 and up) rely on the Unicode-enabled interfaces of MAPI that are not compatible with Outlook 98 and Outlook 2000.
Open the Mail Control Panel and click the Show Profiles button. The list of Mail profiles appears. If the CommuniGate Pro MAPI Installer has instructed you to re-create your existing Profile, select the old Profile and click the Remove button.
Click the Add button to create a new Profile. Depending on the version of the Outlook and the Mail control panel installed, you will see several dialog boxes. If you see a dialog box with the Additional Server Types option, select that option. Select CommuniGate Pro Server as the "service" or "additional server type".
You can add other services into the same Profile.
When the CommuniGate Pro service is added to a Mail Profile, the service settings can be configured. Later you can open the Mail control panel, open this Profile, and open the CommuniGate Pro Server settings. You can also use the Services item in the Outlook Tools menu to open the service settings.
Use the Add and Remove buttons to specify the names of other CommuniGate Pro Accounts. If you want to access an Account in a different Domain, specify the full name: accountName@domainName.
The Account owners must grant you Mailbox Access Rights, otherwise you won't be able to see and open Mailboxes in those Accounts. See the Mailboxes section for more details on foreign Mailbox access.
The Synchronization settings allow you to override the selection of folders to work with in the Offline mode.
You can specify Access Control List for your Mailboxes to grant access to those Mailboxes to other CommuniGate Pro users.Select a Mailbox in the Outlook Folder List, and use the Properties menu item to open the Properties dialog box. Open the Permissions panel:
Use the Add and remove buttons to specify the Accounts and other identifiers to specify those who should have access to this Mailbox.
Select an identifier in the list and use the checkboxes to grant required access rights to
this identifier. See the Mailboxes section for more details on Mailbox ACLs.
Note: a user needs to have the Admin Access Right in order to specify the default Mailbox (Folder) View.
The MAPI Connector supports the "delegation" feature: users can send E-mails and Calendar invitations "on behalf of" or "as" other users.
To grant some user delegation rights for your Account,grant that user the Read (Select) right for your INBOX.
The Free/Busy information is a file specifying when the person is busy, free, out of the office, etc. This information is usually made publicly available, so other users can access it when planning their meetings, scheduling appointments, etc. To compose the Free/Busy data, the groupware client application collects data from user Calendar(s), and merges it into one Free/Busy schedule.File Storage.
Note: Make sure your CommuniGate Pro Account Settings allow the MAPI Connector to store a file with your Free/Busy information in your File Storage.This feature allows users of Outlook and other calendaring clients to access your File Storage via HTTP and retrieve your Free/Busy information. The URL for the CommuniGate Pro Connector user Free/Busy information is
This option will be used by the Outlook application when it needs to retrieve the Free/Busy information for an E-mail user. The application substitutes the %SERVER% symbols with the domain part of the user E-mail, and the %NAME% symbols with the username part of the user E-mail, so for the E-mail address firstname.lastname@example.org the Outlook will use the http://myserver.dom/~john/freebusy.vfb URL to retrieve John's Free/Busy schedule.Note: the suggested Search URL will work only if your CommuniGate Pro Server accepts WebUser Interface connections on the port 80. If it accepts them on the default port 8100, or on any other non-standard port, the Search URL must include that port:
Search URLs specified above allow users to retrieve Free/Busy information for the users of the same CommuniGate Pro system.
The Search URL may be used to retrieve the Free/Busy Information for users of other CommuniGate Pro Servers, as long as the Search URL correctly represents their Free/Busy file URLs. To overwrite the Search URL and specify a different (correct) path to some remote user Free/Busy file, create a Contact record for that user, click on the Details tab and enter the correct FreeBusy file URL into the Internet Free-Busy Address field. See the Microsoft Outlook manual for more details on these settings.
When you work in the Offline mode, the MAPI Connector does not have access to the messages stored on the CommuniGate Pro server. To be able to work productively, you need to make sure that the messages you need are stored in the MAPI Connector local cache. You specify the cache options on the per-Mailbox (per-folder) basis.Use the Options item in the Outlook Tools menu to open the Options dialog box. Then open the CommuniGate Pro panel:
Select the folder you need to work with when you use the Offline mode, and select the downloading method. If you select to download the entire message, the folder name will be shown in bold, if you choose to download message headers only, there will be only a check mark next to the folder name.
Use the Outlook Tools->CommuniGate Pro Server menu to synchronize the changes you do in the Offline mode with the CommuniGate Pro server.
Synchronization takes place when the Send/Receive operation is initiated (manually or automatically, based on the schedule).
The MAPI Connector allows you to specify the server-side Rules to process mail coming to your Account.Use the Tools->CommuniGate Pro menu to open the Rules editor window:
Click the New button to create a new Rule. New Rule has no condition and no action.Click the Add button to add Rule conditions and actions:
See the Automatic Rules section for more details.
The MAPI Connector employs the user WebMail (WebUser Interface) settings. It instructs the MAPI applications (such as the Microsoft Outlook) to use the same names for "Special" Mailboxes. As a result MAPI applications and the WebUser Interface use the same Trash or Deleted Items Mailbox to store removed messages, use the same Mailbox as the Main Calendar Mailbox, etc.
The MAPI Connector also retrieves the user Domain Mail Trailer setting. The content of that setting is added to all non-encrypted and not-signed text messages submitted via the MAPI Connector.
The values specified via the Account Settings panel are stored in the WebUser Settings, so both the WebUser Interface and MAPI sessions use the same From:, Reply-To:, and Organization values.
The MAPI Connector allows Outlook users to employ Real-Time (VoIP, etc.) functions of the CommuniGate Pro Server.Outlook users can initiate a phone call using the telephone number specified in a Contact item. Right-click a Contact record to open a pop-up menu and select the Call using CommuniGate Pro item:
You can also use the CommuniGate Pro Server submenu in the Tools menu.A dialog box with the Contact name and phone number appears: You can type a different phone number in the second field. That number will be used for this call only, it will not be stored with the Contact Item.
Click the Start Call button to initiate a call. All your SIP devices will start to ring immediately. Answer this call on any device, and the Server will instruct it to initiate a call to the selected phone number.The dialog box has a field displaying the call status:
The MAPI connector allows you to specify Server-side Rules, including the Rules that can store incoming messages in an encrypted form.
You may also want to improve security for certain messages received and stored on the Server in clear-text.Right-click on the selected message in Outlook. A pop-up menu will open:
When you select the Encrypt Message item, the MAPI Connector will send your default Certificate (containing your Public Key) to the Server. The Server will use that Certificate to encrypt the selected message. It will be stored on the Server in the encrypted S/MIME format - as if the message sender has sent it encrypted.
If you want to read Encrypted messages using your MAPI clients (Outlook) and the WebUser Interface, make sure that your Windows desktop system and the WebUser Interface have the same Private Keys and Certificates installed. You can either generate a key and Certificate in the WebUser Interface and then export them to your Windows desktop system, or you can export your keys from the Windows desktop system and import them into your WebUser Interface settings.
The MAPI connector works as a liaison between MAPI applications (such as Microsoft Outlook) and the CommuniGate Pro Server. The problem a user can experience with its client, can be a bug or feature of that client, or a problem in the MAPI Connector or Server software. To help investigate the problem, the MAPI Connector can generate a detailed Log of all operations it was requested to perform. You can examine that Log yourself or send it to CommuniGate Systems technical support.Open the Troubleshooting panel in the MAPI Connector ("CommuniGate Pro Service") setup box:
The panel displays the versions of both MAPI Connector software components: the starter code library installed on your desktop computer and the server code library retrieved from the CommuniGate Pro Server.
Select the Enable Logging option to start MAPI Connector log recording. The MAPI Connector Log keeps only the last records, so the Log file does not exceed the size specified in the Maximum Log File Size setting.
Use the checkbox controls to enable logging for various MAPI Connector components.
Click the Show Me Log File button to open a file directory window the Log file is stored in. You can use this feature to E-mail the Log file to CommuniGate Systems technical support.
Click the Delete Log File to clear the Log file.Use the Compatibility options to tune up the MAPI Connector operation for mixed environments.
The protocols and APIs the MAPI Connector implements are not the Internet standards, but API from the Microsoft® Corporation. Those APIs are not fully documented, and as a result, some minor client (Outlook) functions may be unavailable. CommuniGate Systems is working on solving these problems, and the MAPI Connector updates are released on a regular basis.
The special Known MAPI Problems site lists all reported and known problems and provides the status update on them. Please consult this site first if you have any problem with the MAPI Connector functionality.