[DEPRECATED] Outlook Streaming Notifications REST API reference (preview)

  • Article

Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

Note

The beta version of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. Consequently, the beta REST endpoint is also deprecated and will be fully decommissioned in November 2022. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

The Outlook Streaming Notifications REST API sends notifications on a direct connection to let client apps learn about changes to the user's mailbox data. The data can be in the user's mail, calendar, contact, or task data secured by Azure Active Directory in Office 365, or in Microsoft accounts specifically in these domains: Hotmail.com, Live.com, MSN.com, Outlook.com, and Passport.com.

Note

For simplicity of reference, the rest of this article uses Outlook.com to include these Microsoft account domains.

Overview

The Office 365 streaming notifications service establishes a direct connection with a client and delivers notifications of data changes requested by a client app.

When an app subscribes to notifications for a type of change event on a specific resource (such as messages in the user's Inbox), a long-living connection is established between the Office 365 server and the client. When a triggering event occurs (such as a new message in the Inbox), the Office 365 service streams a notification to the client. The client parses the notification, and takes actions according to its business logic, such as getting the new message and updating the unread count.

Compare streaming and push notifications

Mail, calendaring and CRM apps typically use notifications to update their local cache, corresponding client views, or backend system upon changes. Outlook supports both streaming and push notifications. notifications. Push notifications requires the client to provide a listener web service to get notifications from the Office 365 server, while streaming notifications requires only a direct connection between the client and and the Office 365 server. Once a connection with the server is established, the connection remains open for a specified period of time. During this time, the client posts a long-living GetNotifications request just once; whenever a triggering event occurs, the server can simply send a notification as part of the response stream. This continues until the connection times out, the client drops the connection, or a problem occurs in the network.

Use the Streaming Notifications REST API

Authentication

To subscribe, get and close notifications, specify the appropriate scopes for the types of resources you want to be notified on.

Minimum required scope

One of the following read scopes corresponding to the targeted resource:

Like other Outlook REST APIs, for every request to the Outlook Streaming Notifications API, you should include a valid access token. Getting an access token requires you to have registered and identified your app, and obtained the appropriate authorization.

You can find out more about some streamlined registration and authorization options for you. Keep this in mind as you proceed with the specific operations in the Notifications API.

Version of the API

Currently, this API is in preview status and is available in only the beta REST API endpoint:

https://outlook.office.com/api/beta/

Target user

Streaming Notifications API requests are always performed on behalf of the current user.

Streaming notification operations

Subscribe to changes in my mail, calendar, contacts or tasks

Subscribes to streaming notifications when mail, calendar events, contacts, or tasks change in an Office 365 or Outlook.com mailbox. This is the first step for a client to start getting notifications for a resource (an entity or entity collection).

POST https://outlook.office.com/api/beta/me/subscriptions

Specify in the request body the following required properties for a streaming subscription request. For more information, see Notification Entities.

  • odata.type - Include "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription".

  • ChangeType - Specifies the types of events to monitor for that resource. See ChangeType for the supported types.

  • Resource - Specifies the resource to monitor and receive notifications on. You can use optional query parameters, $filter or $select, to refine the conditions for a notification or include specific properties in a rich notification. The following are the supported resources:

    • A regular folder or search folder for messages, events, contacts, or tasks. As examples:

      https://outlook.office.com/api/beta/me/mailfolders('inbox')/messages

      https://outlook.office.com/api/beta/me/taskfolders('{folder_id}')/tasks

    • Or a top level entity collection of messages, events, contacts, or tasks, such as:

      https://outlook.office.com/api/beta/me/messages

      https://outlook.office.com/api/beta/me/events

      https://outlook.office.com/api/beta/me/contacts

      https://outlook.office.com/api/beta/me/tasks

If the subscription request is successful, a subscription ID is returned. By default, this subscription ID will expire in 90 minutes unless the client starts listening for notifications on a connection. Then for as long as the connection is open, the subscription will be auto renewed.

Sample subscription request

The following request creates a streaming subscription to created, updated, and deleted changes for the user's Inbox.

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
   ChangeType: "Created,Updated,Deleted"
}

Sample subscription response

