[DEPRECATED] Office 365 Data Extensions REST API reference (version 2.0)

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 Office 365 Data Extensions REST API allows apps to dynamically store custom data in a message, event, or contact of the user's account. The account can be on Office 365 or a Microsoft account (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

A data extension in the Outlook REST API is an OData v4 open type which contains properties that you can specify at runtime. You can use the Data Extensions API to extend an instance of an entity type already defined in the Entity Data Model (EDM) - a message, event, or contact - by dynamically specifying custom properties and values in a JSON payload. This makes the definition of such entity types more flexible, saving you time to define new entity types just for this purpose.

The ExtensionName property is the only property defined for all extensions. One way to help make sure extension names are unique is to use a reverse domain name system (DNS) method that is dependent on your own domain, for example, Com.Contoso.Contact. Do not use the Microsoft domain in an extension name.

Because an extension is an open type, you can specify additional data specific to an instance of an entity. For example, you can create an extension for individual business contacts that tracks custom data such as company name and initial referrer, and specify the data in the JSON payload as below:

POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions
{
   @odata.type: "Microsoft.OutlookServices.OpenTypeExtension",
   "ExtensionName": "Com.Contoso.Customer",
   "CompanyName": "Alpine Skis",
   "InitialReferrer":  "Robin McCall"
}

You can use the Data Extensions API to perform CRUD operations on a new or existing resource. Read more about the supported operations.

For more information about OData open type, see OData v4 documentation on OData.org.

Using the Data Extensions REST API

Data extensions or extended properties?

Data extensions is the recommended solution for most scenarios involving storing and accessing custom data. If, however, you need to access custom data for Outlook MAPI properties that are not already exposed through the Outlook REST API metadata, you can use extended properties and its REST API. You can verify which properties the metadata exposes at https://outlook.office.com/api/{version}/$metadata, substituting {version} by v2.0, beta, etc., for the version of your choice.

Authentication

Like other Outlook REST API, for every request to the Data Extensions 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 Data Extensions API.

Supported REST resources

You can create extensions for instances of the following resources in the Outlook REST endpoint:

• Message
• Event
• Contact

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:

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

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

URL parameters

The examples in this article use the following ID placeholders in parameters of REST request URLs. You must specify the ID of the instance of the resource for which you want to create an extension.

Parameter	Type	Description
URL parameters
contact_id	string	The contact ID.
event_id	string	The event ID.
message_id	string	The message ID.

See Use the Outlook REST API for more information common to all subsets of the Outlook REST API and the Office 365 Data Extensions REST API.

Extension operations

• Create an extension in an existing item
• Create an extension in a new item
• Get an extension
• Get item expanded with an extension
• Find and expand items with an extension
• Add or modify data in an extension
• Delete an extension

Create extension in an existing item

Create an extension and add custom properties for the specified instance of a resource. The resource can be a message, calendar event, or contact in Office 365 or Outlook.com. The data in the JSON payload can be primitive types, or arrays of primitive types.

To create an extension for each of the supported resources:

POST https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions

Minimum required scope

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

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parameter	Type	Description
Body parameters
ExtensionName	string	A unique text identifier for an extension. Required.

Sample request

This example creates an extension for the specified message. The request body includes the following for the extension:

• The type Microsoft.OutlookServices.OpenTypeExtension which is defined to be an OData open type in the Outlook REST API metadata.
• The extension name "Com.Contoso.Referral".
• Additional data to be stored as custom properties in the JSON payload: CompanyName, DealValue, and ExpirationDate which contain primitive types, and TopModels and TopSalespersons which contain arrays of primitive types.

POST https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions

Content-Type: application/json

{
  "@odata.type" : "Microsoft.OutlookServices.OpenTypeExtension",
  "ExtensionName" : "Com.Contoso.Referral",
  "CompanyName" : "Wingtip Toys",
  "DealValue@odata.type": "#Int64",
  "DealValue" : 500050,
  "ExpirationDate" : "2015-12-03T10:00:00.000Z",
  "TopModels": [
     3001,
     4002,
     5003
  ],
  "TopSalespersons": [
     "Dana Swope",
     "Fanny Downs",
     "Randi Welch"
  ]
}

Sample response

A successful response is indicated by an HTTP 201 Created response code.

The response body includes the following for the new extension:

• The default property ExtensionName.
• The Id property with the fully qualified name of Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
• The custom data to be stored.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue@odata.type": "#Int64",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "TopModels@odata.type": "#Collection(Int32)",
    "TopModels": [
      3001,
      4002,
      5003
    ],
    "TopSalespersons@odata.type": "#Collection(String)",
    "TopSalespersons": [
      "Dana Swope",
      "Fanny Downs",
      "Randi Welch"
    ]
}

