Outlook items (messages, events, contacts, tasks) have an interesting behavior that you’ve probably either never noticed or has caused you significant frustration: their IDs change. It doesn’t happen often, only if the item is moved, but it can cause real problems for apps that store IDs offline for later use.

In the coming weeks, we’re rolling out a new feature designed to eliminate this problem: Immutable ID. With this feature, Microsoft Graph will provide an identifier in the id property that will not change over the lifetime of the item, so long as the item stays in the same mailbox. Watch this post for an update when the feature becomes available.

UPDATE (Jan 15, 2019): This feature is now available in Microsoft Graph v1.0 and beta as an “opt-in”. Graph will continue to return regular IDs by default.

How it works

Even though we don’t believe it would cause problems for existing solutions, to be safe, immutable ID will initially be an “opt-in” feature for Microsoft Graph v1.0 and beta. To opt in, your application needs to send an additional HTTP header in your API requests:

Prefer: IdType="ImmutableId"

Note: In the coming months, the beta version of Microsoft Graph and the beta version the Outlook REST API endpoint (https://outlook.office.com/api/beta) will return immutable ID by default. The Microsoft Graph v1.0 and the Outlook REST v2.0 endpoints will remain opt-in.

Lifetime of Immutable IDs

An item’s immutable ID will not change so long as the item stays in the same mailbox. That means that immutable ID will NOT change if the item is moved to a different folder in the mailbox. However, the immutable ID will change if:

• The user moves the item to an archive mailbox
• The user exports the item (to a PST, as an MSG file, etc.) and re-imports it into their mailbox

Items that support immutable ID

The following items support immutable IDs:

• message
• attachment
• event
• eventMessage
• contact
• outlookTask

Container types (mailFolder, calendar, etc.) do not support immutable ID, but their regular IDs were already constant.

Updating existing data

We’re also providing a method to migrate existing IDs to an equivalent immutable ID. If you’ve already got a database filled with thousands of regular IDs, you can easily migrate. As part of this feature update, we’re providing a new method on the user entity called translateExchangeIds. You can provide an array of up to 1000 IDs to be translated into a target format.

Example

The following example translates a normal Graph ID to an immutable Graph ID.

Request

POST https://graph.microsoft.com/beta/me/translateExchangeIds

{ 
  "inputIds" : 
  [ 
    "AQMkAGM2…" 
  ], 
  "targetIdType" : "restImmutableEntryId", 
  "sourceIdType" : "restId" 
}

Response

HTTP 200 OK

{ 
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.convertIdResult)", 
  "value": [ 
    { 
      "targetId": "AAkALgAA...", 
      "sourceId": "AQMkAGM2..."
    } 
  ] 
}

Release timeline

The following is the planned timeline to release this feature. This timeline is subject to change as we monitor the changes.

• Initial release (October 2018): Immutable ID available on Microsoft Graph beta and Outlook REST beta, requires Prefer header.
• Promote to production (January 2019): Immutable ID available on Microsoft Graph v1.0 and Outlook REST v2.0, requires Prefer header.
• Immutable ID becomes default on beta (a couple of months after previous phase): Immutable ID becomes default on both beta endpoints, remains “opt-in” on production endpoints.

Call to action

Watch this post for an update when immutable IDs become available, then give them a try! Please provide feedback on the feature on UserVoice.

Important: If your production application is using the Microsoft Graph beta endpoint or the Outlook REST API beta endpoint, be aware of the impending change to return immutable IDs by default. If this is a breaking change for your scenario, you will want to consider migrating to Microsoft Graph v1.0.