A successful response returns HTTP 201 and includes the subscription ID. The following is an example response:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('RUM4OEJFNUIQUQ4MQ==')",
    "Id":"RUM4OEJFNUIQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Refine notification conditions

You can limit notifications to a subset of items by using a $filter clause. For example, the following subscription request creates a subscription that triggers a notification only when changes are made to messages with the subject field "Supplements".

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
   @odata.type: "#Microsoft.OutlookServices.StreamingSubscription",
   Resource: "https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
   ChangeType: "Created,Updated,Deleted"
}

A successful subscription response looks like this:

HTTP/1.1 201 Created

{
    "@odata.context":"https://outlook.office.com/api/beta/$metadata#Me/Subscriptions/$entity",
    "@odata.type":"#Microsoft.OutlookServices.StreamingSubscription",
    "@odata.id":"https://outlook.office.com/api/beta/Users('266efe5a-0fd7-4edd-877b-b2d1e561f193@ae01a323-3934-4475-a32d-af1274312bb0')/Subscriptions('MjcwOUQ2MjEtQUQ4MQ==')",
    "Id":"MjcwOUQ2MjEtQUQ4MQ==",
    "Resource":"https://outlook.office.com/api/beta/me/mailfolders('inbox')/Messages?$filter=Subject%20eq%20%27Supplements%27",
    "ChangeType":"Created, Updated, Deleted, Missed"
}

Subscribe to rich streaming notifications

A subscription set up for simply a resource collection returns the ID of a resource instance that has changed. You need to separately get the properties of that instance. The first subscription request above is an example of this type of subscription. The notification stream in the next section shows only the resource ID is returned in a notification.

You can alternatively use a $select parameter in the subscription request, specify the properties you're interested in, and have those property values returned in streaming notifications as well.

The following is an example that requests streaming notifications to include the Subject property when an event has been created:

POST https://outlook.office.com/api/beta/me/subscriptions HTTP/1.1
Content-Type: application/json

{
    @odata.type:"#Microsoft.OutlookServices.StreamingSubscription",
    Resource: "https://outlook.office.com/api/beta/me/events?$select=Subject",
    ChangeType: "Created"
}

After successfully subscribing to rich streaming notifications, listen for notifications to get the Subject property in rich notification payloads.

Listen for notifications

The client creates a long-living pending POST connection for the specified subscriptions, to request the server to start streaming notifications.

POST https://outlook.office.com/api/beta/Me/GetNotifications

This POST request doesn’t complete until the specified ConnectionTimeoutinMinutes is reached and the server ends the JSON blob in the response, or if there are other issues and either the client or server closes the connection.

As long as the connection is open, all the subscriptions using the connection are auto-renewed. If the connection ends, these subscriptions will expire in 90 minutes as well, unless the client sets up a new connection for these subscriptions.

Make sure that your code that makes this POST request handles the return status code HTTP 404 Not found, which would be returned if a specified subscription has actually expired. If that happens, request a new subscription before listening for its notifications again.

Required body parameter Type Description
ConnectionTimeoutInMinutes int32 The number of minutes that the connection should stay alive.
KeepAliveNotificationIntervalInSeconds int32 The interval used by the server to send keep-alive notifications, to notify the client that the connection remains open.
SubscriptionIds Collection(String) IDs of the subscriptions that will be notified on this connection.

Sample listen requests

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg=="
   ]
}

You can use the same long-living connection to listen to notifications for multiple subscriptions by including more than one subscription ID in the POST request.

POST https://outlook.office.com/api/beta/Me/GetNotifications HTTP/1.1
Content-Type: application/json

{
   ConnectionTimeoutInMinutes: 30,
   KeepAliveNotificationIntervalInSeconds: 15,
   SubscriptionIds: [
       "N0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtNDc4NS04MTg2LUYwRjFFNUVFNTNDRg==",
       "Dc4NS04MTg2LUYwRjFFNUVFNTNDRgN0UzMEU4RjMtMjg1Ri00OEFGLUE5NzEtRDM5MkI3NjBDMDY5XzdFMzU4QTE1LTFCQjAtN=="
   ]
}

Sample notification stream

Once the service is set up, the client receives the beginning of the notifications JSON blob.