Create extension in a new item

Create one or more extensions while creating a new instance of a resource, all in the same POST call, and add custom properties to the extension. The resource can be a message, calendar event, or contact in Office 365 or Outlook.com. The data in the JSON payload can be primitive types, or arrays of primitive types.

To create an extension for each of the supported resources, make a POST call similar to creating that resource, and include an extension in the body of the POST request.

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

Minimum required scope

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

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parameter	Type	Description
Body parameters
ExtensionName	string	A unique text identifier for an extension. Required.

Sample request

This example creates a message and an extension in the same call. The request body includes the following:

• The Subject, Body, and ToRecipients properties typical of a new message.
• And for the extension:
  • The type Microsoft.OutlookServices.OpenTypeExtension which is defined to be an OData open type in the Outlook REST API metadata.
  • The extension name "Com.Contoso.Referral".
  • Additional data to be stored as custom properties in the JSON payload: CompanyName, ExpirationDate, and DealValue which contain primitive types, and TopModels and TopSalespersons which contain arrays of primitive types.

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

Content-Type: application/json

{
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "You should be proud!"
  },
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com"
      }
    }
  ],
  "Extensions": [
    {
      "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Sample response

A successful response is indicated by an HTTP 201 Created response code.

The response body includes properties of the new message, and the following for the new extension:

• The Id property with the fully qualified name of Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral.
• The default property ExtensionName specified in the request.
• The custom data specified in the request stored as custom properties.

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "Id": "AAMkAGEbs88AAB84uLuAAA=",
  "CreatedDateTime": "2015-10-30T03:03:43Z",
  "LastModifiedDateTime": "2015-10-30T03:03:43Z",
  "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "Categories": [ ],
  "ReceivedDateTime": "2015-10-30T03:03:43Z",
  "SentDateTime": "2015-10-30T03:03:43Z",
  "HasAttachments": false,
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r
\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "BodyPreview": "You should be proud!",
  "Importance": "Normal",
  "ParentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "Sender": null,
  "From": null,
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com",
        "Name": "John Doe"
      }
    }
  ],
  "CcRecipients": [ ],
  "BccRecipients": [ ],
  "ReplyTo": [ ],
  "ConversationId": "AAQkAGEFGugh3SVdMzzc=",
  "IsDeliveryReceiptRequested": false,
  "IsReadReceiptRequested": false,
  "IsRead": true,
  "IsDraft": true,
  "WebLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "MentionedMe": null,
  "Mentioned": [ ],
  "InferenceClassification": "Focused",
  "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages
