Share via

[DEPRECATED] Outlook Push Notifications REST API reference (version 2.0)

  • Article

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

Note

Version 2.0 of the Outlook REST API is deprecated.

As announced on November 17, 2020, version 2.0 of the Outlook REST API has been deprecated. The v2.0 REST endpoint will be fully decommissioned in March 2024, and the v2.0 documentation will be removed shortly afterwards. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.

The Outlook Push Notifications REST API sends notifications via a webhook to a client-side web service to notify apps about changes to a 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.

Not interested in v2.0 of the API? In the table of contents on the left, go to the Office 365 REST API reference section and select the version you want.

Overview

The Office 365 push notifications service and API work with clients that provide a web service with a callback address, and use webhooks to deliver notifications to client apps. Webhooks are HTTP callbacks configured by usually a trusted, third-party backend web service. The web service can configure webhooks to cause triggering events on one site to invoke behavior on another.

When an app subscribes to notifications of a specific resource (such as messages in the user's Inbox), it specifies a webhook callback URL in the subscription request. When a triggering event occurs (such as a new message in the Inbox), the Office 365 notifications service pushes a notification via a webhook to the callback URL. The app, in turn, takes actions according to its business logic, such as getting the new message and updating the unread count.

Apps should renew their subscriptions before they expire. They can also unsubscribe any time to stop receiving notifications.

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. Currently, push notifications are commonly used by mobile apps, as it doesn't require clients to poll for changes, and makes updates available to clients almost immediately.

Comparing with streaming notifications, push notifications require the client to provide its own web service in order to get notifications, while streaming notifications requires only a direct connection between the client and Office 365 streaming notifications service.

Use the Push Notifications REST API

Authentication

To subscribe, query, renew, and delete subscriptions, 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 API, for every request to the Outlook Push 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 Push Notifications API.

Version of API

This API has been promoted from preview to General Availability (GA) status. It is supported in the v2.0 and beta versions of the Outlook REST API.

Target user

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

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.

Push notification operations

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

Subscription process

The subscription process goes as follows:

  1. A client app makes a subscription request (POST) for a specific resource. It includes a notification URL, among other properties.

  2. The Outlook notifications service tries to validate the notification URL with the listener service. It includes a validation token in the validation request.

  3. If the listener service successfully validates the URL, it returns a success response within 5 seconds as follows:

    • Sets the content type in the response header to text\plain.
    • Includes the same validation token in the response body.
    • Returns an HTTP 200 response code. The listener can discard the validation token subsequently.

  4. Depending on the URL validation result, the Outlook notifications service sends a response to the client app:

    • If URL validation was successful, the service creates the subscription with a unique subscription ID and sends the response to the client.
    • If URL validation was unsuccessful, the service sends an error response with an error code and other details.

  5. Upon receiving a successful response, the client app stores the subscription ID to correlate future notifications with this subscription.

Subscription request

Subscribes to a listener service to receive notifications when mail, calendar events, contacts, or tasks change in Office 365 or Outlook.com. 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/v2.0/me/subscriptions

Specify in the request body the following properties for a push subscription request. Except for ClientState, all of the properties are required. For more information, see Notification Entities.

  • odata.type - Include "@odata.type":"#Microsoft.OutlookServices.PushSubscription". The PushSubscription entity defines NotificationURL.
  • ChangeType - Specifies the types of events to monitor for that resource. See ChangeType for the supported types.
  • ClientState - Optional property that indicates that each notification should be sent with a header by the same ClientState value. This lets the listener check the legitimacy of each notification.
  • NotificationURL - Specifies where notifications should be sent to. This URL represents a web service typically implemented by the client.
  • Resource - Specifies the resource to monitor and receive notifications on. You can use the optional query parameter $filter to refine the conditions for a notification, or use $select to 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/v2.0/me/mailfolders('inbox')/messages

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

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

    https://outlook.office.com/api/v2.0/me/messages

    https://outlook.office.com/api/v2.0/me/events

    https://outlook.office.com/api/v2.0/me/contacts

    https://outlook.office.com/api/v2.0/me/tasks

Sample request

The following example shows how to subscribe to new events.

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

{
   "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
   "Resource": "https://outlook.office.com/api/v2.0/me/events",
   "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
   "ChangeType": "Created",
   "ClientState": "c75831bd-fad3-4191-9a66-280a48528679"
}

Refine notification conditions

You can further refine the conditions for a notification by using the $filter query parameter.

The following example requests a notification for a Message being created in the Drafts folder, containing one or more attachments, and importance being High:

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('Drafts')/messages?$filter=HasAttachments%20eq%20true%20AND%20Importance%20eq%20%27High%27",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created",
  ClientState: "Has attachments and high importance"
}