{
    {"@odata.context":"https://outlook.office.com/api/beta/metadata#Notifications",
    "value": [

The server sends a keep-alive notification at fixed intervals to keep the connection open and active. This interval is set by the client in the KeepAliveNotificationIntervalInSeconds property. The format of the keep-alive notification is as follows:

{
    "@odata.type": "#Microsoft.OutlookServices.KeepAliveNotification",
    "Status": "OK"
}

When a tracked change occurs on the server, the server sends a notification to the client through the connection. In each notification, the server sets the SubscriptionExpirationDateTime property, and keeps renewing it as long as the previous notification succeeded.

{
    "@odata.type": "#Microsoft.OutlookServices.Notification",
    "Id": null,
    "SubscriptionId": "N0UzMEU4...",
    "SubscriptionExpirationDateTime": "2016-09-09T18:36:42.3454926Z",
    "SequenceNumber": 9,
    "ChangeType": "Created",
    "Resource": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')",
    "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Message",
        "@odata.id": "https://outlook.office.com/api/beta/Users('bee8ce18AAA')/Messages('AAMkADdlAA=')",
        "@odata.etag": "W/\"CQAAABYAAAB+0z/4Ly/1ToDr5FGl5k99AAABl5Do\"",
        "Id": "AAMkADdlAA="
    }
}

When your application is listening for multiple notifications on the same long-living connection, you can use the SubscriptionId field to determine which subscription sent the notification.

Note

The second and subsequent notifications sent from the server have a leading comma before the opening bracket to make the notification valid JSON.

,{
    "Id": null,
    "SubscriptionId": "N0UzMEU4...",
    ...
}

Sample rich notification payload

If your subscription request specifies certain properties to be returned, notification payloads would include the values of those properties. Following the example above to subscribe to rich notifications, a rich notification payload that includes the Subject property can look like this:

{
  "@odata.context": "https://outlook.office.com/api/beta/$metadata#Notifications",
    {
      "@odata.type": "#Microsoft.OutlookServices.Notification",
      "Id": null,
      "SubscriptionId": "QjQzNzAwBQQ==",
      "SubscriptionExpirationDateTime": "2017-01-18T00:57:28.6134733Z",
      "SequenceNumber": 1,
      "ChangeType": "Created",
      "Resource": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
      "ResourceData": {
        "@odata.type": "#Microsoft.OutlookServices.Event",
        "@odata.id": "https://outlook.office.com/api/beta/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Close the connection

When the timeout specified in the ConnectionTimeoutInMinutes property is reached, the server closes the connection and sends the end of the JSON blob, as follows.

    ]
}

The connection may be dropped in other circumstances, such as network problems and changes to the server like reboots. The client can use the keep-alive notifications to determine if the connection is still active or has been dropped. In the latter case, the client should attempt to reconnect using the existing subscription ID. If the subscription ID has expired a new subscription request should be made to re-establish the connection.

If the client does not want to listen to a subscription anymore, the client can cancel the POST request and drop the connection. The next time the server attempts to send a notification, it will get an error, detect the connection drop, stop the keep-alive notifications and close the connection.

Notification entities and enumerations

Subscription

Represents the base subscription. This is an abstract base class.

Base type: Entity

Property Type Description Writable? Filterable
Resource string Specifies the resource that will be monitored for changes. Yes N/A
ChangeType ChangeType Indicates the type of events that will raise a notification. See ChangeType for the supported types. Yes N/A

Notification

Represents a notification sent to the client.

Base type: Entity

Property Type Description Writable? Filterable
SubscriptionId string Unique identifier for the subscription. No N/A
SequenceNumber int32 Indicates the sequence value of the change notification. No N/A
ChangeType string Indicates the type of event that raised the notification. See ChangeType for the supported types. No N/A
Resource string Specifies the resource item that is being monitored for changes No N/A
ResourceData Entity Identifies the entity that changed. This is a navigation property No N/A

ChangeType

An enumeration that specifies the types of events occurring to supported resources that can raise a notification.

Supported values:

  • Acknowledgment
  • Created
  • Deleted
  • Missed. A Missed notification occurs when the notifications service cannot send the requested notification.
  • Updated

Next steps

Whether you're ready to start building an app or just want to learn more, we've got you covered.

Or, learn more about using the Office 365 platform: