• Article

Tell Those Messages Where to Go By Using Exchange 2007 SP1 Transport Agents

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Topic Last Modified: 2007-11-29

By Ray Dixon, Programming Writer

Do you want to control where messages are routed on a per-recipient basis? Do you want to control that routing from your own transport agent? Maybe you want to change the routing for certain recipients in an SMTP domain, but not for all the recipients in that domain. With the release of Microsoft Exchange Server 2007 Service Pack 1 (SP1), you can!

Requirements for Routing

To programmatically override the default routing for message recipients, the following are required:

  • A computer that is running Exchange 2007 SP1 that has the Hub Transport server role installed.
  • For each domain that you use to override the default routing, a send connector that has an address space that matches the domain that you specify when you override the default routing. The send connector must be created on each Hub Transport server on which you install your agent.
  • An agent that is derived from the RoutingAgent class. The agent must be installed on each Hub Transport server on which you plan to process messages for possible rerouting.

Overriding the Default Routing

Exchange 2007 SP1 includes the OnResolvedMessage event in the RoutingAgent class. The OnResolvedMessage event occurs after the OnSubmittedMessage event finishes and before the OnRoutedMessage event occurs. This event enables you to read recipient information for each recipient of the resolved message.

Note

An attempt to call SetRoutingOverride before or after the OnResolvedMessage event will cause an exception. You can only use SetRoutingOverride in your event handler for the OnResolvedMessage event and not in the OnSubmittedMessage or OnRoutedMessage events.

You can change the default routing behavior for the message on a per-recipient basis in the OnResolvedMessage event. You do this by using the SetRoutingOverride method on the recipient for which you want to override the default routing. When you call the SetRoutingOverride method, you specify the domain that you want the message routed to by using the RoutingDomain structure. The following code example shows you how to override the routing domain.

void OnResolvedMessageHandler(ResolvedMessageEventSource source, QueuedMessageEventArgs e)
{
    RoutingDomain myRoutingOverride = new RoutingDomain("contoso.com");
    e.MailItem.Recipients[0].SetRoutingOverride(myRoutingOverride);
}

This example specifies that you want Exchange to route the message for the first recipient by using the send connector for the domain contoso.com. It's that simple! Next, the Exchange server will route the message based on the settings of the send connector with the contoso.com address space.

When you call the SetRoutingOverride method, the RoutingOverride property of the message is set to the RoutingDomain that you specify in the SetRoutingOverride method. The Exchange server will then use the send connector for the specified routing domain to determine routing.

Resetting the Routing Override

To reset the routing for the message back to the default routing, call the SetRoutingOverride method by using the RoutingDomain.Empty field. The following code example shows you how to reset the routing override.

    e.MailItem.Recipients[0].SetRoutingOverride(RoutingOverride.Empty);

Troubleshooting Routing

As you can see, it is easy to change the routing for a message to a specific recipient. Suppose you want to troubleshoot your agent — what do you do? You check the event logs and the queue viewer, of course!

Event Logs

Exchange 2007 SP1 logs an event when an agent changes the RoutingDomain property for a message in an attempt to override routing behavior. The following are the properties and values for those events:

Source: AGENT

EventId: REDIRECT

MessageInfo: <RoutingDomainType:RoutingDomainValue>

Queue Viewer

The Queue Viewer displays information about queued messages and messages for which the domain is unreachable. In Queue Viewer, you see recipient information for messages for which routing has been overridden, including the following:

  • The recipient's primary SMTP address
  • The recipient type
  • The final destination for the message
  • The last error that occurred when an attempt was made to route the message

You can use this information to determine why a message is stuck in a delivery queue. The message will appear in the unreachable queue if the RoutingDomain that is specified for the message does not match the address space of a send connector on the Exchange server that is trying to route the message.

Go Re-Route Some Messages

Now that you know about the new routing override capabilities for agents in Exchange 2007 SP1, try them out. Maybe you want to save messages that are destined for certain recipients to a drop folder so that a foreign system can pick them up. Perhaps you must have a way to route all message for some recipients through a nondefault send connector to get those messages to a mail server that processes messages in a special way. Maybe you just like telling those messages where you want them to go. Whether you are doing any of these or have some other reason to override the default routing for recipients, it's time to give it a try!