message resource type

A message in a mailbox folder.

Delta query support

This resource supports delta query to track incremental additions, deletions, and updates, by providing a delta function.

JSON representation

Here is a JSON representation of the resource

{
  "bccRecipients": [{"@odata.type": "microsoft.graph.recipient"}],
  "body": {"@odata.type": "microsoft.graph.itemBody"},
  "bodyPreview": "string",
  "categories": ["string"],
  "ccRecipients": [{"@odata.type": "microsoft.graph.recipient"}],
  "changeKey": "string",
  "conversationId": "string",
  "conversationIndex": "binary",
  "createdDateTime": "String (timestamp)",
  "flag": {"@odata.type": "microsoft.graph.followupFlag"},
  "from": {"@odata.type": "microsoft.graph.recipient"},
  "hasAttachments": true,
  "id": "string (identifier)",
  "importance": "String",
  "inferenceClassification": "String",
  "isDeliveryReceiptRequested": true,
  "isDraft": true,
  "isRead": true,
  "isReadReceiptRequested": true,
  "lastModifiedDateTime": "String (timestamp)",
  "mentionsPreview": {"@odata.type": "microsoft.graph.mentionsPreview"},
  "parentFolderId": "string",
  "receivedDateTime": "String (timestamp)",
  "replyTo": [{"@odata.type": "microsoft.graph.recipient"}],
  "sender": {"@odata.type": "microsoft.graph.recipient"},
  "sentDateTime": "String (timestamp)",
  "subject": "string",
  "toRecipients": [{"@odata.type": "microsoft.graph.recipient"}],
  "uniqueBody": {"@odata.type": "microsoft.graph.itemBody"},
  "UnsubscribeData": "string",
  "UnsubscribeEnabled": true,
  "webLink": "string"
}

Properties

Property Type Description
bccRecipients recipient collection The Bcc: recipients for the message.
body itemBody The body of the message.
bodyPreview String The first 255 characters of the message body.
categories String collection The categories associated with the message.
ccRecipients recipient collection The Cc: recipients for the message.
changeKey String The version of the message.
conversationId String The ID of the conversation the email belongs to.
conversationIndex Binary The Index of the conversation the email belongs to.
createdDateTime DateTimeOffset The date and time the message was created.
flag followUpFlag The flag value that indicates the status, start date, due date, or completion date for the message.
from recipient The mailbox owner and sender of the message.
hasAttachments Boolean Indicates whether the message has attachments.
id String Unique identifier for the message (note that this value may change if a message is moved or altered)
importance String The importance of the message: Low, Normal, High.
inferenceClassification String The classification of the message for the user, based on inferred relevance or importance, or on an explicit override. Possible values are: focused, other.
isDeliveryReceiptRequested Boolean Indicates whether a read receipt is requested for the message.
isDraft Boolean Indicates whether the message is a draft. A message is a draft if it hasn't been sent yet.
isRead Boolean Indicates whether the message has been read.
isReadReceiptRequested Boolean Indicates whether a read receipt is requested for the message.
lastModifiedDateTime DateTimeOffset The date and time the message was last changed.
mentionsPreview mentionsPreview Information about mentions in the message. When processing a GET /messages request, the server sets this property and includes it in the response by default. The server returns null if there are no mentions in the message. Optional.
parentFolderId String The unique identifier for the message's parent mailFolder.
receivedDateTime DateTimeOffset The date and time the message was received.
replyTo recipient collection The email addresses to use when replying.
sender recipient The account that is actually used to generate the message.
sentDateTime DateTimeOffset The date and time the message was sent.
subject String The subject of the message.
toRecipients recipient collection The To: recipients for the message.
uniqueBody itemBody The part of the body of the message that is unique to the current message.
unsubscribeData String The valid entries parsed from the List-Unsubscribe header. This is the data for the mail command in the List-Unsubscribe header if UnsubscribeEnabled property is true.
unsubscribeEnabled Boolean Indicates whether the message is enabled for unsubscribe. Its valueTrue if the list-Unsubscribe header conforms to rfc-2369.
webLink String The URL to open the message in Outlook Web App.

You can append an ispopout argument to the end of the URL to change how the message is displayed. If ispopout is not present or if it is set to 1, then the message is shown in a popout window. If ispopout is set to 0, then the browser will show the message in the Outlook Web App review pane.

