Create subscription

Subscribes a listener application to receive notifications when the requested type of changes occur to the specified resource in Microsoft Graph.

Permissions

Creating a subscription requires read scope to the resource. For example, to get notifications on messages, your app needs the Mail.Read permission.

Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. To learn more, including how to choose permissions, see Permissions.

Supported resource Delegated (work or school account) Delegated (personal Microsoft account) Application
contact Contacts.Read Contacts.Read Contacts.Read
driveItem (user's personal OneDrive) Not supported Files.ReadWrite Not supported
driveItem (OneDrive for Business) Files.ReadWrite.All Not supported Files.ReadWrite.All
event Calendars.Read Calendars.Read Calendars.Read
group Group.Read.All Not supported Group.Read.All
group conversation Group.Read.All Not supported Not supported
message Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read
security alert SecurityEvents.ReadWrite.All Not supported SecurityEvents.ReadWrite.All
user User.Read.All User.Read.All User.Read.All

Note: There are additional limitations for subscriptions on OneDrive and Outlook items. The limitations apply to creating as well as managing subscriptions (getting, updating, and deleting subscriptions).

  • On personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. On OneDrive for Business, you can subscribe to only the root folder. Notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

  • In Outlook, delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. That means, for example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.

  • To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:

    • Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
    • Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.

HTTP request

POST /subscriptions

Request headers

Name Type Description
Authorization string Bearer {token}. Required.

Response

If successful, this method returns 201 Created response code and a subscription object in the response body.

Example

Request

Here is an example of the request to send a notification when the user receives a new mail.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
   "changeType": "updated",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue"
}

In the request body, supply a JSON representation of the subscription object. The clientState field is optional.

Resources examples

The following are valid values for the resource property of the subscription:

Resource type Examples
Mail me/mailfolders('inbox')/messages
me/messages
Contacts me/contacts
Calendars me/events
Users users
Groups groups
Conversations groups('{id}')/conversations
Drives me/drive/root
Security alert security/alerts?$filter=status eq ‘New’
Response

Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 201 Created
Content-type: application/json
Content-length: 252

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "updated",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437"
}

Notification endpoint validation

The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. If validation fails, the request to create the subscription returns a 400 Bad Request error.