This post is a contribution from Manish Joshi, an engineer with the SharePoint Developer Support team
The purpose of this blog is to walk through the process of calling the Outlook Mail API to send messages in Office 365 and Outlook.com. These guide focuses on the OAuth and REST requests and responses. It will cover the sequence of requests and responses that an app can use to authenticate and send an email messages with file attached from a SharePoint Online list item.
Authentication is covered under:
https://docs.microsoft.com/en-us/outlook/rest/get-started
Note: The outlook endpoint used in this guide https://outlook.office.com/api/beta is beta endpoint and should not be used in Production.
The following sections demonstrate sending an email with attachment from SharePoint Online using the Outlook REST Endpoint. This involves 3 steps which are listed below.
POSTMAN calls:
Step 1: Creating an email message
This is a POST request to the endpoint https://outlook.office.com/api/v2.0/me/MailFolders/inbox/messages. The body of the request will contain details like subject, email body and recipient email address. Note the Id returned in the response. This will be used for subsequent requests.
POST:
https://outlook.office.com/api/v2.0/me/MailFolders/inbox/messages
Body:
{
"Subject": "Did you see last night's game?",
"Importance": "Low",
"Body": {
"ContentType": "HTML",
"Content": "They were <b>awesome</b>!"
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "garthf@spo.onmicrosoft.com"
}
}
]
}
Status:
201 Created
Response:
{
"@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages/$entity",
"@odata.id": "https://outlook.office.com/api/v2.0/Users('aaaa2e55-386a-4226-817b-c774a83bbbde@d6f932a7-5f74-41ed-8d92-b27004970770')/Messages('AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAA==')",
"@odata.etag": "W/\"CQAAABYAAAD4u6EvSxjoRYdXUVukcUWEAAPywecn\"",
"Id": "AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAA==",
"CreatedDateTime": "2017-10-24T23:11:27Z",
"LastModifiedDateTime": "2017-10-24T23:11:27Z",
"ChangeKey": "CQAAABYAAAD4u6EvSxjoRYdXUVukcUWEAAPywecn",
"Categories": [],
"ReceivedDateTime": "2017-10-24T23:11:27Z",
"SentDateTime": "2017-10-24T23:11:27Z",
"HasAttachments": false,
"InternetMessageId": "<CO1PR04MB553B61033EB47364785F9EBF6470@CO1PR04MB553.namprd04.prod.outlook.com>",
"Subject": "Did you see last night's game?",
"BodyPreview": "They were awesome!",
"Importance": "Low",
"ParentFolderId": "AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MAAuAAADKqbIbNdyOUuJz-wQyvCCegEA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA",
"ConversationId": "AAQkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MAAQAEp5UbZ0wvtDnnmReZjdsPc=",
"IsDeliveryReceiptRequested": false,
"IsReadReceiptRequested": false,
"IsRead": true,
"IsDraft": true,
"WebLink": "https://outlook.office365.com/owa/?ItemID=AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz%2FwQyvCCegcA%2BLuhL0sY6EWHV1FbpHFFhAAAAgENAAAA%2BLuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAA%3D%3D&exvsurl=1&viewmodel=ReadMessageItem",
"InferenceClassification": "Focused",
"Body": {
"ContentType": "HTML",
"Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nThey were <b>awesome</b>!\r\n</body>\r\n</html>\r\n"
},
"ToRecipients": [
{
"EmailAddress": {
"Name": "Garth Fort",
"Address": "GarthF@spo.onmicrosoft.com"
}
}
],
"CcRecipients": [],
"BccRecipients": [],
"ReplyTo": []
}
Step 2: Adding an Attachment to the previously created email
This is a post request to the endpoint https://outlook.office.com/api/beta/me/messages/<<messageID>>/attachments. <<messageID>> is the ID retrieved from Step 1. The body of the request will contain the path of the file In SPO/ODB to be attached.
POST:
https://outlook.office.com/api/beta/me/messages/AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAA==/attachments
Body:
{
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"Name": "Test1.txt",
"SourceUrl": "https://spo.sharepoint.com/sites/TestSite11/Lists/MarketPlace/Attachments/1/Test1.txt",
"ProviderType": "other",
"Permission": "Edit",
"IsFolder": "False"
}
Status:
201 Created
Response:
{
"@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAA%3D%3D')/Attachments/$entity",
"@odata.type": "#Microsoft.OutlookServices.ReferenceAttachment",
"@odata.id": "https://outlook.office.com/api/beta/Users('faaa2e55-386a-4226-817b-c774a83bbbde@d6f932a7-5f74-41ed-8d92-b27004970776')/Messages('AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAA==')/Attachments('AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAAESABAAJmVbtRdmnUu74pWlPdmpgA==')",
"Id": "AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAAESABAAJmVbtRdmnUu74pWlPdmpgA==",
"LastModifiedDateTime": "2017-10-24T23:12:03Z",
"Name": "Test1.txt",
"ContentType": "text/plain",
"Size": 362,
"IsInline": true,
"SourceUrl": "https://spo.sharepoint.com/sites/TestSite11/Lists/MarketPlace/Attachments/1/Test1.txt",
"ProviderType": "Other",
"ThumbnailUrl": null,
"PreviewUrl": null,
"Permission": "Edit",
"IsFolder": false
}
Step 3: Sending the email
The previous two steps involved creating an email message and adding an attachment. The final step is to send the email message. This is a post request to the endpoint https://outlook.office.com/api/beta/me/messages/<<messageID>>/send. The request and response body are empty in this case. The status will be "202 Accepted" if the email message has been successfully sent
POST:
https://outlook.office.com/api/beta/me/messages/AQMkADcwMzljMTUzLTJlMDktNGFiNy1hYzUwLWU5OGYzNzZiMWY1MABGAAADKqbIbNdyOUuJz-wQyvCCegcA_LuhL0sY6EWHV1FbpHFFhAAAAgENAAAA_LuhL0sY6EWHV1FbpHFFhAAD8kJ2LgAAAA==/send
Body:
Status:
202 Accepted
Response: