Email activity tables

The email activity table helps you track and manage email communications with customers.

Actions on an email activity

By using Dataverse 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 Create email templates.

• 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.

  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 are blocked. You can update the user or queue record to change the attribute value, if it isn't already in the approved state, provided your user account has the prvApproveRejectEmailAddress privilege assigned.

Bulk email

Dataverse supports sending email to a large list of recipients through a bulk email request. When you send a bulk email request to Dataverse, it creates an asynchronous operation in the asynchronous service queue that sends the email messages by using a background process. This process improves system performance.

Use the SendBulkMailRequest and BackgroundSendEmailRequest messages to send bulk email messages. The following list describes 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 Dataverse for pending email messages. If it finds one, it downloads the message 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.

   Note

   Your email service provider might have limits that affect how many emails you can send within a period of time. For more information, see Exchange Online limits > Sending limits.

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

Email attachments

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

To attach an email attachment with an email message or template, use the ActivityMimeAttachment.ObjectId and ActivityMimeAttachment.ObjectTypeCode columns while you're creating or updating an activity mime attachment row.

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, replace the values of the ActivityMimeAttachment.ObjectId and ActivityMimeAttachment.ObjectTypeCode attributes as follows in the preceding code:

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

For a 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, Dataverse saves the attached file as a file BLOB. The ActivityMimeAttachment.AttachmentId attribute of the email attachment record uniquely identifies the file BLOB. This process facilitates the reuse of 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 row that contains the attachment file that you want to reuse, as shown in the following code example:

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

2. Create a new email attachment, associate it with the required email or email template row, and point it to the attached file of the retrieved ActivityMimeAttachment row, 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're reusing an existing attachment file, you don't have to specify the ActivityMimeAttachment.Body and ActivityMimeAttachment.FileName column values while you're creating and associating email attachment rows to emails or email templates.

Email storage

Email descriptions (body of the email) have up to this point been stored in the Dataverse relational store. That is changing as the Email.Description column in the email activity table is being relocated to unstructured Azure Blob storage. Azure Blob storage is also used for storage of attachments, annotations, files, and images.

Transition period

The data migration from Dataverse relation store to Azure Blob storage for all customers is expected to start in May 2023. This data migration will take place as a background process (job). The initial data movement for existing customers is expected to last for about 6 to 12 weeks, and possibly even longer depending on the size of the data. After the initial data movement, any remaining migration is a continuous process. All email descriptions older than twelve months will be moved into Azure Blob storage automatically, and this twelve month transition period cannot be changed. Newer emails will not be moved until they become 12 months old. The email description migration job runs periodically - about once every 30-60 days per tenant.

This data migration will be transparent to you with the exception that you will see a reduction in the size of the ActivityPointer table after the migration process is fully completed. In Power Platform admin center within the Capacity report, a new email line item will be available in File usage. The end result is an increase in the overall File storage consumption and reduction in the database storage consumed.

The limitations mentioned in the next section will start applying to any data that has already moved to the Dataverse managed Azure blob storage even if all the data movement is not complete.

Search and filtering limitations

For email descriptions (bodies) stored in Azure Blob storage, certain limitations apply to filtering, finding, and searching email descriptions as described in the following sections.

Filtering

Filtering on email descriptions isn't supported. Some specific points to consider are:

• FetchXML - You can't search in email bodies by using FetchXML.
• Quick Find and Advanced Find - You can't filter email descriptions by using these methods.

Searching

You can enable Dataverse search on email descriptions to search email descriptions.

See also

Activity tables
Sample: Send an email
Email table
ActivityMimeAttachment table