Edit

Move and copy email messages by using EWS in Exchange

  • Article

Learn how to move and copy email messages by using the EWS Managed API or EWS in Exchange.

You can use the EWS Managed API or EWS to move and copy email messages in a mailbox.

Table 1. EWS Managed API methods and EWS operations for moving and copying email messages

Task EWS Managed API method EWS operation
Move an email message
EmailMessage.Move
MoveItem
Copy an email message
EmailMessage.Copy
CopyItem

It's important to note that when you move or copy an email message into a different folder, a new item is created in the new folder with a unique item ID, and the original message is deleted. If you're moving or copying an email message between two folders in the same mailbox, the new item is returned in the response, which gives you access to the new item ID. However, if you're moving or copying an email message between two mailboxes or between a mailbox and a public folder, the new item is not returned in the response. To access the moved message in that scenario, use the EWS Managed API FindItems method or EWS FindItem operation, create an extended property definition for the PidTagSearchKey (0x300B0102) property, or create and set a custom extended property and then search for the custom extended property in the new folder.

Deleting an email message is different than moving an item to the Deleted Items folder. If you use the EWS Managed API Item.Delete method or the EWS DeleteItem operation, the item specified in the request is removed from the original folder, and a copy is placed in the Deleted Items folder with a new item ID. Unlike when you move or copy any item, the new item is not returned in the Delete method or the DeleteItem operation response. The steps involved in deleting an email by using the EWS Managed API or EWS are the same as those for deleting any generic item from the Exchange store.

Move an email message by using the EWS Managed API

The following code example shows how to use the EmailMessage.Move method to move an existing email message from one folder to another.

This example assumes that service is a valid ExchangeService object, and that ItemId is the Id of the email message to move or copy.

// As a best practice, limit the properties returned by the Bind method to only those that are required.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, EmailMessageSchema.Subject, EmailMessageSchema.ParentFolderId);
// Bind to the existing item by using the ItemId.
// This method call results in a GetItem call to EWS.
EmailMessage beforeMessage = EmailMessage.Bind(service, ItemId, propSet);
// Move the specified mail to the JunkEmail folder and store the returned item.
Item item = beforeMessage.Move(WellKnownFolderName.JunkEmail);
// Check that the item was moved by binding to the moved email message 
// and retrieving the new ParentFolderId.
// This method call results in a GetItem call to EWS.
EmailMessage movedMessage = EmailMessage.Bind(service, item.Id, propSet);
Console.WriteLine("An email message with the subject '" + beforeMessage.Subject + "' has been moved from the '" + beforeMessage.ParentFolderId + "' folder to the '" + movedMessage.ParentFolderId + "' folder.");

Move an email message by using EWS

The following code example shows how to use the MoveItem operation to move an email message to the Junk Email folder.

This is also the XML request that is sent by the EWS Managed API when calling the Move method. The values of some attributes and elements have been shortened for readability.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013" />
  </soap:Header>
  <soap:Body>
    <m:MoveItem>
      <m:ToFolderId>
        <t:DistinguishedFolderId Id="junkemail" />
      </m:ToFolderId>
      <m:ItemIds>
        <t:ItemId Id="AfwDoAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF25sM1" />
      </m:ItemIds>
    </m:MoveItem>
  </soap:Body>
</soap:Envelope>

The server responds to the MoveItem request with a MoveItemResponse message that includes a ResponseCode value of NoError, which indicates that the email message was moved successfully. The response also includes the ItemId for the email message in the new folder, which is important to store because the ItemId is different in the new folder.

Copy an email message by using the EWS Managed API

The following code example shows how to use the EmailMessage.Copy method to copy an existing email message from one folder to another.

This example assumes that service is a valid ExchangeService object, and that ItemId is the Id of the email message to copy. The values of some parameters have been shortened for readability.

// As a best practice, limit the properties returned by the Bind method to only those that are required.
PropertySet propSet = new PropertySet(BasePropertySet.IdOnly, EmailMessageSchema.Subject, EmailMessageSchema.ParentFolderId);
// Bind to the existing item by using the ItemId.
// This method call results in a GetItem call to EWS.
EmailMessage originalMessage = EmailMessage.Bind(service, ItemId, propSet);
// Copy the orignal message into another folder in the mailbox and store the returned item.
Item item = originalMessage.Copy("epQ/3AAA=");
// Check that the item was copied by binding to the copied email message 
// and retrieving the new ParentFolderId.
// This method call results in a GetItem call to EWS.
EmailMessage copiedMessage = EmailMessage.Bind(service, item.Id, propSet);
Console.WriteLine("An email message with the subject '" + originalMessage.Subject + "' has been copied from the '" + originalMessage.ParentFolderId + "' folder to the '" + copiedMessage.ParentFolderId + "' folder.");

Copy an email message by using EWS

The following code example shows how to use the CopyItem operation to copy an email message to different folder in the same mailbox by sending the ItemId of the email message to move, and specifying the destination folder in the ToFolderId element.

This is also the XML request that is sent by the EWS Managed API when calling the Copy method. The values of some attributes and elements have been shortened for readability.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013" />
  </soap:Header>
  <soap:Body>
    <m:CopyItem>
      <m:ToFolderId>
        <t:FolderId Id="pQ/3AAA=" />
      </m:ToFolderId>
      <m:ItemIds>
        <t:ItemId Id="2TSeSAAA="
                  ChangeKey="CQAAABYAAAApjGm7TnMWQ5TzjbhziLL0AAF2d+3+" />
      </m:ItemIds>
    </m:CopyItem>
  </soap:Body>
</soap:Envelope>

The server responds to the CopyItem request with a CopyItemResponse message that includes a ResponseCode value of NoError, which indicates that the email message was copied successfully. The response also includes the ItemId for the email message in the new folder, which is important to store because the ItemId is different in the new folder.

See also