Flagged messages via Office 365 REST API?

Question

I'm looking for a way to detect & set the 'flagged' status of an email using the Office 365 REST Message API. I don't see 'Flag' listed as a property of a REST Message, though I do see it listed under Exchange Web Services.

I've attempted to make a REST call adding Flag to filtered properties, as well as SingleValueExtendedProperties and MultiValueExtendedProperties like:

/folders/inbox/messages?$top=50&$select=Subject,...,Flag
/folders/inbox/messages?$top=50&$select=Subject,...,SingleValueExtendedProperties
/folders/inbox/messages?$top=50&$select=Subject,...,MultiValueExtendedProperties

all of these have come back with some form of:

{"error":{"code":"RequestBroker-ParseUri","message":"Could not find a property named \\\'Flag\\\' on type \\\'Microsoft.OutlookServices.Message\\\'."}}

Any suggestions on how to get access to the Outlook 'Flag' property via the REST API?

Answer 1

UPDATE: There is now a Flag property on Message on the /beta endpoint. This is the recommended way to do this. I'll leave the other information there for historical purposes and to help folks trying to set other extended properties.

Now you can get/set flag status much easier. The Message entity now has a Flag property of type FollowupFlag. (If you don't see it at that link, be sure that the beta version is selected at the top of the page).

You can mark a message as flagged by sending a PATCH with the following payload:

{
  "Flag": {
    "FlagStatus": "Flagged"
  }
}

---

OLD METHOD (Using extended properties)

Note: We recently made a change to simplify the extended properties format. This change is rolling out to servers now, so I've added the new format to this answer. I've left the old format in case anyone is accessing mailboxes that haven't had the update applied yet. If using the old format and you get an error:

"Could not find a property named 'PropertyRef' on type 
'Microsoft.OutlookServices.SingleValueLegacyExtendedProperty'."

You need to move to the new format.

What you need to do is include an $expand query parameter to expand the SingleValueExtendedProperties collection, with a $filter sub-parameter to indicate the property you want to include. In this case, you want PidTagFlagStatus. Try a query like this:

New Format:

api/beta/me/messages?$select=Subject,SingleValueExtendedProperties&$expand=SingleValueExtendedProperties($filter=PropertyId eq 'Integer 0x1090')

Old Format:

api/beta/me/messages?$select=Subject,SingleValueExtendedProperties&$expand=SingleValueExtendedProperties($filter=(PropertyRef eq '0x1090' and Type eq Microsoft.OutlookServices.MapiPropertyType'Integer'))

Messages that aren't flagged at all will just not have that property returned. Messages that do will look something like this:

New Format:

{
  "@odata.id": "https://outlook.office365.com/api/beta/Users('JasonJ@jasonjohdemo.onmicrosoft.com')/Messages('AAMkAGQ4Yzc2NDkwLTYxYmItNDZmYS1iZjI1LTYyNmY4NTZkMjI1NgBGAAAAAADwPSus7EwaR6q1wNtgoqEMBwDpfBfj8UPUTqu4bEwGpnFMAAAAAAEgAADpfBfj8UPUTqu4bEwGpnFMAAAjCUJGAAA=')",
  "@odata.etag": "W/\"CQAAABYAAADpfBfj8UPUTqu4bEwGpnFMAAAjCzND\"",
  "Id": "AAMkAGQ4Yzc2NDkwLTYxYmItNDZmYS1iZjI1LTYyNmY4NTZkMjI1NgBGAAAAAADwPSus7EwaR6q1wNtgoqEMBwDpfBfj8UPUTqu4bEwGpnFMAAAAAAEgAADpfBfj8UPUTqu4bEwGpnFMAAAjCUJGAAA=",
  "Subject": "Test Flag",
  "SingleValueExtendedProperties@odata.context": "https://outlook.office365.com/api/beta/$metadata#Me/Messages('AAMkAGQ4Yzc2NDkwLTYxYmItNDZmYS1iZjI1LTYyNmY4NTZkMjI1NgBGAAAAAADwPSus7EwaR6q1wNtgoqEMBwDpfBfj8UPUTqu4bEwGpnFMAAAAAAEgAADpfBfj8UPUTqu4bEwGpnFMAAAjCUJGAAA%3D')/SingleValueExtendedProperties",
  "SingleValueExtendedProperties": [
    {
      "PropertyId": "Integer 0x1090",
      "Value": "2"
    }
  ]
}

Old Format:

{
  "@odata.id": "https://outlook.office365.com/api/beta/Users('JasonJ@jasonjohdemo.onmicrosoft.com')/Messages('AAMkAGQ4Yzc2NDkwLTYxYmItNDZmYS1iZjI1LTYyNmY4NTZkMjI1NgBGAAAAAADwPSus7EwaR6q1wNtgoqEMBwDpfBfj8UPUTqu4bEwGpnFMAAAAAAEgAADpfBfj8UPUTqu4bEwGpnFMAAAjCUJGAAA=')",
  "@odata.etag": "W/\"CQAAABYAAADpfBfj8UPUTqu4bEwGpnFMAAAjCzND\"",
  "Id": "AAMkAGQ4Yzc2NDkwLTYxYmItNDZmYS1iZjI1LTYyNmY4NTZkMjI1NgBGAAAAAADwPSus7EwaR6q1wNtgoqEMBwDpfBfj8UPUTqu4bEwGpnFMAAAAAAEgAADpfBfj8UPUTqu4bEwGpnFMAAAjCUJGAAA=",
  "Subject": "Test Flag",
  "SingleValueExtendedProperties@odata.context": "https://outlook.office365.com/api/beta/$metadata#Me/Messages('AAMkAGQ4Yzc2NDkwLTYxYmItNDZmYS1iZjI1LTYyNmY4NTZkMjI1NgBGAAAAAADwPSus7EwaR6q1wNtgoqEMBwDpfBfj8UPUTqu4bEwGpnFMAAAAAAEgAADpfBfj8UPUTqu4bEwGpnFMAAAjCUJGAAA%3D')/SingleValueExtendedProperties",
  "SingleValueExtendedProperties": [
    {
      "PropertyRef": "0x1090",
      "Type": "Integer",
      "Value": "2"
    }
  ]
}

Setting the flag is as simple as sending a PATCH to the message with that property in the SingleValueExtendedProperties collection:

New Format:

PATCH https://outlook.office365.com/api/beta/me/messages/{id}

{
  "SingleValueExtendedProperties": [
    {
      "PropertyId": "Integer 0x1090",
      "Value": "2"
    }
  ]
}

Old Format:

PATCH https://outlook.office365.com/api/beta/me/messages/{id}

{
  "SingleValueExtendedProperties": [
    {
      "PropertyRef": "0x1090",
      "Type": "Integer",
      "Value": "2"
    }
  ]
}

Finally, per MS-OXOFLAG, a value of 2 means flagged for follow up, and 1 means flag completed.