Subscription lifetime changes for Outlook resources

Microsoft Graph team

We are in the process of deploying a change to the Outlook REST API and the Microsoft Graph that will expire subscriptions to Outlook-related resources (mail, calendar, contacts, tasks) automatically when one of the following events occurs:

  • The subscription is for an Intune-managed device that has been marked as non-compliant.
  • The password of the user that created the subscription has changed or been reset.
  • The account of the user that created the subscription has been disabled in Azure Active Directory.

This only applies to applications that use user tokens to create subscriptions. Applications that use app tokens to create subscriptions are not affected by this change. Existing applications do not need to do anything to enable this behavior.

Outlook REST API

When the subscription is removed, the Outlook REST API will send a notification with changeType set to “SubscriptionRemoved” to signal that the subscription has been removed, and the application will stop receiving any notifications. The notification’s error value contains more information about why the subscription was removed.

Example notification

{ 
    "value": [ 
        { 
        "SubscriptionId": "NTYxREIy...", 
        "SubscriptionExpirationDateTime": "2018-12-14T22:25:30.2337269Z", 
        "ChangeType": "SubscriptionRemoved", 
        "Error": { 
           "Message": "Account state change 'AccountDisabled' has happened after 
             last authorization time '2018-12-07T22:25:30.2307355Z', 
             please recreate your subscription.", 
           "Code": "AccountStateChanged" 
            }
        } 
    ] 
}

Handling SubscriptionRemoved notification

If your application receives a SubscriptionRemoved notification, you should immediately attempt to recreate the subscription. If the API call returns an authentication error, you should prompt the user to reauthenticate.

Handling missed notifications

In some cases, it may take some time before a subscription can be reestablished. The user might need to contact their administrator to get their account reinstated, for example. Any changes to the subscribed resources that happen during this time won’t generate notifications to your application. Once the connection has been reestablished, your app can retrieve those “missed” changes by either:

  • Deleting all local data and re-synchronizing
  • Making an API call filtered on the created or modified date (for example, GET <SubscriptionResourceUrl>?$filter=createdDateTime+ge+{LastTimeNotificationWasReceived})

Microsoft Graph

Currently, when the subscription is removed, Microsoft Graph does not send any notification to the application. We are working on a solution for Microsoft Graph. In the meantime, applications that use Microsoft Graph will need to be aware that this scenario will cause a 404 error when attempting to renew a subscription. In this case, the app should attempt to recreate the subscription. If the API call returns an authentication error, you should prompt the user to reauthenticate. Once the subscription is reestablished, use the methods from above to handle any missed notifications.

Call to action

If your application uses user tokens to create subscriptions to Outlook resources, update your apps as needed to handle this scenario. We welcome any feedback at our UserVoice.

Feedback usabilla icon