[DEPRECATED] Outlook Mail REST API reference (version 1.0)
Applies to: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
Note
Version 1.0 of the Outlook REST API is deprecated.
As announced in October 2017, version 1.0 of the Outlook REST API has been deprecated. The v1.0 REST endpoint will be fully decommissioned, and the v1.0 documentation will be removed shortly afterwards. Migrate existing apps to use Microsoft Graph. See a comparison to start your migration.
The Outlook Mail API lets you read, create, and send messages and attachments, view and respond to event messages, and manage folders that are secured by Azure Active Directory in Office 365. It also provides the same functionality in Microsoft accounts, specifically in these domains: 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 v1.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.
All Mail API operations
Message operations
Messages are stored in mailbox folders, so message endpoints often include the folder that contains the message. A folder is either specified by ID or by one of the following well-known folder names: Inbox
, Drafts
, SentItems
, or DeletedItems
.
- Get messages
- Synchronize messages
- Create and send messages
- Reply or reply all to messages
- Forward new or drafted messages
- Update messages
- Delete messages
- Move or copy messages
- Manage Focused Inbox
- Manage @-Mentions (preview)
- Manage rules (preview)
- Unsubscribe (preview)
- Get language choices (preview)
- Get time zone choices (preview)
- Get mailbox settings
- Get auto reply settings
- Update auto reply settings
- Get MailTips (preview)
- Get attachments
- Create attachments
- Delete attachments
Folder operations
Mailbox folders can contain messages and other folders. You can get, create, change, delete, and manage folders. You can use the following well-known folder names instead of the ID to specify the corresponding folder: Inbox
, SentItems
, Drafts
, or DeletedItems
.
See also
Use the Mail REST API
Authentication
Like other Outlook REST API, for every request to the Mail 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 Mail API.
Version of API
The Mail REST API is supported in all versions of the Outlook REST API. The functionality may differ depending on the specific version.
Target user
All Mail API requests are performed on behalf of the signed-in user unless specified. A few API subsets, such as Focused Inbox API, can be performed on the signed-in user, or a user specified by a user ID, given the appropriate permissions.
See Use the Outlook REST API for more information common to all subsets of the Outlook REST API.
Get messages
You can get a message collection or an individual message from a mailbox folder.
Each message in the response contains multiple properties, including the Body property. The message body can be either text or HTML. 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
Currently, the GET operation returns message bodies in only HTML format.
Get a message collection
Minimum required scope
One of the following:
Note
The behavior of the operations in this section vary by version. Find out more by choosing a version under Office 365 REST API reference in the table of contents on the left.
Get a message collection from the Inbox.
GET https://outlook.office.com/api/v1.0/me/messages
You can also specify a folder in the user's mailbox and get the message collection from that folder.
GET https://outlook.office.com/api/v1.0/me/MailFolders/{folder_id}/messages
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name, if you're getting messages from a specific folder. |
Note
By default, each message in the response includes all its properties. Use $select
to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
The following example shows how to use $select
to specify returning only the Sender and Subject properties of each message in the response. Refer to the sample response in Get a message for a full list of properties that would be returned for a message if you don't use $select
.
Sample request
GET https://outlook.office.com/api/v1.0/me/folders/sentitems/messages/?$select=Sender,Subject
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Folders('sentitems')/Messages(Sender,Subject)",
"value": [
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2TIy-AAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqS\"",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEJAACd9nJ-tVysQos2hTfspaWRAAADTIzAAAA=",
"Subject": "Meeting Notes",
"Sender": {
"EmailAddress": {
"Name": "Alex D",
"Address": "/O=EXCHANGELABS/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=1A5F1737122542AEA595DF9590A1C6FD-ALEXD"
}
}
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2TIy-AAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP\"",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEJAACd9nJ-tVysQos2hTfspaWRAAADTIy-AAA=",
"Subject": "Contract Signing",
"Sender": {
"EmailAddress": {
"Name": "Alex D",
"Address": "/O=EXCHANGELABS/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=1A5F1737122542AEA595DF9590A1C6FD-ALEXD"
}
}
},
{
"@odata.type": "#Microsoft.OutlookServices.EventMessage",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGI2TIy-AAA=')",
"@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqJ\"",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEJAACd9nJ-tVysQos2hTfspaWRAAADTIy9AAA=",
"Subject": "Rob:Alex 1:1",
"Sender": {
"EmailAddress": {
"Name": "Alex D",
"Address": "/O=EXCHANGELABS/OU=EXCHANGE ADMINISTRATIVE GROUP (FYDIBOHF23SPDLT)/CN=RECIPIENTS/CN=1A5F1737122542AEA595DF9590A1C6FD-ALEXD"
}
}
}
]
}
Response type
The requested message collection.
Get a message
Minimum required scope
One of the following:
Get a message by ID.
GET https://outlook.office.com/api/v1.0/me/messages/{message_id}
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The message ID. |
Sample request
GET https://outlook.office.com/api/v1.0/me/messages/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAA=
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIKz\"",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAA=",
"ChangeKey": "CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTIKz",
"Categories": [],
"DateTimeCreated": "2014-10-20T00:41:57Z",
"DateTimeLastModified": "2014-10-20T00:41:57Z",
"Subject": "Re: Meeting Notes",
"BodyPreview": "________________________________________\nFrom: Alex D\nSent: Sunday, October 19, 2014 5:28 PM\nTo: Katie Jordan\nSubject: Meeting Notes\n\nPlease send me the meeting notes ASAP",
"Body": {
"ContentType": "Text",
"Content": "\n________________________________________\nFrom: Alex D\nSent: Sunday, October 19, 2014 5:28 PM\nTo: Katie Jordan\nSubject: Meeting Notes\n\nPlease send me the meeting notes ASAP\n"
},
"Importance": "Normal",
"HasAttachments": true,
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEMAAA=",
"From": {
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
},
"Sender": {
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAQAEmjRj3pwjRLrbymGMYyEto=",
"DateTimeReceived": "2014-10-20T00:41:57Z",
"DateTimeSent": "2014-10-20T00:41:53Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": false,
"IsRead": false
}
Response type
The requested message.
Note
By default, the response includes all the properties of the specified message. Use $select
to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
The following example shows how to use $select
to specify returning only the Sender and Subject properties of the message in the response.
GET https://outlook.office.com/api/v1.0/me/messages/AAMkAGEI5MTAAA=?$select=Sender,Subject
Synchronize messages
This feature is currently available in v2.0 and the beta version. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select either version.
Create and send messages
You can send a new message on the fly, or create a draft message and then send it. You can create drafts in any folder.
Send a new message on the fly
Minimum required scope
One of the following:
Send the message supplied in the request body by using the SendMail method. You can include one or more attachments in the same action call by specifying them in the Attachments collection property. You can also save the message in the Sent Items folder.
POST https://outlook.office.com/api/v1.0/me/sendmail
Required parameter | Type | Description |
---|---|---|
Body parameters | ||
Message | Message | The message to send. |
SavetoSentItems | boolean | Indicates whether to save the message in Sent Items. Default is true. |
Specify the Message parameter with the required ToRecipients property and any writable message properties in the request body. The SaveToSentItems parameter is required only if false.
Sample request
POST https://outlook.office.com/api/v1.0/me/sendmail
{
"Message": {
"Subject": "Meet for lunch?",
"Body": {
"ContentType": "Text",
"Content": "The new cafeteria is open."
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
}
}
],
"Attachments": [
{
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"Name": "menu.txt",
"ContentBytes": "bWFjIGFuZCBjaGVlc2UgdG9kYXk="
}
]
},
"SaveToSentItems": "false"
}
Sample response
Status code: 202
Create a draft message
Minimum required scope
One of the following:
Create a draft of a new message. Drafts can be created in any folder and optionally updated before sending. To save to the Drafts folder, use the /me/messages
shortcut.
POST https://outlook.office.com/api/v1.0/me/messages
POST https://outlook.office.com/api/v1.0/me/folders/{folder_id}/messages
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The destination folder ID, or the Inbox or Drafts well-known folder name. |
Specify any writable message properties in the request body.
Sample request
POST https://outlook.office.com/api/v1.0/me/folders/inbox/messages
Content-Type: application/json
{
"Subject": "Did you see last night's game?",
"Importance": "Low",
"Body": {
"ContentType": "HTML",
"Content": "They were <b>awesome</b>!"
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
}
}
]
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0Ag5\"",
"Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEPAAAmP1Ln1wcHRariNdTMGAO9AAASz7k0AAA=",
"ChangeKey": "CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0Ag5",
"Categories": [],
"DateTimeCreated": "2014-10-18T20:06:51Z",
"DateTimeLastModified": "2014-10-18T20:06:51Z",
"Subject": "Did you see last night's game?",
"BodyPreview": "They were awesome!",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nThey were <b>awesome</b>!\r\n</body>\r\n</html>\r\n"
},
"Importance": "Low",
"HasAttachments": false,
"ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEPAAA=",
"From": null,
"Sender": null,
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAQADXiGXoAtX9IubRTpv2hisc=",
"DateTimeReceived": "2014-10-18T20:06:51Z",
"DateTimeSent": "2014-10-18T20:06:51Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": true,
"IsRead": true
}
Response type
The draft message.
Send a draft message
Minimum required scope
One of the following:
Send a new message draft, a Reply draft, a Reply All draft, or a Forward draft by using the Send method. The message is then saved in the Sent Items folder.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/send
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the draft message to send. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0Mz7k0AAA=/send
Sample response
Status code: 202
Reply or reply all to messages
Note
The behavior of the operations in this section vary by version. Find out more by choosing a version under Office 365 REST API reference in the table of contents on the left.
You can reply with a comment on the fly, or you can first create a reply draft, then update and send the draft.
You can reply to only the sender of the message or reply to all recipients at once.
- Reply to sender on the fly
- Reply all on the fly
- Create a draft reply message
- Create a draft reply-all message
Reply to sender on the fly
Minimum required scope
One of the following:
Reply to the sender of a message by specifying a comment and using the Reply method. The message is then saved in the Sent Items folder.
Alternatively, if you need to modify any updateable properties for the reply, you can first create a draft reply message, update the message properties, and then send the reply.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/reply
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to reply to. |
Body parameters | ||
Comment | string | A comment to include. Can be an empty string. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0Mz8DmAAA=/reply
Content-Type: application/json
{
"Comment": "Sounds great! See you tomorrow."
}
Sample response
Status code: 202
Reply all on the fly
Minimum required scope
One of the following:
Reply to all recipients of a message by specifying a comment and using the ReplyAll method. The message is then saved in the Sent Items folder.
Alternatively, if you need to modify any updateable properties for the reply, you can first create a draft reply-all message, update the message properties, and then send the reply.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/replyall
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to reply to. |
Body parameters | ||
Comment | string | A comment to include. Can be an empty string. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0MSz8DmAAA=/replyall
Content-Type: application/json
{
"Comment": "Thanks for the heads up."
}
Sample response
Status code: 202
Create a draft reply message
Minimum required scope
One of the following:
Create a draft to reply to the specified message. You can then update the draft to add reply content to the body property or change other message properties, or simply send the draft.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/createreply
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to reply to. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkADA1MTAAAAqldOAAA=/createreply
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('86b6ceaf-57f7-4278-97c4-4da0a97f6cdb@70559e59-b378-49ea-8e53-07a3a3d27f5b')/Messages('AAMkADA1MTAAAH5JKoAAA=')",
"@odata.etag": "W/\"CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DO\"",
"Id": "AAMkADA1MTAAAH5JKoAAA=",
"CreatedDateTime": "2016-03-15T08:33:43Z",
"LastModifiedDateTime": "2016-03-15T08:33:43Z",
"ChangeKey": "CQAAABYAAADX8oL1Wa7jQbcPAHouCzswAAAH5/DO",
"Categories": [ ],
"ReceivedDateTime": "2016-03-15T08:33:43Z",
"SentDateTime": "2016-03-15T08:33:43Z",
"HasAttachments": false,
"InternetMessageId": "<DM2PR00MB00571796B16132601E1F286CF7890@DM2PR00MB0057.namprd00.prod.outlook.com>",
"Subject": "RE: Let's start a group",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<body>Fanny, would you name the group if the project is approved, please?\r\n<b>From:</b> Fanny Downs<br>\r\n<b>Sent:</b> Friday, March 4, 2016 12:23:35 AM<br>\r\n<b>To:</b> Admin<br>\r\n<b>Subject:</b> Re: Let's start a group</font>\r\n<p>That's a great idea!<br>\r\n</body>\r\n</html>"
},
"BodyPreview": "Fanny, would you name the group if the project is approved, please?\r\n________________________________\r\nFrom: Fanny Downs\r\nSent: Friday, March 4, 2016 12:23:35 AM\r\nTo: Admin\r\nSubject: Re: Let's start a group\r\n\r\n\r\nThat's a gre",
"Importance": "Normal",
"ParentFolderId": "AQMkADA1MTAAAAIBDwAAAA==",
"Sender": {
"EmailAddress": {
"Name": "Admin",
"Address": "admin@contoso.onmicrosoft.com"
}
},
"From": null,
"ToRecipients": [
{
"EmailAddress": {
"Name": "Fanny Downs",
"Address": "fannyd@contoso.onmicrosoft.com"
}
}
],
"CcRecipients": [ ],
"BccRecipients": [ ],
"ReplyTo": [ ],
"ConversationId": "AAQkADA1MTVGjIwpLvWmGtIo-aFE=",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": true,
"WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADA1MTAAAH5JKoAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
"MentionedMe": null,
"AppliedHashtagsPreview": null,
"LikesPreview": null,
"MentionsPreview": null,
"Mentioned": [ ],
"InferenceClassification": "Focused",
"UnsubscribeData": [ ],
"UnsubscribeEnabled": false,
"Flag": { "FlagStatus": "NotFlagged" }
}
Response type
The draft Reply message with the ToRecipient, IsDraft, and other appropriate properties prepopulated.
Create a draft reply-all message
Minimum required scope
One of the following:
Create a draft to reply to the sender and all the recipients of the specified message. You can then update the draft to add reply content to the body or change other message properties, or simply send the draft.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/createreplyall
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to reply to. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0Mz8DmAAA=/createreplyall
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE0Mz7k5AAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AhF\"",
"Id": "AAMkAGE0Mz7k5AAA=",
"ChangeKey": "CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AhF",
"Categories": [],
"CreatedDateTime": "2014-10-18T21:21:06Z",
"LastModifiedDateTime": "2014-10-18T21:21:06Z",
"Subject": "RE: Check out the new Office 365 APIs",
"BodyPreview": "If the project gets approved, please decide on the name.\r\n_________________________________\r\nFrom: Alex D\r\nSent: Saturday, October 18, 2014 9:18:18 PM\r\nTo: Katie Jordan; Garth Fort\r\nSubj",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n...</html>\r\n"
},
"Importance": "Normal",
"HasAttachments": false,
"ParentFolderId": "AAMkAGE0MAAEPAAA=",
"From": null,
"Sender": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
},
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Garth Fort"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGE0M3HbTkEU=",
"ReceivedDateTime": "2014-10-18T21:21:06Z",
"SentDateTime": "2014-10-18T21:21:06Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": true,
"IsRead": true
}
Response type
The draft Reply All message with the ToRecipient, IsDraft, and other appropriate properties prepopulated.
Forward new or drafted messages
Note
The behavior of the operations in this section vary by version. Find out more by choosing a version under Office 365 REST API reference in the table of contents on the left.
You can forward a message directly, or you can create a draft forward message, update, and then send it.
Forward a message directly
Minimum required scope
One of the following:
Forward a message by using the Forward method and optionally specifying a comment. The message is then saved in the Sent Items folder.
Alternatively, if you need to modify any updateable properties in the message to be forwarded, you can first create a draft forward message, update the message properties, and then send the reply.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/forward
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to forward. |
Body parameters | ||
Comment | string | A comment to include. Can be an empty string. |
ToRecipients | Collection(Recipient) | The list of recipients. |
Specify the Comment and ToRecipients parameters in the request body.
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0Mz8DmAAA=/forward
Content-Type: application/json
{
"Comment": "FYI",
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com"
}
},
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com"
}
}
]
}
Sample response
Status code: 202
Create a draft forward message
Minimum required scope
One of the following:
Create a draft to forward the specified message. You can then update the draft to add content to the body or change other message properties, or simply send the draft.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/createforward
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to forward. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0Mz8DmAAA=/createforward
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE0Mz7k6AAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AhG\"",
"Id": "AAMkAGE0Mz7k6AAA=",
"ChangeKey": "CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AhG",
"Categories": [],
"CreatedDateTime": "2016-03-15T08:42:10Z",
"LastModifiedDateTime": "2016-03-15T08:42:10Z",
"Subject": "FW: Let's start a group",
"BodyPreview": "Dana, just want to make sure you get this.\r\n________________________________\r\nFrom: Admin\r\nSent: Tuesday, March 15, 2016 6:47:54 AM\r\nTo: Fanny Downs; Randi Welch\r\nSubject: RE: Let's st",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n...</html>\r\n"
},
"Importance": "Normal",
"HasAttachments": false,
"ParentFolderId": "AAMkAGE0MAAEPAAA=",
"From": null,
"Sender": {
"EmailAddress": {
"Address": "'alexd@contoso.onmicrosoft.com'",
"Name": "Alex D"
}
},
"ToRecipients": [],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGE0M3HbTkEU=",
"ReceivedDateTime": "2016-03-15T08:42:10Z",
"SentDateTime": "2016-03-15T08:42:10Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": true,
"IsRead": true
}
Response type
The draft Forward message with IsDraft and appropriate properties prepopulated.
Update messages
Change writable properties on a message and save the changes.
Update a message
Minimum required scope
One of the following:
Change writable properties on a draft or existing message. Only the properties that you specify are changed.
PATCH https://outlook.office.com/api/v1.0/me/messages/{message_id}
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to update. |
Specify one or more writable message properties in the request body.
Sample request
PATCH https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEMAAAmP1Ln1wcHRariNdTMGAO9AAASz8S-AAA=
Content-Type: application/json
{
"Categories": [
"Orange category",
"Green category"
],
"IsRead": true
}
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AIP\"",
"Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MABGAAAAAAC_0WfqSjt_SqLtNkuO-bj1BwAmP1Ln1wcHRariNdTMGAO9AAAAAAEMAAAmP1Ln1wcHRariNdTMGAO9AAASz8S-AAA=",
"ChangeKey": "CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AIP",
"Categories": [
"Orange category",
"Green category"
],
"DateTimeCreated": "2014-10-17T17:12:15Z",
"DateTimeLastModified": "2014-10-19T03:24:35Z",
"Subject": "Meeting notes from today",
"BodyPreview": "See 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: 0px; margin-bottom: 0px; }--></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"color: rgb(0, 0, 0); font-family: Calibri,Arial,Helvetica,sans-serif; font-size: 12pt; background-color: rgb(255, 255, 255);\">\r\n<p>See attached</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
},
"Importance": "Normal",
"HasAttachments": true,
"ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEMAAA=",
"From": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"Sender": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAQANKneItHNYxNlwnKip-qvhs=",
"DateTimeReceived": "2014-10-17T17:12:15Z",
"DateTimeSent": "2014-10-17T17:12:12Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": false,
"IsRead": true
}
Response type
The updated message.
Delete messages
Note
Be careful when you delete messages. Deleted contents might not be recoverable. To learn more, see Deleting items.
Delete a message
Minimum required scope
One of the following:
DELETE https://outlook.office.com/api/v1.0/me/messages/{message_id}
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to delete. |
Sample request
DELETE https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0Mz8TBAAA=
Sample response
Status code: 204
Move or copy messages
You can move or copy a message to a folder.
Move a message
Minimum required scope
One of the following:
Move a message to a folder. This creates a new copy of the message in the destination folder.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/move
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to move. |
Body parameters | ||
DestinationId | string | The destination folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEJAACd9nJ-tVysQos2hTfspaWRAAADTIy-AAA=/move
Content-Type: application/json
{
"DestinationId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEJAAA="
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"@odata.etag": "W/\"CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP\"",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEJAACd9nJ-tVysQos2hTfspaWRAAADTshBhAAA=",
"ChangeKey": "CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP",
"Categories": [],
"DateTimeCreated": "2014-10-20T00:13:21Z",
"DateTimeLastModified": "2014-10-20T00:13:23Z",
"Subject": "Contract Signing",
"BodyPreview": "There will be a detailed legal review of Project Falcon once the contract is ready.",
"Body": {
"ContentType": "Text",
"Content": "There will be a detailed legal review of Project Falcon once the contract is ready."
},
"Importance": "Normal",
"HasAttachments": false,
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEJAAA=",
"From": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"Sender": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
},
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Garth Fort"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAQAKjRc0YJSUBJpofjWgitxag=",
"DateTimeReceived": "2014-10-20T00:13:21Z",
"DateTimeSent": "2014-10-20T00:13:21Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": false,
"IsRead": true
}
Response type
The message that was moved.
Copy a message
Minimum required scope
One of the following:
Copy a message to a folder.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/copy
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The ID of the message to copy. |
Body parameters | ||
DestinationId | string | The destination folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/v1.0/me/messages/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEJAACd9nJ-tVysQos2hTfspaWRAAADTIy-AAA=/copy
Content-Type: application/json
{
"DestinationId": "inbox"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"@odata.etag": "W/\"CQAAABYAAAAmP1Ln1wcHRariNdTMGAO9AAAS0AIS\"",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEJAACd9nJ-tVysQos2hTfspaWRAAADT8DtAAA=",
"ChangeKey": "CQAAABYAAACd9nJ/tVysQos2hTfspaWRAAADTJqP",
"Categories": [],
"DateTimeCreated": "2014-10-20T00:13:21Z",
"DateTimeLastModified": "2014-10-20T00:13:23Z",
"Subject": "Contract Signing",
"BodyPreview": "There will be a detailed legal review of Project Falcon once the contract is ready.",
"Body": {
"ContentType": "Text",
"Content": "There will be a detailed legal review of Project Falcon once the contract is ready."
},
"Importance": "Normal",
"HasAttachments": false,
"ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEMAAA=",
"From": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"Sender": {
"EmailAddress": {
"Address": "alexd@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Alex D"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "katiej@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Katie Jordan"
}
},
{
"EmailAddress": {
"Address": "garthf@a830edad9050849NDA1.onmicrosoft.com",
"Name": "Garth Fort"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": [],
"ConversationId": "AAQkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAQAKjRc0YJSUBJpofjWgitxag=",
"DateTimeReceived": "2014-10-20T00:13:21Z",
"DateTimeSent": "2014-10-20T00:13:21Z",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsDraft": false,
"IsRead": true
}
Response type
The new copy of the message.
Manage Focused Inbox
This feature is currently available in v2.0 and beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select one of these versions.
Manage @-Mentions (preview)
This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.
Manage rules (preview)
This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.
Unsubscribe (preview)
This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.
Get language choices (preview)
This feature is currently available in only beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.
Get time zone choices (preview)
This feature is currently available in only beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.
Get mailbox settings
This feature is currently available in v2.0 and beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select one of these versions.
Get auto reply settings
This feature is currently available in v2.0 and beta. To find out more, To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select one of these versions.
Update auto reply settings
This feature is currently available in v2.0 and beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select one of these versions.
Get MailTips (preview)
This feature is currently available in beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.
Get attachments
You can get an attachment collection or get an attachment. Attachments can be files (for example,
Get an attachment collection
Minimum required scope
One of the following:
Get the attachments from a particular message.
GET https://outlook.office.com/api/v1.0/me/messages/{message_id}/attachments
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The message ID. |
Note
By default, each attachment in the response includes all its properties corresponding to that attachment type. Use $select
to specify only those properties you need for best performance. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
Response type
An attachment collection which can be of the type FileAttachment or ItemAttachment.
Sample requests and responses
The following example shows how to use $select
to specify returning only the Name property of each file attachment in the response. Refer to the sample response in Get an attachment for a full list of properties that would be returned for an attachment if you don't use $select
.
Sample request
GET https://outlook.office.com/api/v1.0/me/messages/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAA=/attachments?$select=Name
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAA%3D')/Attachments",
"value": [
{
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAABEgAQANQEWV4bM8FIlPwxj4kShdM=",
"Name": "minutes.docx",
"ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"Size": 11585,
"IsInline": false,
"DateTimeLastModified": "2014-10-20T00:41:52Z",
"ContentId": null,
"ContentLocation": null,
"IsContactPhoto": false,
"ContentBytes": "UEsDBBQABgAIAAAAIQDCAAA4KQAAAAA="
}
]
}
The following example shows getting the only attachment which is an Outlook mail item. The response includes an attachment ID which is also the ID of the attached message.
GET https://outlook.office.com/api/v1.0/me/messages('AAMkADFiNTPAAA=')/attachments
Content-Type: application/json
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages('AAMkADFiNTPAAA%3D')/Attachments",
"value": [
{
"@odata.type": "#Microsoft.OutlookServices.ItemAttachment",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-20075df800e5@1717622f-1d94-4d0c-9d74-f907ad6677b4')/Messages('AAMkADFiNTPAAA=')/Attachments('AAMkADFiNTAUhhYuYi0=')",
"Id": "AAMkADFiNTAUhhYuYi0=",
"Name": "How to retrieve item attachment using Outlook REST API",
"ContentType": message/rfc822,
"Size": 71094,
"IsInline": false,
"DateTimeLastModified": "2015-09-24T05:57:59Z",
}
]
}
Get an attachment
Minimum required scope
One of the following:
Get an attachment from a particular message.
GET https://outlook.office.com/api/v1.0/me/messages/{message_id}/attachments/{attachment_id}
Note
See OData query parameters for filtering, sorting, and paging parameters.
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The message ID. |
attachment_id | string | The attachment ID. |
Note
By default, the response includes all the properties of the attachment. Use $select
to specify only those properties you need for best performance. Refer to Get an attachment collection for an example. The Id property is always returned. See OData query parameters for filtering, sorting, and paging parameters.
Response type
The requested file attachment or item attachment.
Sample request
GET https://outlook.office.com/api/v1.0/me/messages/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAA=/attachments/AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAABEgAQANQEWV4bM8FIlPwxj4kShdM=
Sample response
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Messages('AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQBGAAAAAADUuTJK1K9aTpCdqXop_4NaBwCd9nJ-tVysQos2hTfspaWRAAAAAAEMAACd9nJ-tVysQos2hTfspaWRAAADTHVSAAA%3D')/Attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.FileAttachment",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2j4kShdM=",
"Name": "minutes.docx",
"ContentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"Size": 11585,
"IsInline": false,
"DateTimeLastModified": "2014-10-20T00:41:52Z",
"ContentId": null,
"ContentLocation": null,
"IsContactPhoto": false,
"ContentBytes": "UEsDBBQABgAIAAAAIQDCAAA4KQAAAAA=",
}
Create attachments
You can create a file attachment or create an item attachment for a message.
Create a file attachment
Minimum required scope
One of the following:
Add a file attachment to a message.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/attachments
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The message ID. |
Body parameters | ||
@odata.type | string | #Microsoft.OutlookServices.FileAttachment |
Name | string | The name of the attachment. |
ContentBytes | binary | The file to attach. |
Specify the Name and ContentBytes parameters and any writable file attachment properties in the request body.
Response type
The new file attachment.
Create an item attachment
Minimum required scope
One of the following:
Add an item attachment to a message.
POST https://outlook.office.com/api/v1.0/me/messages/{message_id}/attachments
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The message ID. |
Body parameters | ||
@odata.type | string | #Microsoft.OutlookServices.ItemAttachment |
Name | string | The name of the attachment. |
Item | A Message or Event entity. | The item to attach. |
Specify the Name and Item parameters and any writable item attachment properties in the request body.
Response type
The new item attachment.
Create a reference attachment
Minimum required scope
One of the following:
Add a reference attachment to a message.
This feature is currently available in only the beta version. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select beta.
Delete attachments
Minimum required scope
One of the following:
Delete the specified attachment of a message. The attachment can be a file attachment or item attachment.
DELETE https://outlook.office.com/api/v1.0/me/messages/{message_id}/attachments/{attachment_id}
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
message_id | string | The message ID. |
attachment_id | string | The attachment ID. |
Sample request
DELETE https://outlook.office.com/api/v1.0/me/messages/AAMkAGE0Mz8S-AAA=/attachments/AAMkAGE0Mg67gL7o=
Sample response
Status code: 204
Get folders
You can get a folder collection or get a folder in the user's mailbox.
Get a folder collection
Minimum required scope
One of the following:
Get the folder collection under the root folder of the signed-in user (.../me/folders
), or under the specified folder. You can use the .../me/folders
shortcut to get the top-level folder collection and navigate to another folder.
GET https://outlook.office.com/api/v1.0/me/folders
GET https://outlook.office.com/api/v1.0/me/folders/{folder_id}/childfolders
Note
See OData query parameters for filtering, sorting, and paging parameters.
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name, if you're getting folders from a specific folder. |
Sample request
GET https://outlook.office.com/api/v1.0/me/folders
Sample response
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Folders",
"value": [
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEfAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Conversation Action Settings",
"ChildFolderCount": 0
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEKAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Deleted Items",
"ChildFolderCount": 0
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEPAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Drafts",
"ChildFolderCount": 0
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEMAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Inbox",
"ChildFolderCount": 0
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEQAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Journal",
"ChildFolderCount": 0
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEeAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Junk Email",
"ChildFolderCount": 0
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAERAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Notes",
"ChildFolderCount": 0
},
{
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAELAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Outbox",
"ChildFolderCount": 0
}
]
}
Response type
The requested folder collection.
Get a folder
Minimum required scope
One of the following:
Get a folder by ID.
GET https://outlook.office.com/api/v1.0/me/folders/{folder_id}
Note
See OData query parameters for filtering, sorting, and paging parameters.
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Sample request
GET https://outlook.office.com/api/v1.0/me/folders/inbox
Sample response
Status code: 200
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Folders/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEJAAA=",
"ParentFolderId": "AAMkAGI2NGVhZTVlLTI1OGMtNDI4My1iZmE5LTA5OGJiZGEzMTc0YQAuAAAAAADUuTJK1K9aTpCdqXop_4NaAQCd9nJ-tVysQos2hTfspaWRAAAAAAEIAAA=",
"DisplayName": "Inbox",
"ChildFolderCount": 0,
"UnreadItemCount": 2,
"TotalItemCount": 2
}
Response type
The requested folder.
Synchronize folder hierarchy
This feature is currently available in v2.0 and beta. To find out more, in the table of contents on the left, go to the Office 365 REST API reference section and select one of these versions.
Create folders
Add a new folder to a folder collection.
Create a folder
Minimum required scope
One of the following:
Create a child folder by the name specified in DisplayName. DisplayName is the only writable property for a folder.
POST https://outlook.office.com/api/v1.0/me/folders/{folder_id}/childfolders
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Body parameters | ||
DisplayName | string | The display name of the folder. |
Sample request
POST https://outlook.office.com/api/v1.0/me/folders/inbox/childfolders
Content-Type: application/json
{
"DisplayName": "Company"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Folders('inbox')/ChildFolders/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAASz-l_AAA=",
"ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEMAAA=",
"DisplayName": "Company",
"ChildFolderCount": 0,
"UnreadItemCount": 2,
"TotalItemCount": 27
}
Response type
The new folder.
Remarks
You can't create a top-level folder. You can only add a folder to a childfolders
endpoint.
Update folders
Change a folder name.
Update a folder
Minimum required scope
One of the following:
Change the folder name to that specified in DisplayName. The name is the only writable property for a folder.
PATCH https://outlook.office.com/api/v1.0/me/folders/{folder_id}
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Body parameters | ||
DisplayName | string | The new display name of the folder. |
Sample request
PATCH https://outlook.office.com/api/v1.0/me/folders/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAASz-l_AAA=
Content-Type: application/json
{
"DisplayName": "Business"
}
Sample response
Status code: 200
}
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Folders/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAASz-l_AAA=",
"ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEMAAA=",
"DisplayName": "Business",
"ChildFolderCount": 0,
"UnreadItemCount": 4,
"TotalItemCount": 38
}
Response type
The updated folder.
Delete folders
Delete a folder and all of its contents.
Note
Be careful when you delete folders. Deleted contents might not be recoverable. To learn more, see Deleting items.
Delete a folder
Minimum required scope
One of the following:
Delete the folder specified in folder_id.
DELETE https://outlook.office.com/api/v1.0/me/folders/{folder_id}
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Sample request
DELETE https://outlook.office.com/api/v1.0/me/MailFolders/AAMkAGE0Mz-l_AAA=
Sample response
Status code: 204
Move or copy folders
You can move or copy a folder to another folder.
Move a folder
Minimum required scope
One of the following:
Move a folder and its contents to another folder by using the Move method.
POST https://outlook.office.com/api/v1.0/me/folders/{folder_id}/move
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Body parameters | ||
DestinationId | string | The destination folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/v1.0/me/folders/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAASz-l_AAA=/move
Content-Type: application/json
{
"DestinationId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAOyxQ9AAA="
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Folders/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAASz-l_AAA=",
"ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAOyxQ9AAA=",
"DisplayName": "Business",
"ChildFolderCount": 0,
"UnreadItemCount": 4,
"TotalItemCount": 38
}
Response type
The folder that was moved.
Copy a folder
Minimum required scope
One of the following:
Copy a folder and its contents to another folder by using the Copy method.
POST https://outlook.office.com/api/v1.0/me/folders/{folder_id}/copy
Required parameter | Type | Description |
---|---|---|
URL parameters | ||
folder_id | string | The folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Body parameters | ||
DestinationId | string | The destination folder ID, or the Inbox , Drafts , SentItems , or DeletedItems well-known folder name. |
Sample request
POST https://outlook.office.com/api/v1.0/me/folders/AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAASz-l_AAA=/copy
Content-Type: application/json
{
"DestinationId": "inbox"
}
Sample response
Status code: 201
{
"@odata.context": "https://outlook.office.com/api/v1.0/$metadata#Me/Folders/$entity",
"@odata.id": "https://outlook.office.com/api/v1.0/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE4v1RAAA=')",
"Id": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAASz-mAAAA=",
"ParentFolderId": "AAMkAGE0MGM1Y2M5LWEzMmUtNGVlNy05MjRlLTk0YmJjYzVkN2I5MAAuAAAAAAC_0WfqSjt_SqLtNkuO-bj1AQAmP1Ln1wcHRariNdTMGAO9AAAAAAEMAAA=",
"DisplayName": "Business",
"ChildFolderCount": 0,
"UnreadItemCount": 4,
"TotalItemCount": 38
}
Response type
The new copy of the folder.
Next steps
Whether you're ready to start building an app or just want to learn more, we've got you covered.
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
- Calendar API reference
- Contacts API reference
- Task REST API (preview)
- OneDrive API
- Discovery Service REST API operations reference
- Resource reference for the Mail, Calendar, Contacts, and Task REST APIs