('AAMkAGEbs88AAB84uLuAAA%3D')/Extensions",
  "Extensions": [
    {
      "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
      "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels@odata.type": "#Collection(Int32)",
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons@odata.type": "#Collection(String)",
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

Get extension

Get an extension by name or ID within the specified instance of a resource. The resource can be a message, calendar event, or contact in Office 365 or Outlook.com.

Getting the extension by name or by ID returns the same response body.

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

Minimum required scope

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

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Parameter	Type	Description
URL parameter
extensionId	string	This can be an extension name which is a text identifier unique among all extensions in a resource instance, or a fully qualified name which concatenates the extension type and unique text identifier. The fully qualified name is returned in the id property when you create the extension. Required.

Sample request

The first example references an extension by its name and gets the extension in the specified message.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

The second example references an extension by its ID (fully qualified name) and gets the extension in the specified message.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Sample response

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

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00Z"
}

Get item expanded with extension

Get an instance of a resource expanded with the extension that is specified by a filter on the Id. The resource can be a message, calendar event, or contact in Office 365 or Outlook.com.

You can filter on the Id against the extension name or fully qualified name, and then get the instance expanded with the extension as shown below. Make sure you apply URL encoding to the space characters in the filter string.

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

Minimum required scope

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

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Parameter	Type	Description
URL parameter
extensionId	string	This can be an extension name which is a text identifier unique among all extensions in a resource instance, or a fully qualified name which concatenates the extension type and unique text identifier. The fully qualified name is returned in the id property when you create the extension. Required.

Sample request

The following example gets and expands the specified message by including the extension returned from a filter. The filter returns the extension that has its Id matching a fully qualified name.

For your convenience, the request is shown below with URL encoding of the reserved character, space.

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')?$expand=Extensions($filter=Id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Sample response

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

The response body includes all the properties of the specified message and extension returned from the filter.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "Id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "Categories": [
    ],
    "CreateDateTime": "2015-06-19T02:03:31Z",
    "LastModifiedDateTime": "2015-08-13T02:28:00Z",
    "Subject": "Attached is the requested info",
    "BodyPreview": "See the images attached.",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "Importance": "Normal",
    "HasAttachments": true,
    "ParentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "From": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "Sender": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "ToRecipients": [
        {
            "EmailAddress": {
                "Address": "wendy@contoso.com",
                "Name": "Wendy Molina"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "ReceivedDateTime": "2015-06-19T02:05:04Z",
    "SentDateTime": "2015-06-19T02:04:59Z",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsDraft": false,
    "IsRead": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Users('desmond40contoso.com')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions",
    "Extensions": [
      {
        "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
        "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "ExtensionName": "Com.Contoso.Referral",
        "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "CompanyName": "Wingtip Toys",
        "DealValue": 500050,
        "ExpirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

Find and expand items with an extension

You can find instances of a resource that contain an extension matching a filter. Additionally, in the same query, you can get these instances expanded with the extension. The queries in this section find such instances, expand and include the extension in the response.

The resource can be a message, calendar event, or contact in Office 365 or Outlook.com.

You can filter on the Id against the extension name or fully qualified name, and then get the instances expanded with the extension as shown below. Make sure you apply URL encoding to the space characters in the filter string.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

Minimum required scope

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

• https://outlook.office.com/mail.read
• https://outlook.office.com/calendars.read
• https://outlook.office.com/contacts.read
• wl.imap
• wl.calendars
• wl.contacts_calendars
• wl.basic

Parameter	Type	Description
URL parameter
extensionId	string	This can be an extension name which is a text identifier unique among all extensions in a resource instance, or a fully qualified name which concatenates the extension type and unique text identifier. The fully qualified name is returned in the id property when you create the extension. Required.

Sample request

The following example searches all messages in the signed-in user's mailbox to find those that contain an extension matching a filter, and expands them by including the extension. The filter returns extensions that has the Id matching the extension name Com.Contoso.Referral.

For your convenience, the request is shown below with URL encoding of the reserved character, space.

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=Id%20eq%20'Com.Contoso.Referral')

Sample response

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

The response body includes all the messages that have a matching extension, and all message properties. In this example, the response contains two messages.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.EventMessage",
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')",
            "@odata.etag": "W/\"DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn\"",
            "Id": "AAMkADIyDREAAA=",
            "CreatedDateTime": "2016-01-06T02:20:17Z",
            "LastModifiedDateTime": "2016-01-13T02:13:54Z",
            "ChangeKey": "DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:18Z",
            "SentDateTime": "2016-01-06T02:20:18Z",
            "HasAttachments": false,
            "InternetMessageId": "<BY1PR19MB0023E92E0B43F5E268406F0DF5F40@BY1PR19MB0023.namprd19.prod.outlook.com>",
            "Subject": "Accepted: Latin American Product Manual Group",
            "Body": {
                "ContentType": "Text",
                "Content": ""
            },
            "BodyPreview": "",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAAEJAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyWejUoYAg=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": true,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyDREAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "MeetingMessageType": "MeetingAccepted",
            "StartDateTime": {
                "DateTime": "2015-01-05T19:00:00.0000000",
                "TimeZone": "UTC"
            },
            "EndDateTime": {
                "DateTime": "2015-01-05T20:30:00.0000000",
                "TimeZone": "UTC"
            },
            "Location": {
                "DisplayName": "Mt. Adams"
            },
            "Type": "SeriesMaster",
            "Recurrence": {
                "Pattern": {
                    "Type": "RelativeMonthly",
                    "Interval": 2,
                    "Month": 0,
                    "DayOfMonth": 0,
                    "DaysOfWeek": [
                        "Monday"
                    ],
                    "FirstDayOfWeek": "Sunday",
                    "Index": "First"
                },
                "Range": {
                    "Type": "NoEnd",
                    "StartDate": "2015-01-05",
                    "EndDate": "0001-01-01",
                    "RecurrenceTimeZone": "tzone://Microsoft/Utc",
                    "NumberOfOccurrences": 0
                }
            },
            "IsOutOfDate": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyDREAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500300,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ],
            "Event@odata.associationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')/$ref",
            "Event@odata.navigationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')"
        },
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')",
            "@odata.etag": "W/\"CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq\"",
            "Id": "AAMkADIyAHVAAA=",
            "CreatedDateTime": "2016-01-06T02:20:02Z",
            "LastModifiedDateTime": "2016-01-13T02:24:50Z",
            "ChangeKey": "CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:02Z",
            "SentDateTime": "2016-01-06T02:20:01Z",
            "HasAttachments": false,
            "InternetMessageId": "<CY1PR19MB0032531C620A46068FDDD45DE3F40@CY1PR19MB0032.namprd19.prod.outlook.com>",
            "Subject": "International Launch Planning for XT2000",
            "Body": {
                "ContentType": "HTML",
                "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nWe will be ready to ship XT 2000 on 10/1, how's the International launch plan going?<br>\r\n<div style=\"display:inline-block\">\r\n<table border=\"0\" cellspacing=\"0\" style=\"background-color:#F4F4F4\">\r\n<tbody>\r\n<tr>\r\n<td style=\"padding:20px; font-size:12px; color:#666666\">You're receiving this message because you're a subscribed member of the Engineering group.<br>\r\n<a href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=conversations&amp;source=EscalatedMessage\">View group conversations</a> |\r\n<a href=\"https://adatumltd.sharepoint.com/_layouts/groupstatus.aspx?id=dbcbe107-6244-40ba-b0f1-1c46ad35435d&amp;target=documents\">\r\nView group files</a> | <a id=\"BD5134C6-8D33-4ABA-A0C4-08581FDF89DB\" href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=unsubscribe&amp;source=EscalatedMessage\">\r\nUnsubscribe</a></td>\r\n</tr>\r\n</tbody>\r\n</table>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "BodyPreview": "We will be ready to ship XT 2000 on 10/1, how's the International launch plan going?\r\nYou're receiving this message because you're a subscribed member of the Engineering group.\r\nView group conversations | View group files | Unsubscribe",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAEMAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "Engineering",
                    "Address": "engineering@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "Garret Vargas",
                    "Address": "GarretV@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyLESZnSPc=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": false,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyAHVAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyAHVAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500050,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ]
        }
    ]
}

