The DeliverIncomingEmail message is one of those gems.  Let’s take a look:

What does it do?

First and foremost, it takes information that exists within an email message that you retrieved from somewhere and creates a CRM Email Activity. This process could be a custom application you wrote, or in my case, a Simple Email Router.  Regardless of where the email comes from, this message will do all of the heavy lifting required to create the Email Activity.

Usage:

DeliverIncomingEmailRequest request = new DeliverIncomingEmailRequest
{
    Subject = subject,
    From = from,
    To = to,
    Cc = cc,
    Bcc = bcc,
    MessageId = Guid.NewGuid().ToString(),
    ReceivedOn = CrmTypes.CreateCrmDateTimeFromUser(timeReceived),
    Body = body,
    SubmittedBy = to,
    Importance = "Normal",
    Attachments = new BusinessEntityCollection()
};

request.Attachments.EntityName = EntityName.activitymimeattachment.ToString();
request.Attachments.BusinessEntities.Add(new activitymimeattachment());

How It Works

You complete the parameters of the message with information from the inbound email; things like To, From, Subject, Body, etc. the use the CrmService.Execute method to deliver the mail.  That’s it.

Caveats

MessageId is a Guid that can be either the ID of the message or a new Guid you supply.

Attachments are required, even if you don’t have attachments.  In the example above, we have created a BusinessEntityCollection to hold our attachments, but never actually added any.  This will keep the Message from failing to process.

To, Cc, Bcc can contain multiple email addresses that are separated by a comma ( , ).

So why is this such a big deal?

Did you notice that we are only supplying the email addresses of the people involved in the conversation?  When CRM processes this message, it will perform an automatic lookup and attempt to associate people with those email addresses.

This is actually one of the few messages within the CRM SDK that doesn’t require an ID to perform a lookup or an association and saves you, the developer, a tremendous amount of time and effort.

A Bit of Background

In the next few weeks, sometime before Convergence 2010, I’ll be launching a new online training service for CRM users.  This is a totally Online-based solution using the Microsoft Online stack including:

• CRM Online
• Business Productivity Online Suite ( BPOS )
• Windows Azure

The only drawback to using CRM Online is you must install the CRM Email Router on a computer somewhere to move email into and out of CRM Online.  Since I wanted everything in a data center not run by me, I decided to spend a little time and effort to create a very simplistic replacement for the Email Router.

Email Router Architecture

At its heart, the Email Router really only does two things:

1. Check CRM for unsent messages, sending any it finds
2. Check a mailbox for new messages, retrieving and inserting into CRM any it finds

That didn’t seem to be too hard of a process to replicate especially since, in all reality, I only had one CRM user to monitor.

Software Components

To help me send and receive email, I selected the Chilkat Email .NET Component.  It’s quite affordable and has a whole host of useful features.

Everything else was written using the CRM SDK.

The code resides inside a Windows Azure Worker Role and I poll CRM and the Exchange Online mailbox a few times a minute ( again, this is not a high-production environment ).

Sending Email

So how do you determine what email needs to get sent?  It’s pretty simple actually:  You just query the Email entity and look for emails with a statuscode attribute for a value of 6, which is PendingSend.

Again, I don’t have complicated requirements so I’m only interested in retrieving the TO, Subject, and Description from the email.  If my needs develop, I can always add additional functionality to handle scenarios like:

• Multiple recipients
• Attachments
• Multiple users ( From address )

Once I have collected all of the emails to be sent, I connect to Exchange Online, send the emails, then set the status of the email to Sent

Receiving Email

Collecting incoming email is a very similar process.  Here’s how it works:

1. I connect to my Exchange Online mailbox using POP3 and retrieve all of the unread email.
2. Looping through each email, I use the SDK method, DeliverIncomingEmailRequest, to actually deliver the email to CRM.
3. After successful delivery, I delete the email from the Exchange Online mailbox.

Conclusion

Well, that’s about it.  Like I mentioned numerous times: my needs were very simplistic, but as you can see, it’s not rocket science, and the process can be enhanced and extended to suit your needs.

So I’m testing one of my CRM add-ons which involves sending an email to an email-enabled CRM queue.

I’m sending an email with an XML packet in the email body.  Unfortunately, Outlook keeps hard-wrapping the text by inserting carriage-returns which end up breaking the XML into fragments.

Fortunately, Slipstick Systems came to my rescue, as always ( anything Outlook/Exchange-related ).

Anyway, I found a reference to a KB article that mentions how to make Outlook “not wrap� plain text emails going out over the Internet.

Perfect!

Other than having to change the Registry Key mentioned in the KB article to:

HKEY_CURRENT_USER\Software\Microsoft\Office\12.0

instead of Office\11.0 ( for Outlook 2003 ), everything worked and I can get back to testing.

We had an issue with the second CRM server, which just went into production, where inbound mail wasn't being sent to CRM.  Looking at the forwarding mailbox, we found that all of the mail had ended up in the Undeliverable folder.  After a couple of hours of troubleshooting and searching the web, I found this article from Guenter that provided the solution to our issue.

It turns out the CRM Email Router service was running under the security context of a user called CRMMail.  We had to add that user to the PrivUserGroup security group for the second CRM server so that it would accept the forwarded email.

Michael Lu has a really cool video showing how to configure the CRM 4.0 email router to use a POP3 account.