Rediger

Del via

Email activity entities

  • Artikkel

The email activity lets you track and manage email communications with customers. Dynamics 365 Customer Engagement (on-premises) includes the Email Router software that manages the routing of email to or from Dynamics 365 Customer Engagement (on-premises). The email activity is delivered using email protocols. Email Router supports the following email protocols: Exchange Web services, POP3, and SMTP. In addition to the Email Router software, the email activity can also be delivered by using Dynamics 365 for Outlook.

Actions on an Email Activity

Using Dynamics 365 Customer Engagement Web Services, you can perform the following actions on an email activity:

  • Create, retrieve, update, and delete the email activity.

  • Send email messages, or send email messages by using email templates (Template). For more information about email templates, see Template Entity.

  • Attach files as attachments by using the (ActivityMimeAttachment) attribute in the email message.

  • Send mass or bulk email messages.

  • Configure incoming email messages to be delivered from Microsoft Exchange Server to any user or queue, or outgoing messages to be sent from any user or queue to Microsoft Exchange Server. For information about how to configure incoming email messages for queues, see Configure email for incoming messages.

    If the Organization.RequireApprovalForuserEmail and Organization.RequireApprovalForQueueEmail (process emails only for approved users/queues) organization attributes are set to true (1), the following occurs: email messages are delivered or sent from a user or queue only if the primary email address of the user or queue is approved. The SystemUser.EmailRouterAccessApproval and the Queue.EmailRouterAccessApproval attributes indicate the status of the primary email address of the user and queue respectively, and the value must be set to 1. Otherwise, the incoming and outgoing messages will be blocked. You can update the user or queue record to change the attribute value, if it is not already in the approved state, provided your user account has the prvApproveRejectEmailAddress privilege assigned.

Note

In Dynamics 365 for Customer Engagement, the Email.StatusCode attribute cannot be null.

Bulk Email

Dynamics 365 Customer Engagement (on-premises) supports sending email to a large list of recipients through a bulk email request. When a bulk email request is sent to Dynamics 365 Customer Engagement (on-premises), an asynchronous operation is created in the asynchronous service queue that sends the email messages by using a background process. This gives you improved system performance.

The SendBulkMailRequest and BackgroundSendEmailRequest messages are used for sending bulk email messages. The following lists the sequence used to send bulk email:

  1. Execute the SendBulkMail request. This request contains a query that selects the target email recipients and an email template for composing each email.

  2. The asynchronous service creates the email activities for each recipient.

  3. The asynchronous service sends each email message. The email messages have a "pending" send status.

  4. The email router, Dynamics 365 for Outlook, or a third-party email send component polls Dynamics 365 Customer Engagement (on-premises) for pending email messages, and if one is found, downloads it by using the BackgroundSendEmail request.

  5. The BackgroundSendEmail request performs the following operations: checks if pending email messages are present, downloads the email to the caller of the BackgroundSendEmailRequest message, and synchronizes the downloads if there are multiple callers.

  6. The caller of the BackgroundSendEmailRequest message receives the downloaded email message, and sends it out.

Email Attachments

Email attachments are files that can be attached to email messages or email templates. An attached file can be in any standard computer file format such as Office Word documents, Office Excel spreadsheets, CAD files, and PDF files. You can attach multiple files as email attachments to an email or email template. The maximum size of files that can be uploaded is determined by the Organization.MaxUploadFileSize property. This property is set in the Email tab of the System Settings in the Dynamics 365 application. This setting limits the size of files that can be attached to email messages, notes, and web resources. The default setting is 5 MB.

To attach an email attachment with an email message or template, you use the ActivityMimeAttachment.ObjectId and ActivityMimeAttachment.ObjectTypeCode attributes while you are creating or updating an activity mime attachment record.

The following code sample shows how to attach an email attachment to an email:

ActivityMimeAttachment _sampleAttachment = new ActivityMimeAttachment{  
    ObjectId = new EntityReference(Email.EntityLogicalName, _emailId),  
    ObjectTypeCode = Email.EntityLogicalName,  
    Subject = "Sample Attachment”,  
    Body = System.Convert.ToBase64String(new ASCIIEncoding().GetBytes("Example Attachment")),  
    FileName = "ExampleAttachment.txt"};

Similarly, to attach the email attachment to a template instead of an email, you will replace the values of the ActivityMimeAttachment.ObjectId and ActivityMimeAttachment.ObjectTypeCode attributes as follows in the above code:

ObjectId = new EntityReference(Template.EntityLogicalName, _templateId), ObjectTypeCode = Template.EntityLogicalName,

For complete code sample about how to create email attachments, see Sample: Create, Retrieve, Update, and Delete an E-Mail Attachment.

Reusing Email Attachments

When you create an email attachment record, the attached file is saved as a file BLOB. The ActivityMimeAttachment.AttachmentId attribute of the email attachment record uniquely identifies the file BLOB. This is done to facilitate the reuse of the file attachments with other email and email template records, without creating and storing multiple copies of the same file in the database.

To reuse an existing file attachment:

  1. Retrieve the ActivityMimeAttachment record that contains the attachment file that you want to re-use, as shown in the following code example:

    ActivityMimeAttachment retrievedAttachment = (ActivityMimeAttachment)_serviceProxy.Retrieve(ActivityMimeAttachment.EntityLogicalName, _emailAttachmentId, new ColumnSet(true));

  2. Create a new email attachment record, associate it with the required email or email template record, and point it to the attached file of the retrieved ActivityMimeAttachment record, as shown in the following code example:

    ActivityMimeAttachment _reuseAttachment = new ActivityMimeAttachment{  
    ObjectId = new EntityReference(Email.EntityLogicalName, _emailId),  
    ObjectTypeCode = Email.EntityLogicalName,  
    Subject = "Sample Attachment”,  
    AttachmentId = retrievedAttachment.AttachmentId};

    Because you are reusing an existing attachment file, you do not have to specify the ActivityMimeAttachment.Body and ActivityMimeAttachment.FileName attribute values while you are creating and associating email attachment records to emails or email templates.

See also

Activity Entities
Sample code for activity entities
Email Entity
ActivityMimeAttachment Entity