MAPI Connector

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:

/i	install or upgrade the MAPI connector
/r	remove the MAPI connector
/q	do not ask for profile configuration
/Q	do not display error messages

You may want to use the silent mode to install or upgrade the MAPI Connector starter code part on many workstation, using the Windows network administration methods and tools.

To set the language of the MAPI-Connector interface the cgmxp32.ini file can be used. Place it into the same directory where the setup.exe installer resides.

During installation process the file will be copied to the C:\Windows directory (if MAPI-Connector was installed earlier, you can do this manually).

The language of the MAPI-Connector interface will be set according to the OS localization.

To automate MAPI-Connector configuration the cgmxui32.inf file can be used. Modify this file to fit your needs (the description of the settings is within the file), then place it into the same directory where the setup.exe installer resides.

During installation process the file will be copied to the C:\Windows directory (if MAPI-Connector has been installed earlier, you can do this manually).

To create an Outlook profile with the predefined MAPI-Connector settings run command prompt as Administrator and execute the following command:

regsvr32.exe cgmxui32.dll /i:16

For Outlook 32-bit cgmxui32.dll resides in C:\Windows\SysWOW64

For Outlook 64-bit cgmxui32.dll resides in C:\Windows\System32

As the result, the Outlook profile with the name username_CGATE (where username is the name of the currently logged in user) will be created with the predefined MAPI-Connector settings.

If, as the result of the command execution, an error message appears, make sure, that the command is run as Administrator, and the cgmxp32.inf file exists in the C:\Windows directory.

Alternative way not requiring Administrator rights:

Run ex2cgp, matching Outlook bitness, with the following parameters:

ex2cgp.exe profileonly full_path_to_cgmxui32.inf

If you need the created profile to be set as default, add "default " in the end.

Example:

ex2cgp.exe profileonly C:\Users\Bob\cgmxui32.inf default

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.

Server

The Server panel allows you to specify the CommuniGate Pro Server and Account data:

Server Name

The name of your CommuniGate Pro Server. This should be a domain (DNS) name that has an A-record pointing to the network (IP) address of the server.
Note: the MAPI Connector adds this name to the Account Name (see below) to send fully-qualified account names to the Server. This feature simplifies multi-domain support using a single IP address. Make sure that the specified name is either a name of some CommuniGate Pro Domain, or a name of some CommuniGate Pro Domain Alias, otherwise the Server will report the account has been moved to a remote system error.

Server Port

The network port the CommuniGate Pro Server uses for MAPI clients. This is the same port as the port used for IMAP clients.

Use a Secure (SSL/TLS) connection

If this option is selected, the MAPI Connector establishes a regular (clear text) network connection to the specified Server port, and uses the STARTTLS command to encrypt all data sent between the workstation and the Server. STARTTLS allows you to use the same server IMAP port for both clear text and secure connections.
If this option is selected, and the specified Server Port is 993 (the standard port number for secure IMAP), then the MAPI Connector establishes a secure connection to that port. This method should be used if the only port available on the server is the secure IMAP port.
See the PKI section for more details.

Use Windows Integrated Authentication (Kerberos)

Select this option if your Windows workstation is a member of a Windows/Active Directory Domain or is controlled by some other Kerberos KDC. The MAPI Connector will use your Windows username and credentials to connect to the CommuniGate Pro server.
If you want to use this option, make sure that:

• Your CommuniGate Pro Account has the Kerberos Authentication method enabled.
• Your CommuniGate Pro Domain has the proper Kerberos Keys exported from the Active Directory or Kerberos KDC.

Use the Following Authentication details

Select this option if you want to specify the Account name explicitly.

Account Name

The name of the CommuniGate Pro Account to work with. This name can be a qualified name in the accountName@domainName form. If the simple name form is used (the name does not contain the @ symbol), the MAPI Connector adds the Server Name setting value to the specified account name.

Password

The password for the specified CommuniGate Pro Account.

Remember Password

If this option is not selected, the MAPI Connector will present a Login dialog box every time it needs to connect to the Server. If this option is selected, the supplied password is stored in the MAPI Connector settings data.

Use Secure Authentication

If this option is selected, the MAPI Connector sends passwords using secure (encoded) SASL CRAM-MD5 method. The secure method does not work if passwords are stored on the Server using a one-way encrypted method (see the Security section for more details). In this case this option should be disabled, and the MAPI Connector will send passwords in clear text.
Note: if you need to send passwords in clear text while connecting to the Server via public networks, enable the Use a Secure connection option, so all information is encrypted.

Account Settings

The Account Settings dialog box can be opened by pressing the Account Settings button on the Server panel. The box allows you to specify the MAPI Account name and other general data:

Connection

The Connection panel allows you to select your network connection method.

Offline

When working in the Offline mode (without a server connection, and using the local message cache only), you may want to tell the Connector to start in the Offline mode.
This will eliminate connection attempts on startup (to avoid bringing up your modem, for example).

Advanced

The Advanced panel allows you to specify other CommuniGate Pro Accounts you want to work with.

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.

Include all folders in Send/Receive operation

Use this option to select all the account folders for download, regardless the selection in Outlook -> Tools -> Options -> CommuniGate Pro.

Always download entire message

With this option checked the Connector will download the entire message bodies (versus Headers Only).

Use the Cache files root folder settings to specify where the MAPI Connector should store its local cache. The local cache is used for most MAPI Connector operations, it also allows you to use the MAPI applications (such as Outlook) in the off-line mode.

