message resource type

A message in a mailFolder.

This resource supports:

  • Adding your own data as custom Internet message headers. Add custom headers only when creating a message, and name them starting with "x-". Once the message has been sent, you cannot modify the headers. To get the headers of a message, apply the $select query parameter in a get message operation.
  • Adding your own data as custom properties as extensions.
  • Subscribing to change notifications.
  • Using delta query to track incremental additions, deletions, and updates, by providing a delta function.

Methods

Method Return Type Description
List messages message collection Get all the messages in the signed-in user's mailbox (including 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 of the Forward message. You can then update or send the draft.
createReply Message Create a draft of the Reply message. You can then update or send the draft.
createReplyAll Message Create a draft of the Reply All message. 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. 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. The message is then saved in the Sent Items folder.
replyAll None Reply to all recipients of a message. 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.
Attachments
List attachments Attachment collection Gets all attachments on a message.
Add attachment Attachment Add a new attachment to a message by posting to the attachments collection.
Open extensions
Create open extension openTypeExtension Create an open extension and add custom properties in a new or existing instance of a resource.
Get open extension openTypeExtension collection Get an open extension object or objects identified by name or fully qualified name.
Schema extensions
Add schema extension values Create a schema extension definition and then use it to add custom typed data to a resource.
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.

Properties

Property Type Description
bccRecipients recipient collection The Bcc: recipients for the message.
body itemBody The body of the message. It can be in HTML or text format. Find out about safe HTML in a message body.
bodyPreview String The first 255 characters of the message body. It is in text format.
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.
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. The value must correspond to the actual mailbox used. Find out more about setting the from and sender properties of a message.
hasAttachments Boolean Indicates whether the message has attachments. This property doesn't include inline attachments, so if a message contains only inline attachments, this property is false. To verify the existence of inline attachments, parse the body property to look for a src attribute, such as <IMG src="cid:image001.jpg@01D26CD8.6C05F070">.
id String Unique identifier for the message (note that this value may change if a message is moved or altered)
importance importance The importance of the message: Low, Normal, High.
inferenceClassification inferenceClassificationType The classification of the message for the user, based on inferred relevance or importance, or on an explicit override. The possible values are: focused or other.
internetMessageHeaders internetMessageHeader collection A collection of message headers defined by RFC5322. The set includes message headers indicating the network path taken by a message from the sender to the recipient. It can also contain custom message headers that hold app data for the message.

Returned only on applying a $select query option. Read-only.
internetMessageId String The message ID in the format specified by RFC2822.
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.
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. In most cases, this value is the same as the from property. You can set this property to a different value when sending a message from a shared mailbox, or sending a message as a delegate. In any case, the value must correspond to the actual mailbox used. Find out more about setting the from and sender properties of a 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. uniqueBody is not returned by default but can be retrieved for a given message by use of the ?$select=uniqueBody query. It can be in HTML or text format.
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.

Relationships

Relationship Type Description
attachments attachment collection The fileAttachment and itemAttachment attachments for the message.
extensions extension collection The collection of open extensions defined for the message. Nullable.
multiValueExtendedProperties multiValueLegacyExtendedProperty collection The collection of multi-value extended properties defined for the message. Nullable.
singleValueExtendedProperties singleValueLegacyExtendedProperty collection The collection of single-value extended properties defined for the message. Nullable.

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",
  "createdDateTime": "String (timestamp)",
  "flag": {"@odata.type": "microsoft.graph.followupFlag"},
  "from": {"@odata.type": "microsoft.graph.recipient"},
  "hasAttachments": true,
  "id": "string (identifier)",
  "importance": "String",
  "inferenceClassification": "String",
  "internetMessageHeaders": [{"@odata.type": "microsoft.graph.internetMessageHeader"}],
  "internetMessageId": "String",
  "isDeliveryReceiptRequested": true,
  "isDraft": true,
  "isRead": true,
  "isReadReceiptRequested": true,
  "lastModifiedDateTime": "String (timestamp)",
  "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"},
  "webLink": "string",

  "attachments": [{"@odata.type": "microsoft.graph.attachment"}],
  "extensions": [{"@odata.type": "microsoft.graph.extension"}],
  "multiValueExtendedProperties": [{"@odata.type": "microsoft.graph.multiValueLegacyExtendedProperty"}],
  "singleValueExtendedProperties": [{"@odata.type": "microsoft.graph.singleValueLegacyExtendedProperty"}]
}

See also