Edit

Exporting and importing items by using EWS in Exchange

  • Article

Learn about exporting and importing appointments, emails, contacts, tasks, and other mailbox items by using the EWS Managed API or EWS in Exchange.

Exchange is a gold mine of important information: email, contacts, tasks, and calendars are core to an organization's functions. EWS enables you to export and import core item types via three different approaches:

  • Exchange item types. We recommend this approach for importing and exporting items to and from other systems and files.

  • Item-level capability (EWS only). We recommend this option for exporting or copying from one Exchange server or mailbox and importing to another.

  • MIME streams in the form of common standard file formats such as iCalendar and vCard. Because the property set is limited and MIME conversion is costly, we recommend the approach only for importing or exporting a small amount of data.

Important

EWS is not designed for mailbox backup and restore. To back up and restore databases, use the backup and restore API. See also Backup, restore, and disaster recovery on TechNet.

Table 1. Exporting and importing contact, email, and calendar items

Task EWS Managed API method EWS operation Notes
Export a copy of a contact, email, task, or calendar item with a specified property set.
Contact.Bind
EmailMessage.Bind
Appointment.Bind
Task.Bind
GetItem
We recommend this option if you're exporting mailbox items to another non-Exchange system or file (including vCard and iCal file types).
Because you have control over the exported property set, and because performance is better for the Exchange server, this is generally the best option.

Depending on the properties set on a mailbox item, and whether your application is aware of all of the non-schematized property identifiers (extended properties) that might be set on an item, this option might not produce a full-fidelity copy.

These methods and operation provide the schematized set of properties for an item plus any requested extended properties.
The Bind method or GetItem operation can only provide full-fidelity export of items if you know the extended properties that are set on an item.
You can request all the known extended properties to enable full fidelity.

TIP: You can use the tracing feature in the EWS Managed API to get the XML representation of exported items. For more information, see Export an item into a custom format.
Import a copy of a contact, email, task, or calendar item with a specified property set.
Contact.Save
EmailMessage.Save
Appointment.Save
Task.Save
CreateItem
We recommend this option for importing mailbox items into Exchange.
You might have to set special properties on some item types in order to maintain the state of the imported item.
Because some properties are only set by Exchange and not by clients, it's not always possible to have a full-fidelity import.

For example, you cannot import a meeting with attendees into a mailbox because Exchange sets the relationships between the organizer and attendees.
This relationship can only be established by organizers sending and attendees receiving and responding to the meeting request.

Appointment objects in Exchange can have complex relationships and settings.
Appointments that have attendees (meetings) have settings that tie together the meeting organizer and meeting attendees.
These settings are not maintained when you export and import appointments.
Programmatically reestablishing meeting organizer/attendee relationships directly on the appointments is not supported.
An option you do have for reestablishing those relationships is to perform post-processing after an import, then have an organizer resend the meetings and have the attendees accept the meetings.
You can use Exchange impersonation to make the calls for both the organizer and the attendees.
You should change the UID property of the Appointment object before you import to avoid having meetings be incorrectly related to other meetings in a mailbox.
Export a copy of a contact, email, task, or calendar item in full-fidelity.
Not applicable
ExportItems
This is the best option for exporting mailbox items that you want to import back into an Exchange mailbox.
You can also use this option to copy items between mailboxes.

The ExportItems operation provides an opaque stream that represents the item that you can use to move information between mailboxes.
You can use ExportItems with the GetItem operation to make an index for finding the items in another system.
You cannot change the export stream.
For more information, see Export items with full fidelity.
Import a copy of a contact, email, task, or calendar item in full-fidelity.
Not applicable
UploadItems
This is the only option for importing items that were exported by the ExportItems operation.
Export a copy of a contact, email, or calendar item as a MIME stream for a common file type.
Contact.Bind
EmailMessage.Bind
Appointment.Bind
GetItem
You can use the MimeContent property to get the MIME stream representation of an item.

This will provide a basic subset of all the properties on an item.
As a best practice, only use the MIME stream for one-off operations.
Do not rely on MIME for large and frequent importing/exporting of items, because Exchange performs content conversion for the MIME and this can affect performance.

The Contact MIME stream is a vCard (.vcf) file.
Depending on the properties set on a contact, this might not produce a full-fidelity copy.
Note that you cannot import a contact by using the vCard MIME stream.
To learn more, see Export a contact into a vCard file.

The EmailMessage MIME stream is an .eml file.
The .eml format is convenient because Outlook and other email clients can identify it.
You can also use the MIME stream to create an .mht file, which is convenient because many browsers can use that file type.
EWS doesn't provide a .msg file stream for exporting an email to a .msg file.
Your options for exporting an .msg file are to either construct an .MSG file from the results of an EmailMessage.Bind method or GetItem operation call, or use a third-party API that calls EWS and constructs the .msg file from the results.
For more information, see Export an email as an .eml file.

The Appointment MIME stream is an iCal (.ics) file.
The .ics format is convenient because Outlook and other email clients can identify it.
This is not a viable option for exporting meetings because attendee information is not provided in the MIME stream.
Attachments and other properties might not be included in the MIME stream.
Consider constructing the iCal format from either the Appointment object or from the XML returned by the GetItem operation.
This way, you can capture more of the Exchange properties with extended properties ("X-' properties) in the iCal file.
You can also export an appointment in XML form.
Call the GetItem operation and save the XML in your system.
You can also use the tracing functionality in the EWS Managed API to capture the XML to put in an XML database.
For more information, see Exporting an appointment as an iCal file.
Import a copy of an email or calendar item as a MIME stream for a common file type.
EmailMessage.Save
Appointment.Save
CreateItem
You can import an .eml or .ics file by using the MimeContent property on an EmailMessage or Appointment object.
You will need to set the PidTagMessageFlags (0x0E07) extended property if the email is not a draft.

You cannot use this approach to import meetings.

Alternatives to exporting and importing items by using EWS

Other options are available for exporing and importing items to and from an Exchange mailbox. The following are some ideas to consider when you design your import and export strategy:

In this section

See also