Local Outlook Application Data folder

Use this option to store the cache files in the default location on your workstation. The cache file will be available on this workstation only.

Global Outlook Application Data folder

Use this option is you use Windows roaming features and plan to use your Outlook application from several workstations.
Note: the cache files can be quite large (they may even store a complete copy of all your server-based Mailbox data, depending on the Connector settings). If the cache file becomes large, you can experience delays when you are logging into the workstation, as the workstation needs to copy all roaming data.

Custom

Use this option if you want to store the cache files in a custom location. For example, you may want to choose a shared folder on a file server to avoid delays caused by roaming.

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.

Posting Free/Busy Information

The MAPI Connector stores your Free/Busy information in your Account File Storage.
Publicly available information in the standard vCalendar format is stored as the freebusy.vfb file in the topmost directory of your 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

Accessing Free/Busy Information for Other Users

In order to process Appointments and Meetings, the Outlook application on the client machine should be able to access the Free/Busy information of other users. This operation is implemented via the MAPI Connector, but also may be done by the Outlook application itself. To configure your Outlook application:

• Select Options from the Tools menu to open the Options dialog box.
• Click the Calendar Options button to open the Calendar Options dialog box.
• Click the Free/Busy Options button to open the Free/Busy Options dialog box.
• Enter the http://%SERVER%/~%NAME%/freebusy.vfb URL string into the Search field. (read all the notes below).
• Click the OK buttons to close all dialog boxes.

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 john@myserver.dom 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:

Note: the suggested Search URL will work only if your CommuniGate Pro Domains have names that have A-records pointing to the CommuniGate Pro server. Often, the DNS system does not contain any A-record for your mydomain.dom Domains, or those records point to a different system (company Web server), while the CommuniGate Pro Server addresses are specified as mail.mydomain.com, or cgate.mydomain.com, or mx.mydomain.com or similar DNS A-record(s). In this case the Search URL must be modified to use the proper domain names:

Note: if your CommuniGate Pro server is serving only one Domain, then you can specify the Search URL as:

where mail.mydomain.com is the name of the CommuniGate Pro Domain or its alias. This should be a name of a DNS A-record pointing to the CommuniGate Pro Server.

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).

Mark to Download Message(s)

The messages selected in the Outlook Mailbox view will be marked so their full bodies are downloaded during the next Send/Receive operation.

Mark to Delete Message(s)

The messages selected in the Outlook Mailbox view will be marked so they will be removed from the Server storage during the next Send/Receive operation.

Unmark Selected Headers

Cancels the pending off-line operations for the messages selected in the Outlook Mailbox view.

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.

Outlook users that work with Exchange servers may have problems sending meeting requests to your users working with the CommuniGate Pro MAPI Connector. Meeting requests sent via an Exchange server may come in as plain text messages instead. The Exchange users should adjust the configuration of their Outlook applications:

Using Outlook Tools menu, Exchange users should open the Options dialog box. After they click the Calendaring Options button, the dialog box appears and they should enable the Send meeting requests using iCalendar by default option.

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.

Send in Outlook native message format

In some rare cases special messages (such as Task requests or forwarded Contacts) sent via the MAPI Connector in the Internet format may be interpreted incorrectly by Outlook Exchange (or Outlook IMAP) users. Checking this option may help to solve the problem.

Send in Outlook 2000 compatible format

Older versions of Outlook may have problems interpreting Calendar and Contact items in the format used by newer versions of Outlook. Check this option to use older format for these items.

Send in Exchange 5.5 compatible format

Meeting requests in formats used by newer versions of Outlook may be incorrectly interpreted by Exchange 5.5 servers. Check this option if any of your correspondents use this version of Exchange server and have problems accepting your meeting requests.

Conservative mass deletion

In some configuration the Outlook Autoarchive function may remove messages in large portions. To avoid this problem, select this option.

Always convert RTF to HTML

Selecting this option causes the text/rtf MIME parts in outgoing messages to be converted to HTML, which is understood by the larger number of mail client applications.

Do not display "Server transaction in progress..." dialog

During long server transactions the Connector displays a progress indicator window. If you don't want that select this option.

Show reports in Outlook native format

Outlook can use a special form to display non delivery notification messages, which provides interface for re-sending of the failed messages. For this feature to work correctly the non-delivery report should contain the full body of the failed message, which is not always the case.

Do not respond to requests for read receipts

The sender of a message may request a receipt to be sent back to him when you open a message for reading. To ignore such requests select this option.

No history uploads for large messages

To fulfill Outlook requests to set some extended property on a message the MAPI connector may re-upload modified message back to the server. This may take quite a while for large messages. To disable this kind of activity check this option.

Erase messages immediately, do not mark for deletion

To increase performance, by default messages are not removed immediately but rather are marked for deletion and removed physically when the folder containing them is closed. If the folder is accessed by several clients simultaneously, these items marked for deletion may still appear in those clients and confuse users. To avoid that you can check this option.

Refresh connection every minute

Some NAT and anti-virus/spam firewalls are very aggressive in terminating TCP connections which they assume to be idle. Closing IMAP sessions this way on the TCP level may confuse Outlook. With this option checked, the MAPI Connector will produce some minimal data exchange on the connection to the CommuniGate pro server, so that connection does not appear idle to the firewall.

Restrict search to downloaded items only

Searching through some message attributes may require downloading items to the client. This may take quite a while for large message store. With this option checked only those items that were previously cached by the MAPI Connector will be searched.

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.