Email activity entities

Мақала
11/28/2016

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

The email activity lets you track and manage email communications with customers. Microsoft Dynamics 365 includes the Email Router software that manages the routing of email to or from Microsoft Dynamics 365. 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 Microsoft Dynamics 365 for Outlook.

In This Topic

Actions on an Email Activity

Bulk Email

Email Attachments

Actions on an Email Activity

Using Microsoft Dynamics 365 SDK, 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 (email template) entity messages and methods.
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. For more information, see Security role UI to privilege mapping.

Note

In Microsoft Dynamics 365 (online & on-premises), the Email.StatusCode attribute cannot be null.

Bulk Email

Microsoft Dynamics 365 supports sending email to a large list of recipients through a bulk email request. When a bulk email request is sent to Microsoft Dynamics 365, 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:

Execute the SendBulkMail request. This request contains a query that selects the target email recipients and an email template for composing each email.
The asynchronous service creates the email activities for each recipient.
The asynchronous service sends each email message. The email messages have a "pending" send status.
The email router, Microsoft Dynamics 365 for Outlook, or a third-party email send component polls Microsoft Dynamics 365 for pending email messages, and if one is found, downloads it by using the BackgroundSendEmail request.
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.
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 Microsoft Office Word documents, Microsoft 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 email 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:

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));

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.

Бөлісу құралы:

Email activity entities

In This Topic

Actions on an Email Activity

Bulk Email

Email Attachments

Reusing Email Attachments

See Also

Қосымша ресурстар