message resource type
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
A message in a mailbox folder.
The maximum total number of recipients included in the toRecipients, ccRecipients, and bccRecipients properties for a single email message sent from an Exchange Online mailbox is 500. For more information, see sending limits.
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-". After the message is sent, you can't modify the headers. To get the headers of a message, apply the
$selectquery 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 draft message | message | Create a draft of a new message. |
| Get message | message | Read properties and relationships of message object. |
| Update message | message | Update message object. |
| Delete message | None | Delete message object. |
| Copy message | Message | Copy a message to a folder. |
| Create draft to forward message | 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. |
| Create draft to reply | 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. |
| Create draft to reply-all | 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. |
| Get message delta | message collection | Get a set of messages that were added, deleted, or updated in a specified folder. |
| Forward message | 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. |
| Mark as junk | message | Mark a message as junk. This API adds the sender to the list of blocked senders and moves the message to the Junk Email folder, when moveToJunk is true. |
| Mark as not junk | message | Mark a message as not junk. This API removes the sender from the list of blocked senders and moves the message to the Inbox folder, when moveToInbox is true. |
| Move message | Message | Move the message to a folder. This API creates a new copy of the message in the destination folder. |
| Reply to message | 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. |
| Reply-all to message | 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 draft message | None | Sends a previously created message draft. The message is then saved in the Sent Items folder. |
| Recall message | message | Recall a message in the specified user's mailbox Sent Items folder. |
| Unsubscribe | None | Send a message using the data and address specified in the first mailto command in the List-Unsubscribe header. |
| Permanently delete | None | Permanently delete a message and place it in the Purges folder in the Recoverable Items folder in the user's mailbox. |
| 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. |
| Open extensions | ||
| Create open extension | openTypeExtension | Create an open extension and add custom properties to a new or existing resource. |
| Get open extension | openTypeExtension collection | Get an open extension identified by the extension name. |
| Extended properties | ||
| Create single-value property | message | Create one or more single-value extended properties in a new or existing message. |
| Get single-value property | message | Get messages that contain a single-value extended property by using $expand or $filter. |
| Create multi-value property | message | Create one or more multi-value extended properties in a new or existing message. |
| Get multi-value 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. If the message contains instances of mention, this property would contain a concatenation of these mentions as well. |
| 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 | Edm.Binary | Indicates the position of the message within the conversation. |
| createdDateTime | DateTimeOffset | The date and time the message was created. The date and time information uses ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. |
| flag | followupFlag | The flag value that indicates the status, start date, due date, or completion date for the message. |
| from | recipient | The owner of the mailbox from which the message is sent. In most cases, this value is the same as the sender property, except for sharing or delegation scenarios. 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. By default, this value changes when the item is moved from one container (such as a folder or calendar) to another. To change this behavior, use the Prefer: IdType="ImmutableId" header. See Get immutable identifiers for Outlook resources for more information. Read-only. |
| importance | importance | The importance of the message. The possible values are: low, normal, and high. |
| inferenceClassification | inferenceClassificationType | The classification of the message for the user, based on inferred relevance or importance, or on an explicit override. Possible values are: focused, 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 RFC5322. Updatable only if isDraft is true. |
| 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. The date and time information uses ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. |
| 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. The date and time information uses ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. |
| 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, for a shared calendar, or 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. The date and time information uses ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. |
| 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. |
| 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 on the web. 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, the browser shows the message in the Outlook on the web review pane. The message opens in the browser if you are signed in to your mailbox via Outlook on the web. You are prompted to sign in if you are not already signed in with the browser. This URL cannot 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. |
| 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. Nullable. |
| singleValueExtendedProperties | singleValueLegacyExtendedProperty collection | The collection of single-value extended properties defined for the message. Nullable. |
JSON representation
The following 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": "String (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",
"internetMessageHeaders": [{"@odata.type": "microsoft.graph.internetMessageHeader"}],
"internetMessageId": "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",
"attachments": [{"@odata.type": "microsoft.graph.attachment"}],
"extensions": [{"@odata.type": "microsoft.graph.extension"}],
"mentions": [{"@odata.type": "microsoft.graph.mention"}],
"multiValueExtendedProperties": [{"@odata.type": "microsoft.graph.multiValueLegacyExtendedProperty"}],
"singleValueExtendedProperties": [{"@odata.type": "microsoft.graph.singleValueLegacyExtendedProperty"}]
}