Add or modify data in an extension

Update an extension with the properties in the request body:

• If a property in the request body matches the name of an existing property in the extension, the data in the extension is updated.
• Otherwise that property and its data are added to the extension.

The extension is in a resource which can be a message, calendar event, or contact in Office 365 or Outlook.com. It can be referenced by name or ID, and either way returns the same response. The data in the JSON payload can be primitive types, or arrays of primitive types.

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

Minimum required scope

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

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parameter	Type	Description
URL parameter
extensionId	string	This can be an extension name which is a text identifier unique among all extensions in a resource instance, or a fully qualified name which concatenates the extension type and unique text identifier. The fully qualified name is returned in the id property when you create the extension. Required.
Body parameters
ExtensionName	string	A unique text identifier for an extension. Required.

Sample request

Each of the two examples in this section uses the extension in the GET extension example above. The first references the extension by name, the second by ID. Their request bodies and responses are the same.

Each example updates the extension above by:

• Changing CompanyName from Wingtip Toys to Wingtip Toys (USA)
• Changing DealValue from 500050 to 500100
• Adding new data as the custom property Updated

This example references the extension by its name:

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

This example references the extension by its ID (fully qualified name):

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Sample response

A successful response is indicated by an HTTP 200 OK response code, and the updated extension in the response body.

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": 500100,
    "ExpirationDate": "2015-12-03T10:00:00Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

Delete an extension

Delete an extension from the specified instance of a resource. The resource can be a message, calendar event, or contact in Office 365 or Outlook.com.

To delete an extension in an instance of each of the supported resources:

DELETE https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extension_name}')

Minimum required scope

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

• https://outlook.office.com/mail.readwrite
• https://outlook.office.com/calendars.readwrite
• https://outlook.office.com/contacts.readwrite
• wl.imap
• wl.calendars_update
• wl.events_create
• wl.contacts_create

Parameter	Type	Description
URL parameters
extension_name	string	A unique text identifier for an extension. Required.

Sample request

The following example references an extension by its name and deletes the extension in the specified message.

DELETE https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

Sample response

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

Extension entities

Extension

Type: Microsoft.OutlookServices.Entity

An abstract entity with the Entity entity as base type.

OpenTypeExtension

Type: Microsoft.OutlookServices.Extension

An abstract, OData v4 open type that supports dynamically specifying properties and data in a JSON payload to update an instance of an entity type.

Property	Type	Description	Writable?	Filterable?
ExtensionName	string	Unique extension name. Use a reverse domain name system based on your own domain, for example, Com.Contoso.Contact.	Yes	No

Next steps

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

• Get started with Mail, Calendar, and Contacts REST APIs.
• Want samples? We've got them.

Or, learn more about using the Office 365 platform:

• Outlook REST API on the Outlook Dev Center
• Overview of developing on the Office 365 platform
• Office 365 app authentication and resource authorization
• Manually register your app with Azure AD so it can access Office 365 APIs
• Mail REST APIs reference
• Calendar REST APIs reference
• Contacts REST APIs reference
• Task REST API (preview)
• Resource reference for the Mail, Calendar, Contacts, and Task REST APIs