The following example requests a notification for an all-day Event being created:

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/events?$filter=IsAllDay%20eq%20true",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created",
  ClientState: "Notifications for events that IsAllDay."
}

The following example requests a notification for a Contact being created with the company being Contoso:

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/contacts?$filter=CompanyName%20eq%20%27Contoso%27",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created",
  ClientState: "Contacts in Contoso."
}

One common application of $filter is to get notification on a change in a specific property of the specified resource.

For example, you can use $filter to subscribe to unread messages in a folder (the IsRead property is false), and include all the change types:

  • A message added to or marked unread in the folder would trigger a Created notification.
  • Reading a message or marking it as read in the folder would trigger a Deleted notification.
  • A change to any property, other than IsRead, of a message in the folder would trigger an Updated notification.

You can create such a subscription as follows:

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

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages$filter=IsRead%20eq%20false",
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

If you don’t use a $filter when creating the subscription (as below):

  • Adding a message to the folder would result in a Created notification.
  • Reading a message in the folder, marking the message as read, or changing any other property of a message in that folder would result in an Updated notification.
  • Deleting the message would result in a Delete notification.
POST https://outlook.office.com/api/v2.0/me/subscriptions HTTP/1.1
Content-Type: application/json

{
  @odata.type:"#Microsoft.OutlookServices.PushSubscription",
  Resource: "https://outlook.office.com/api/v2.0/me/mailfolders('folder_id')/messages,
  NotificationURL: "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
  ChangeType: "Created,Deleted,Updated",
  ClientState: "Message unread"
}

Validation request

The validation request attempts to validate the NotificationURL that a client app specifies in a subscription request:

POST https://{notificationUrl}?validationToken={token}

The Outlook service specifies the NotificationURL in the subscription request in {notificationUrl}, and defines a string {token} as the validation token. The Outlook service also includes a ClientState header if the client app includes one in the subscription request.

Subscription response

The subscription response includes the properties in the request, and the following additional properties:

  • Id - The unique subscription ID which the client app should save to match with future notifications.
  • ChangeType - Apart from the values specified in the request, the response includes the additional notification type, Missed.
  • SubscriptionExpirationDateTime - The date and time that the subscription will expire. If the subscription request does not specify an expiration time, or if the request specifies an expiration time longer than the maximum allowed, this property will be set to that maximum allowed length from the time the request is sent. For a subscription that requests rich notifications of specific properties, the maximum allowed is 1 day. For other subscriptions, the maximum is 7 days.
  • Other OData-related properties.

Sample response data

This response indicates that the listener service should expect to get notifications for new events and missed changes. If there are missed changes, the client will need to synchronize with the service to capture them.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Subscriptions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.PushSubscription",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')",
    "Id": "Mjk3QNERDQQ==",
    "Resource": "https://outlook.office.com/api/v2.0/me/events",
    "ChangeType": "Created, Missed",
    "ClientState": "c75831bd-fad3-4191-9a66-280a48528679",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myNotifyClient",
    "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z"
}

Query a subscription

You can find details about any of the signed-in user's existing subscriptions by specifying its subscription ID. As an example, to query the subscription created in the last example:

GET https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Subscriptions('Mjk3QNERDQQ==')

If successful, the response would be the same as the last sample response data, except it would exclude any ClientState the client app has specified to avoid potential security risks.

Notifications

Each notification contains the following properties, regardless of its type:

  • ClientState header - Present only if the client specified the ClientState property in the subscription request. Used by the listener to verify the legitimacy of the notification.
  • SubscriptionId - Identifies to the client app the subscription to which this notification belongs.
  • SubscriptionExpirationDateTime - The expiration date and time for the subscription.
  • SequenceNumber - A number in sequence for a notification, to help the client app identify if it's missing a notification.
  • ChangeType - The types of events that the client app wants to be notified on (for example, a Created event type when mail is received, or Update event type when reading a message).
  • Resource - The URL of the specific resource item that is being monitored (for example, a URL to the changed message or event).
  • ResourceData - A notification related to a resource change (such as receiving, reading or deleting a message) has this additional property that contains the resource ID of the item that was changed. A client can use this resource ID to handle this item according to its business logic (for example, fetch this item, sync its folder).

Note

The Id property is not used in Notification entities.

Change notification payload

