Send a Bulk E-mail and Monitor the Job

This sample code shows how to send a bulk e-mail and monitor its progress.

   1:  //# Send a Bulk E-mail and Monitor the Job

   2:  using System;

   3:  using CrmSdk;

   4:  using Microsoft.Crm.Sdk.Utility;

   5:   

   6:  namespace Microsoft.Crm.Sdk.HowTo.BulkOperation

   7:  {

   8:     public class SendBulkEmailAndMonitor

   9:     {

  10:        public SendBulkEmailAndMonitor()

  11:        {

  12:   

  13:        }

  14:   

  15:        public static bool Run(string crmServerUrl, string orgName)

  16:        {

  17:           bool success = false;

  18:   

  19:           try

  20:           {

  21:              // Set up the CRM Service.  

  22:              CrmService service = Microsoft.Crm.Sdk.Utility.CrmServiceUtility.GetCrmService(crmServerUrl, orgName);

  23:              service.PreAuthenticate = true;

  24:   

  25:              // Create some contacts to send a bulk e-mail to.

  26:              // Typically, this would be an existing list of customers, such as a marketing list.

  27:              object[] contactIds = new object[2];

  28:              

  29:              contact emailContact1 = new contact();

  30:              emailContact1.firstname = "Adam";

  31:              emailContact1.lastname = "Carter";

  32:              emailContact1.emailaddress1 = "adam.carter@example.com";

  33:   

  34:              // Create the contact.

  35:              contactIds[0] = service.Create(emailContact1);

  36:              

  37:              contact emailContact2 = new contact();

  38:              emailContact2.firstname = "Adina";

  39:              emailContact2.lastname = "Hagege";

  40:              emailContact2.emailaddress1 = "adina.hagege@example.com";

  41:   

  42:              // Create the contact.

  43:              contactIds[1] = service.Create(emailContact2);

  44:              

  45:              // Create the bulk mail request.

  46:              SendBulkMailRequest bulkMailRequest = new SendBulkMailRequest();

  47:   

  48:              // Create a query expression for the bulk operation to use to retrieve 

  49:              // the contacts in our e-mail list.

  50:              ConditionExpression condition = new ConditionExpression();

  51:              condition.AttributeName = "contactid";

  52:              condition.Operator = ConditionOperator.In;

  53:              condition.Values = contactIds;

  54:   

  55:              FilterExpression filterExpression = new FilterExpression();

  56:              filterExpression.Conditions = new ConditionExpression[] { condition };

  57:   

  58:              ColumnSet returnColumns = new ColumnSet();

  59:              returnColumns.Attributes = new string[] { "contactid" };

  60:   

  61:              QueryExpression queryRequest = new QueryExpression();

  62:              queryRequest.ColumnSet = returnColumns;

  63:              queryRequest.EntityName = EntityName.contact.ToString();

  64:              queryRequest.Criteria = filterExpression;

  65:   

  66:              // Attach the contact query to the bulk e-mail request.

  67:              bulkMailRequest.Query = queryRequest;

  68:   

  69:              // Get a system user to use as the sender.

  70:              bulkMailRequest.Sender = GetEmailSenderMoniker(service);

  71:   

  72:              // Set the RegardingId to the e-mail sender.

  73:              bulkMailRequest.RegardingId = bulkMailRequest.Sender.Id;

  74:              bulkMailRequest.RegardingType = EntityName.systemuser.ToString();

  75:   

  76:              // Use a built-in e-mail template.

  77:              // NOTE: The e-mail template's 'template type' must match the type of customers

  78:              // in the e-mail list. Our list contains contacts, so our template must be for contacts.

  79:              bulkMailRequest.TemplateId = new Guid("07B94C1D-C85F-492F-B120-F0A743C540E6");

  80:   

  81:              // Create a tracking ID for the bulk operation to monitor its progress.

  82:              RequestIdOptionalParameter trackingId = new RequestIdOptionalParameter();

  83:              trackingId.Value = Guid.NewGuid();

  84:              

  85:              // Attach the tracking ID to the bulk e-mail request.

  86:              bulkMailRequest.OptionalParameters = new OptionalParameter[] { trackingId };

  87:   

  88:              // Execute the async bulk e-mail request.

  89:              service.Execute(bulkMailRequest);

  90:              

  91:              // Now that we have executed the bulk operation, we have to retrieve it using our tracking ID.

  92:              ColumnSet asyncColumns = new ColumnSet();

  93:              asyncColumns.Attributes = new string[] { "requestid", "statecode" };

  94:   

  95:              QueryByAttribute bulkQuery = new QueryByAttribute();

  96:              bulkQuery.ColumnSet = asyncColumns;

  97:              bulkQuery.EntityName = EntityName.asyncoperation.ToString();

  98:              bulkQuery.Attributes = new string[] { "requestid" };

  99:              bulkQuery.Values = new object[1];

 100:              bulkQuery.Values[0] = trackingId.Value;

 101:   

 102:              // Retrieve the bulk e-mail async operation.

 103:              BusinessEntityCollection aResponse = service.RetrieveMultiple(bulkQuery);

 104:   

 105:              // Monitor the async operation through polling.

 106:              const int ARBITRARY_MAX_POLLING_TIME = 60;

 107:              int secondsTicker = ARBITRARY_MAX_POLLING_TIME;

 108:   

 109:              asyncoperation createdBulkMailOperation = null;

 110:              

 111:              while (secondsTicker > 0)

 112:              {

 113:                 // Make sure that the async operation was retrieved.

 114:                 if (aResponse.BusinessEntities.Length > 0)

 115:                 {

 116:                    // Grab the one bulk operation that was created.

 117:                    createdBulkMailOperation = (asyncoperation)aResponse.BusinessEntities[0];

 118:   

 119:                    // Check the operation's state.

 120:                    if (createdBulkMailOperation.statecode.Value != AsyncOperationState.Completed)

 121:                    {

 122:                       // The operation has not yet completed.  Wait a second for the status to change.

 123:                       System.Threading.Thread.Sleep(1000);

 124:                       secondsTicker--;

 125:   

 126:                       // Retrieve a fresh version the bulk delete operation.

 127:                       aResponse = service.RetrieveMultiple(bulkQuery);

 128:                    }

 129:                    else

 130:                    {

 131:                       // Stop polling because the operation's state is now completed.

 132:                       secondsTicker = 0;

 133:                    }

 134:                 }

 135:                 else

 136:                 {

 137:                    // Wait a second for the async operation to become active.

 138:                    System.Threading.Thread.Sleep(1000);

 139:                    secondsTicker--;

 140:   

 141:                    // Retrieve the entity again.

 142:                    aResponse = service.RetrieveMultiple(bulkQuery);

 143:                 }

 144:              }

 145:              

 146:              // When the bulk e-mail operation has finished, all sent e-mail messages will have a status of "Pending Send" and 

 147:              // will be picked up by your e-mail router. Or, you can then use BackgroundSendEmail to download

 148:              // all the e-mail messages that were created by using the SendBulkEmail message. See the BackgroundSendEmail sample for an example.

 149:   

 150:              #region check success

 151:              

 152:              // Validate async operation succeeded.

 153:              if (createdBulkMailOperation.statecode.Value == AsyncOperationState.Completed)

 154:              {

 155:                 success = true;

 156:              }

 157:   

 158:              #endregion

 159:   

 160:              #region Remove Data Required for this Sample.

 161:              

 162:              // Delete the sent e-mail messages. 

 163:              ColumnSet sentMailColumns = new ColumnSet();

 164:              sentMailColumns.Attributes = new string[] { "statuscode" };

 165:   

 166:              ConditionExpression statusCondition = new ConditionExpression();

 167:              statusCondition.AttributeName = "statuscode";

 168:              statusCondition.Operator = ConditionOperator.Equal;

 169:              statusCondition.Values = new object[] { EmailStatus.PendingSend };

 170:   

 171:              // Create the query filter.

 172:              FilterExpression emailFilter = new FilterExpression();

 173:              emailFilter.Conditions = new ConditionExpression[] { statusCondition };

 174:              emailFilter.FilterOperator = LogicalOperator.And;

 175:   

 176:              // Query for e-mail activity.

 177:              QueryExpression emailsQuery = new QueryExpression();

 178:              emailsQuery.ColumnSet = sentMailColumns;

 179:              emailsQuery.EntityName = EntityName.email.ToString();

 180:              emailsQuery.Criteria = emailFilter;

 181:   

 182:              // Retrieve the e-mail activity.

 183:              BusinessEntityCollection emails = service.RetrieveMultiple(emailsQuery);

 184:   

 185:              foreach (email sentMail in emails.BusinessEntities)

 186:              {

 187:                 service.Delete(EntityName.email.ToString(), sentMail.activityid.Value);

 188:              }

 189:              

 190:              // Delete the contacts created for e-mails.

 191:              foreach (Guid createdContactId in contactIds)

 192:              {

 193:                 service.Delete(EntityName.contact.ToString(), createdContactId);

 194:              }

 195:   

 196:              #endregion

 197:           }

 198:           catch (System.Web.Services.Protocols.SoapException)

 199:           {

 200:              // Perform error handling here.

 201:              throw;

 202:           }

 203:           catch (Exception)

 204:           {

 205:              throw;

 206:           }

 207:   

 208:           return success;

 209:        }

 210:   

 211:        /// <summary>

 212:        /// Retrieves a systemuser to use as the sender of an e-mail.

 213:        /// </summary>

 214:        /// <param name="service">The CRM service</param>

 215:        /// <returns>Moniker to use as e-mail sender</returns>

 216:        public static Moniker GetEmailSenderMoniker(CrmService service)

 217:        {

 218:           Moniker emailSender = new Moniker();

 219:           

 220:           ColumnSet selectClause = new ColumnSet();

 221:           selectClause.Attributes = new string[] {"fullname"};

 222:           

 223:           QueryExpression allSystemUsersQuery = new QueryExpression();

 224:           allSystemUsersQuery.EntityName = EntityName.systemuser.ToString();

 225:           allSystemUsersQuery.ColumnSet = selectClause;

 226:   

 227:           // Create the query request.

 228:           RetrieveMultipleRequest allSystemUsersRequest = new RetrieveMultipleRequest();

 229:           allSystemUsersRequest.Query = allSystemUsersQuery;

 230:   

 231:           // Execute the request.

 232:           RetrieveMultipleResponse allSystemUsersResponse = (RetrieveMultipleResponse)service.Execute(allSystemUsersRequest);

 233:   

 234:           // Grab a system user for the bulk e-mail.

 235:           if (allSystemUsersResponse.BusinessEntityCollection.BusinessEntities.Length > 0)

 236:           {

 237:              // For demonstration, grab the first system user.

 238:              systemuser emailUser = (systemuser)allSystemUsersResponse.BusinessEntityCollection.BusinessEntities[0];

 239:              emailSender.Id = emailUser.systemuserid.Value;

 240:              emailSender.Name = EntityName.systemuser.ToString();

 241:           }

 242:           else

 243:           {

 244:              // If no system user was found, we cannot continue with bulk e-mail.

 245:              throw (new Exception("No system user found to send e-mail."));

 246:           }

 247:           

 248:           return emailSender;

 249:        }

 250:     }

 251:  }