Import items by using EWS in Exchange

Article
09/15/2021

Learn how to import appointments, emails, contacts, tasks, and other items by using the EWS Managed API or EWS in Exchange.

Many systems contain appointments, emails, contacts, and tasks, and you can import those items into Exchange in a number of different ways. Importing items into Exchange is simple when mailbox relationships aren't maintained on those items. You can use the Item.Save EWS Managed API method or the CreateItem EWS operation to create the items in an Exchange mailbox. The simple approach does not support all scenarios, however; for example:

You cannot maintain the relationship between organizers and attendees when importing appointments with attendees (meetings). This means that the meeting organizer will need to resend meeting invites to attendees in order to reestablish the relationship between the organizer and attendees. If the appointment was imported into an attendee's calendar, the appointment will not be related to the meeting organizer's appointment. The attendees will need to accept the resent meeting invite from the organizer in order to reestablish the organizer-attendee relationship.
Information about the assignees is not preserved when assigned tasks are imported.

All the import options can be used to batch import items into Exchange.

Use EWS Managed API or EWS item types to import an item

You can use the EWS Managed API or EWS to import emails, contacts, appointments, or tasks from other systems. Just set the properties from your source format on any of the following objects, depending on what you're importing.

Table 1. EWS Managed API objects and EWS elements

EWS Managed API object	EWS element
EmailMessage	Message
Contact	Contact
Appointment	CalendarItem
Task	Task

Use the Item.Save EWS Managed API method or the CreateItem EWS operation to perform the import of items. We recommend this approach when you're importing items from other systems because you have control over which properties get imported. For more information about how to set properties on items and then save the item, see Create an item by using the EWS Managed API or Create an item by using EWS.

Import items with full fidelity

You can use the UploadItems EWS operation to upload an item as a data stream. This data stream representation of an item has to come from the results of an ExportItems operation call. Because the EWS Managed API does not implement the UploadItems operation, if you use the EWS Managed API, you'll need to write a routine to send the web requests.

This is the easiest way to import items that have been exported from another Exchange server.

In the following example, the identifiers and the Data element content are shortened for readability.

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
      xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
      xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013_SP1"/>
  </soap:Header>
  <soap:Body>
    <m:UploadItems>
      <m:Items>
        <t:Item CreateAction="CreateNew">
          <t:ParentFolderId  Id="AAMkADEzOTE7kV0AAA=" ChangeKey="AQAAAA=="/>
          <t:Data>AQAAAAgAAAAAAQAAAAADABZADQASDkANABMO</t:Data>
        </t:Item>
      </m:Items>
    </m:UploadItems>
  </soap:Body>
</soap:Envelope>

The server responds to the UploadItems request with an UploadItemsResponse element that that includes a ResponseCode element value of NoError, which indicates that the item was successfully uploaded. The response also includes the item ID of the uploaded item.

Use the MIME stream to import from common file formats

EWS can import EML (.eml) and iCal (.ics) files. You'll want to test your MIME content to see how the Exchange MIME parser handles the content of your MIME stream. Although using the MIME stream is convenient, it is typically better to Use EWS Managed API or EWS item types to import an item. Here's an example of how to import a vCard.

Use the EWS Managed API to import an email from an EML file by using the MIME stream

The following example shows how to set the MimeContent property with the contents of an EML file and then import the email into a mailbox. This example also shows how to set the PidTagMessageFlags (0x0E07) extended property on an imported email so that it doesn't appear in the mailbox as a draft item. This example assumes that service is a valid ExchangeService object, and that the user can authenticate to an Exchange server.

private static void UploadMIMEEmail(ExchangeService service)
{
    EmailMessage email = new EmailMessage(service);
    
    string emlFileName = @"C:\import\email.eml";
    using (FileStream fs = new FileStream(emlFileName, FileMode.Open, FileAccess.Read))
    {
        byte[] bytes = new byte[fs.Length];
        int numBytesToRead = (int)fs.Length;
        int numBytesRead = 0;
        while (numBytesToRead > 0)
        {
            int n = fs.Read(bytes, numBytesRead, numBytesToRead);
            if (n == 0)
                break;
            numBytesRead += n;
            numBytesToRead -= n;
        }
        // Set the contents of the .eml file to the MimeContent property.
        email.MimeContent = new MimeContent("UTF-8", bytes);
    }
    
    // Indicate that this email is not a draft. Otherwise, the email will appear as a 
    // draft to clients.
    ExtendedPropertyDefinition PR_MESSAGE_FLAGS_msgflag_read = new ExtendedPropertyDefinition(3591, MapiPropertyType.Integer);
    email.SetExtendedProperty(PR_MESSAGE_FLAGS_msgflag_read, 1);
    // This results in a CreateItem call to EWS. The email will be saved in the Inbox folder.
    email.Save(WellKnownFolderName.Inbox);
}

Use the EWS Managed API to import an appointment from an iCal file by using the MIME stream

You can import simple appointments in the form of iCalendar files by using the MIME stream. You can't import meetings, which are appointments with attendees, because the relationship between meeting organizers and attendees has to be set as part of the Exchange calendaring workflow. Attendees cannot be captured in the MIME stream.

The following code example shows you how to import a simple .ics file into a user's mailbox.

private static void UploadMIMEAppointment(ExchangeService service)
{
    Appointment appointment = new Appointment(service);
    string iCalFileName = @"C:\import\appointment.ics";
    using (FileStream fs = new FileStream(iCalFileName, FileMode.Open, FileAccess.Read))
    {
        byte[] bytes = new byte[fs.Length];
        int numBytesToRead = (int)fs.Length;
        int numBytesRead = 0;
        while (numBytesToRead > 0)
        {
            int n = fs.Read(bytes, numBytesRead, numBytesToRead);
            if (n == 0)
                break;
            numBytesRead += n;
            numBytesToRead -= n;
        }
        // Set the contents of the .ics file to the MimeContent property.
        appointment.MimeContent = new MimeContent("UTF-8", bytes);
    }
    // This results in a CreateItem call to EWS. 
    appointment.Save(WellKnownFolderName.Calendar);
}

Use EWS to import an item by using the MIME stream

You can use the CreateItem EWS operation to import EML and iCal items by using their MIME stream.

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
               xmlns:m="https://schemas.microsoft.com/exchange/services/2006/messages">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2013_SP1" />
    <t:MailboxCulture>en-US</t:MailboxCulture>
  </soap:Header>
  <soap:Body >
    <m:CreateItem>
      <m:SavedItemFolderId>
        <t:DistinguishedFolderId Id="inbox"/>
      </m:SavedItemFolderId> 
        <m:Items>
        <t:Message>
          <t:MimeContent CharacterSet="UTF-8">
            <!-- Insert MIME content here-->
          </t:MimeContent>
        </t:Message>
      </m:Items>
    </m:CreateItem>
  </soap:Body>
</soap:Envelope>

Next steps

After you import items into a mailbox, you might want to create a custom folder to store your imported items, or synchronize your client and mailbox items.