This documentation is archived and is not being maintained.

Bulk E-mail

banner art

[Applies to: Microsoft Dynamics CRM 4.0]

Find the latest SDK documentation: CRM 2015 SDK

Microsoft Dynamics CRM supports sending e-mail to a large list of recipients through a bulk e-mail request. When a bulk e-mail request is sent to the Microsoft Dynamics CRM platform by a Web service call, an asynchronous operation is created in the asynchronous service queue that sends out the e-mail messages by using a background process. This results in improved system performance.

The key messages for sending bulk e-mail are SendBulkEmail and BackgroundSendEmail. These messages send bulk e-mail as outlined in the following list:

  1. A SendBulkMail request is issued to the CrmService Web service. This request contains a query that selects the target e-mail recipients and an e-mail template for composing each e-mail.
  2. The asynchronous service creates the e-mail activities for each recipient.
  3. The asynchronous service sends each e-mail. The e-mail messages now have a "pending" send status.
  4. The e-mail router, Microsoft Dynamics for Microsoft Office Outlook, or a third-party e-mail send component polls the Microsoft Dynamics CRM server for pending e-mail messages and if one is found downloads it by using the BackgroundSendEmail request.
  5. The BackgroundSendEmail request performs the following operations: checks if pending e-mail messages are present, downloads the e-mail to the caller of BackgroundSendEmail, and synchronizes the downloads if there are multiple callers.
  6. The caller of BackgroundSendEmail receives the downloaded e-mail and sends it out.


The following code shows you how to directly send e-mail by using the BackgroundSendEmail message. The code sample assumes that an e-mail activity with a recipient list and a subject of "SDK Sample Email" exists in the database. The complete code sample can be found in the SDK samples folder SDK\Server\Reference.

// Query for e-mail activity to send.
QueryByAttribute allEmailsQuery = new QueryByAttribute();
// Be aware that retrieving all columns (attributes) may adversely affect
// performance and cause unwanted cascading in subsequent 
// updates. A best practice is to retrieve the least amount of 
// data required.
allEmailsQuery.ColumnSet = new AllColumns();
allEmailsQuery.EntityName =;
allEmailsQuery.Attributes = new string[] { "subject" };
allEmailsQuery.Values = new string[] { "SDK Sample Email" };

// Retrieve the e-mail activity.
BusinessEntityCollection emails = service.RetrieveMultiple(allEmailsQuery);

// Create the request.
BackgroundSendEmailRequest bkgrndSendEmailRequest = new BackgroundSendEmailRequest();

// Set the request properties.
bkgrndSendEmailRequest.Query = allEmailsQuery;
RequestIdOptionalParameter  trackingParam = new RequestIdOptionalParameter();
trackingParam.Value = Guid.NewGuid();
bkgrndSendEmailRequest.OptionalParameters = new OptionalParameter[] { trackingParam };

// Execute the request.
BackgroundSendEmailResponse bkgrndSendEmailResponse = (BackgroundSendEmailResponse)service.Execute(bkgrndSendEmailRequest);

See Also


© 2010 Microsoft Corporation. All rights reserved.