The message will open in the browser if you are logged in to your mailbox via Outlook Web App. You will be prompted to login if you are not already logged in with the browser.

This URL can be accessed from within an iFrame.

Removing script from the Body property

The message body can be either HTML or text. If the body is HTML, by default, any potentially unsafe HTML (for example, JavaScript) embedded in the Body property would be removed before the body content is returned in a REST response. To get the entire, original HTML content, include the following HTTP request header:

Prefer: outlook.allow-unsafe-html

Setting the From and Sender properties

When a message is being composed, in most cases, the From and Sender properties represent the same signed-in user, unless either is updated as described in the following scenarios:

  • The From property can be changed if the Exchange administrator has assigned SendAs rights of the mailbox to some other users. The administrator can do this by selecting Mailbox Permissions of the mailbox owner in the Azure Management Portal, or by using the Exchange Admin Center or a Windows PowerShell Add-ADPermission cmdlet. Then, you can programmatically set the From property to one of these users who have SendAs rights for that mailbox.
  • The Sender property can be changed if the mailbox owner has delegated one or more users to be able to send messages from that mailbox. The mailbox owner can delegate in Outlook. When a delegate sends a message on behalf of the mailbox owner, the Sender property is set to the delegate‚Äôs account, and the From property remains as the mailbox owner. Programmatically, you can set the Sender property to a user who has got delegate right for that mailbox.

Relationships

Relationship Type Description
attachments Attachment collection The fileAttachment and itemAttachment attachments for the message.
extensions Extension collection Read-only. Nullable.
mentions mention collection A collection of mentions in the message, ordered by the createdDateTime from the newest to the oldest. By default, a GET /messages does not return this property unless you apply $expand on the property.
multiValueExtendedProperties multiValueLegacyExtendedProperty collection The collection of multi-value extended properties defined for the message. Read-only. Nullable.
singleValueExtendedProperties singleValueLegacyExtendedProperty collection The collection of single-value extended properties defined for the message. Read-only. Nullable.

Methods

Method Return Type Description
List messages message collection Get all the messages in the signed-in user's mailbox (excluding the Deleted Items and Clutter folders).
Create message message Create a draft of a new message.
Get message message Read properties and relationships of message object.
Update message Update message object.
Delete None Delete message object.
copy Message Copy a message to a folder.
createForward Message Create a draft forward message to include a comment or update any message properties all in one createForward call. You can then update or send the draft.
createReply Message Create a draft of a reply message to include a comment or update any message properties all in one createReply call. You can then update or send the draft.
createReplyAll Message Create a draft of a reply-all message to include a comment or update any message properties, all in one createReplyAll call. You can then update or send the draft.
delta message collection Get a set of messages that have been added, deleted, or updated in a specified folder.
forward None Forward a message, add a comment or modify any updateable properties all in one forward call. The message is then saved in the Sent Items folder.
move Message Move the message to a folder. This creates a new copy of the message in the destination folder.
reply None Reply to the sender of a message, add a comment or modify any updateable properties all in one reply call. The message is then saved in the Sent Items folder.
replyAll None Reply to all the recipients of a message by specifying a comment and modifying any updateable properties for the reply, all by using the replyAll method. The message is then saved in the Sent Items folder.
send None Sends a previously created message draft. The message is then saved in the Sent Items folder.
unsubscribe None Send a message using the data and address specified in the first mailto command in the List-Unsubscribe header.
Attachments
List attachments Attachment collection Get all attachments on a message.
Add attachment Attachment Add a new attachment to a message by posting to the attachments collection.
Data extensions
Create data extension openTypeExtension Create an open type data extension and add custom properties in a new or existing instance of a resource.
Get data extension openTypeExtension collection Get an openTypeExtension object or objects identified by name or fully qualified name.
Extended properties
Create single-value extended property message Create one or more single-value extended properties in a new or existing message.
Get message with single-value extended property message Get messages that contain a single-value extended property by using $expand or $filter.
Create multi-value extended property message Create one or more multi-value extended properties in a new or existing message.
Get message with multi-value extended property message Get a message that contains a multi-value extended property by using $expand.

See also