In the following example, as the user receives a new event, the notifications service sends a notification with ChangeType set to "Created". The header of the notification would include the ClientState as specified in the initial subscription request. The receive event notification has a payload similar to this:

{
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.Notification",
            "Id": null,
            "SubscriptionId": "Mjk3QNERDQQ==",
            "SubscriptionExpirationDateTime": "2015-04-23T22:46:13.8805047Z",
            "SequenceNumber": 1,
            "ChangeType": "Created",
            "Resource" : "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
            "ResourceData": {
                "@odata.type": "#Microsoft.OutlookServices.Event",
                "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfcd489-628b-7d04-b48b-20075df800e5@1717622f-1d94-c0d4-9d74-f907ad6677b4')/Events('AAMkADNkNmAA=')",
                "Id": "AAMkADNkNmAA="
            }
        }
    ]
}

Get instance properties by subscribing to rich notifications

As seen in the last example of a change notification payload, a push notification subscription set up for a resource collection returns only the ID of a resource instance that has changed. You need to separately get the properties of that instance.

You can save a separate GET API call if you use a $select parameter in the subscription request and specify the properties you're interested in. The following is an example that requests a notification to include the subject property when an event has been created:

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

{
    "@odata.type":"#Microsoft.OutlookServices.PushSubscription",
    "Resource": "https://outlook.office.com/api/v2.0/me/events?$select=Subject",
    "NotificationURL": "https://mywebhook.azurewebsites.net/api/send/myRichNotifyClient",
    "ChangeType": "Created"
}

Sample rich notification payload

A rich notification payload includes the values of the properties specified in the subscription request. Following the last example, a rich notification includes the Subject property like this::

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$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/v2.0/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/v2.0/Users('6ed6de00-b4c1-4f9b-8ce0-30908c54da0a@ea54488f-a8f6-4c8d-acad-c3a1da54f79f')/Events('AAMkAGAAAAACisAAA=')",
        "@odata.etag": "W/\"IpGjeMHoYUS/RhJxluiSeAAAAAAyoQ==\"",
        "Id": "AAMkAGAAAAACisAAA=",
        "Subject": "Quarterly meeting CY17Q1"
      }
    }
  ]
}

Renew subscription

Renew a subscription for up to the maximum length from the time of the renewal request.

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/{subscriptionId}

The default subscription length is 7 days for subscription requests that don't require specific instance properties in the response, and 1 day for subscriptions to rich notifications.

You can submit the renew request without a payload and the subscription will be extended by the corresponding maximum period.

Sample request

PATCH https://outlook.office.com/api/v2.0/me/subscriptions/Mjk3QNERDQQ==

{
   @odata.type:"#Microsoft.OutlookServices.PushSubscription",
   "SubscriptionExpirationDateTime": "2015-05-28T17:17:45.9028722Z"
}

Response

A successful response is indicated by an HTTP 200 response code.

Delete subscription

Delete a subscription by specifying the subscription ID.

DELETE https://outlook.office.com/api/v2.0/me/subscriptions('{subscriptionId}')

Sample request

Delete https://outlook.office.com/api/v2.0/me/subscriptions('Mjk3QNERDQQ==')

Response

A successful response is indicated by an HTTP 204 No Content response code.

Notification API 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. In the case of push notifications, the notification is sent to the listener service specified by the client.

Base type: Entity

Property Type Description Writable? Filterable?
SubscriptionId string Unique identifier for the subscription. No No
SubscriptionExpirationDateTime Edm.DateTimeOffset Specifies the date and time when the notification subscription expires. The time is in UTC. Yes N/A
SequenceNumber int32 Indicates the sequence value of the change notification. No N/A
ChangeType ChangeType Indicates the type of event that raised the notification. The enumeration values are: Created=1, Updated=2, Deleted=4, Missed=16. A Missed notification occurs when the notifications service cannot send the requested notification. No N/A
Resource string Specifies the resource item that is being monitored for changes. Yes N/A
ResourceData Entity Identifies the entity that changed. This is a navigation property. No N/A

PushSubscription

Represents a subscription that uses the push notification mechanism.

Base type: Subscription

Property Type Description Writable? Filterable?
NotificationURL string The URL of the application that will receive the push notifications. Yes N/A
SubscriptionExpirationDateTime Edm.DateTimeOffset Specifies the date and time when the notification subscription expires. The time is in UTC. Yes N/A
ClientState string Specifies the value of the ClientState header sent by the service for each notification. The maximum length is 255 characters. The client can check that the notification came from the service by comparing the value set on the ClientState property with the value of the ClientState header received with each notification. Yes No

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: