Comprehensive Guide to Integrating Microsoft CRM Online with Dotdigital Using Web API

If you're looking to supercharge your email marketing game while leveraging your CRM data, you're in the right place. I've spent countless hours working with both Microsoft Dynamics 365 and Dotdigital, and today I'll walk you through connecting these powerful platforms to create automated, personalized email campaigns that actually work.

The Big Picture: Why Bother with This Integration?

Before we dive into the technical stuff, let's talk about why you might want to connect these systems in the first place. Picture this: a potential customer fills out a form on your website, their information automatically flows into your CRM, and based on their interests, they immediately receive a perfectly timed, personalized email campaign. No manual intervention needed. Sound good? That's just scratching the surface.

Here's what you can achieve:

• Trigger emails automatically based on what's happening in your CRM
• Use all that rich CRM data to personalize your messages
• Track how your campaigns are performing right in Dotdigital
• Say goodbye to copying and pasting contact information

Getting Your Ducks in a Row

Before we start coding, you'll need:

• Admin access to Dynamics 365 (with permission to customize)
• A Dotdigital account with API access enabled
• Your API credentials from Dotdigital
• Visual Studio (or your preferred IDE if you're not a VS fan)

Setting Up Dotdigital (The Easy Part)

First things first - let's get Dotdigital ready for integration:

1. Head over to your Dotdigital account and navigate to Settings > Access > API Users
2. Create a new API user (give them a name that makes sense, like "CRM Integration")
3. Save that API key somewhere safe - you'll need it soon

•  Design an Email Template

1. Go to Campaigns > Create Campaign in Dotdigital.
2. Select a template or create a custom design.
3. Add placeholders for dynamic data, such as:
   • {{FirstName}}
   • {{LastName}}
   • {{ApprovalDate}}
4. Save the campaign and note its Campaign Name and Campaign ID.

---

Preparing Dynamics 365

Now for the CRM side of things. We need to add a couple of custom fields to track contact status and approval dates:

• Status (Option Set): Values like Pending, Approved, Rejected.
• Approval Date (DateTime): Auto-populated when status changes to Approved.

The Fun Part: Building the Integration

Here's where things get interesting. We're going to create a plugin that springs into action whenever a contact's status changes to "Approved." First, let's set up our configuration:

<configuration>
  <appSettings>
    <add key="DotdigitalApiKey" value="YourAPIKeyHere" />
    <add key="DotdigitalEndpoint" value="https://api.dotdigital.com/v2/" />
  </appSettings>
</configuration>

---

Overview

When a contact’s status changes to "Approved," a CRM plugin will:

1. Pass the campaign name to the Dotdigital API.
2. Verify if the campaign exists.
3. If the campaign is available, send a personalized email.

Plugin Development

Step 1: Register a Plugin on Status Change

Use the Dynamics 365 Plugin Registration Tool to register a plugin on the Update event of the Contact entity. Ensure it listens specifically for changes to the Status field.

Step 2: Develop the Plugin

Now for the meat of our integration - the plugin that handles the status change:

public class ContactApprovalPlugin : IPlugin
{
    public void Execute(IServiceProvider serviceProvider)
    {
        var context = (IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));
        var service = ((IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory)))
            .CreateOrganizationService(context.UserId);

        if (context.InputParameters.Contains("Target") && 
            context.InputParameters["Target"] is Entity entity && 
            entity.LogicalName == "contact")
        {
            var status = entity.GetAttributeValue("statuscode")?.Value;

            if (status == 100000000) // "Approved" status
            {
                var email = entity.GetAttributeValue("emailaddress1");
                var firstName = entity.GetAttributeValue("firstname");
                var lastName = entity.GetAttributeValue("lastname");

                var dotdigitalService = new DotdigitalService();
                
                // Always verify the campaign exists before trying to send
                if (dotdigitalService.CheckCampaignExists("Approval Campaign"))
                {
                    dotdigitalService.SendEmailCampaign(
                        "Approval Campaign", 
                        email, 
                        firstName, 
                        lastName
                    );
                }
            }
        }
    }
}

Step 3: Add Helper Methods for API Calls

To make our lives easier, I've created some helper methods for working with the Dotdigital API:

public class DotdigitalService

{
    public bool CheckCampaignExists(string campaignName)
    {
        using (var client = GetDotdigitalClient())
        {
            var response = client.GetAsync("campaigns").Result;
            response.EnsureSuccessStatusCode();

            var campaigns = JsonConvert.DeserializeObject<List<Campaign>>(
                response.Content.ReadAsStringAsync().Result
            );
            
            return campaigns.Any(c => c.Name.Equals(
                campaignName, 
                StringComparison.OrdinalIgnoreCase
            ));
        }
    }

    public void SendEmailCampaign(string campaignName, string email, 
        string firstName, string lastName)
    {
        using (var client = GetDotdigitalClient())
        {
            var payload = new
            {
                campaignName,
                contacts = new[]
                {
                    new { 
                        email, 
                        firstname = firstName, 
                        lastname = lastName 
                    }
                }
            };

            var response = client.PostAsync(
                "campaigns/send",
                new StringContent(
                    JsonConvert.SerializeObject(payload),
                    Encoding.UTF8,
                    "application/json"
                )
            ).Result;

            response.EnsureSuccessStatusCode();
        }
    }
}

---

Testing Your Integration

Before you roll this out to production, here's how to test it:

1. Create a test contact in your CRM
2. Set their status to "Pending"
3. Change the status to "Approved"
4. Watch your plugin trace logs
5. Check your test email inbox

If everything's working, you should see an email arrive almost instantly!

Common Gotchas and How to Avoid Them

After implementing this dozens of times, here are the issues I see most often:

1. API Key Issues: Double-check your API key - it's always the first thing to verify
2. Campaign Names: Make sure your campaign names match exactly
3. Missing Contact Data: Validate required fields before trying to send
4. Plugin Timing: Register your plugin on the right step (Post-Operation)

Pro Tips for Production

Want to take this to the next level? Here are some battle-tested recommendations:

1. Store Secrets Properly: Move those API keys to Azure Key Vault
2. Add Retry Logic: Network calls can fail - handle them gracefully
3. Log Everything: You'll thank yourself later when troubleshooting
4. Monitor Performance: Keep an eye on those API call response times

Additional Use Cases

Multi-Step Campaigns:

Trigger a series of emails based on different contact events, such as registration, purchase, or feedback submission.

Dynamic Campaign Selection:

Retrieve campaign names dynamically from the Campaign Configuration table in Dynamics 365.

---

Best Practices

1. Monitor Campaign Metrics:
   • Regularly review Dotdigital analytics for performance insights.
2. Optimize Data Handling:
   • Minimize unnecessary API calls by validating data in CRM before invoking Dotdigital.
3. Test Thoroughly:
   • Use a sandbox environment for testing plugins and workflows before deploying to production.

---

Wrapping Up

Connecting Microsoft CRM Online with Dotdigital might seem daunting at first, but it's worth the effort. You're not just saving time - you're creating a more responsive, personalized experience for your customers.

Have questions about the integration? Drop them in the comments below or reach out to me directly. I'd love to hear how you're using this setup in your own projects!

For further assistance, refer to the official documentation for Microsoft Dynamics 365 and Dotdigital API.