OUTBOX: Programming Exchange 2007 Foreign Connectors - The Exchange EDK Gateway Connector Replacement

...We have had a few customers looking for information on writing a custom foreign connector for Exchange 2007 and I finally got around to combining all my information into one document so that I could reuse it. I thought I would share it here as well to maybe save a few calls to our team...

What is a gateway connector?

“Gateway connectors generally use non-standard protocols, or proprietary APIs to connect Exchange to non-Exchange messaging systems” – [TechNet]Gateway Messaging Connectors Architecture

One of the most common examples of a gateway connector is an Exchange fax gateway that many ISVs have implemented for Exchange 2000/2003/2007. These gateway connectors allow a user to send faxes from Exchange clients by sending mail to a special address space like, 8001234567@MyFaxServer.com. Additionally when a fax is received the ISVs product could allow for delivery of the fax through the gateway connector to an Exchange client by converting the inbound fax to a mail message.

There are two key tasks that an Exchange gateway must perform…

Ø Receive outbound messages from Exchange

Ø Send inbound messages to Exchange

What is new in Exchange 2007?

Exchange 2007 does not support the same gateway model that Exchange 2000/2003 used. Rather than using MAPI and watching queues, the Exchange 2007 solution is file system based. To receive outbound messages from Exchange to be sent via the gateway service, you configure a foreign connector on the Hub Transport server which drops messages to a directory which the gateway service monitors. Conversely to send inbound messages from a non-Exchange to Exchange mailboxes the gateway services would create a file in a directory which Exchange monitors.

Receiving outbound messages from Exchange

The gateway service monitors a drop directory on an Exchange Hub Transport server to receive messages sent from Exchange clients that are to be sent via the non-Exchange gateway service. Address spaces which may be SMTP or non-SMTP are configured for each foreign connector to route messages to a particular drop directory.

Foreign connectors are created and configured using Exchange Powershell cmdlets.

“To use the interactive mode of the Exchange Management Shell to create a new Foreign connector

1. At the Exchange Management Shell command prompt, type New-ForeignConnector, and then press ENTER.

2. At the Address Spaces (0): prompt, type the address space to which this connector will send messages, for example, contoso.com, and then press ENTER.

3. Enter additional address spaces if this connector will send messages to more than one domain. After you enter all the address spaces, press ENTER to continue.

4. At the Name: prompt, type a name for this connector, and then press ENTER. The connector summary is displayed. ” – [TechNet] How to Create a New Foreign Connector

Messages dropped in this directory will be in MIME format with TNEF (winmail.dat) attachments. The basic MIME data contains the header fields like TO and CC fields but you will not see the BCC, attachments, and body content. This information and other MAPI data are in the TNEF data which is in the winmail.dat attachment. The Exchange.Data.ContentTypes.TNEF namespace is used to iterate through the TNEF parts and extract the data from the winmail.dat that could be used by the gateway service for routing.

Send inbound messages to Exchange

The gateway service sends messages to Exchange by creating files in a replay directory. These are MIME formatted messages which are created using the new managed Exchange.Data namespaces.

The replay directory is monitored by Exchange. It checks for new messages every 5 seconds (this interval cannot be changed). Once a message is processed the file is renamed from *.eml to *.tmp. After the *.tmp file is converted to an SMTP message the *.tmp file is locked until the message is successfully queued for delivery. If the transport service is restarted then all the *.tmp files are renamed to *.eml and the processing starts over again. Messages dropped to the replay directory have some prerequisites which must be taken into account.

“A message file that is copied into the Replay directory must meet the following requirements for successful delivery:

· The message file must be a text file that complies with the basic SMTP message format. Multipurpose Internet Mail Extensions (MIME) message header fields and content are supported.

· The message file must have an .eml file name extension.

· X-Headers must occur before all regular header fields.

· A blank line must exist between the header fields and the message body.”

What is the difference between the Replay directory and the Pickup directory?

“Exchange Server 2003 uses a single Pickup directory for creating and submitting text message files. Exchange 2007 splits this functionality into separate Pickup and Replay directories. The Pickup directory is intended for users or applications to manually create new message files. The Replay directory is intended for the re-submission of exported Exchange e-mail messages and for receiving messages from non-SMTP connectors. This separation of duties allows for the appropriate security to be applied to one directory without affecting the functionality of the other directory.”

[TechNet] Managing the Replay Directory