title | description | ms.localizationpriority | author | ms.subservice | doc_type |
---|---|---|---|---|---|
Create message |
Create a draft of a new message in either JSON or MIME format. |
high |
SuryaLashmiS |
outlook |
apiPageType |
Namespace: microsoft.graph
Create a draft of a new message in either JSON or MIME format.
When using JSON format, you can:
- Include an attachment to the message.
- Update the draft later to add content to the body or change other message properties.
When using MIME format:
- Provide the applicable Internet message headers and the MIME content, all encoded in base64 format in the request body.
- * Add any attachments and S/MIME properties to the MIME content.
By default, this operation saves the draft in the Drafts folder.
Send the draft message in a subsequent operation.
Alternatively, send a new message in a single operation, or create a draft to forward, reply and reply-all to an existing message.
* Note: S/MIME message payloads are currently limited to 4 MB. Submission attempts that exceed this limit will result in an
HTTP 413 Request Entity Too Large
error response.
[!INCLUDE national-cloud-support]
One of the following permissions are required to call this API. To learn more, including how to choose permissions, see Permissions.
Permission type | Permissions (from least to most privileged) |
---|---|
Delegated (work or school account) | Mail.ReadWrite |
Delegated (personal Microsoft account) | Mail.ReadWrite |
Application | Mail.ReadWrite |
POST /me/messages
POST /users/{id|userPrincipalName}/messages
POST /me/mailFolders/{id}/messages
POST /users/{id | userPrincipalName}/mailFolders/{id}/messages
Name | Type | Description |
---|---|---|
Authorization | string | Bearer {token}. Required. |
Content-Length | number | 0. Required. |
Content-Type | string | Nature of the data in the body of an entity. Required. Use application/json for a JSON object and text/plain for MIME content. |
When using JSON format, provide a JSON representation of message object.
When specifying the body in MIME format, provide the MIME content with the applicable Internet message headers ("To", "CC", "BCC", "Subject"), all encoded in base64 format in the request body.
Since the message resource supports extensions, you can use the POST
operation and add custom properties with your own data to the message while creating it.
If successful, this method returns 201 Created
response code and message object in the response body.
If the request body includes malformed MIME content, this method returns 400 Bad request
and the following error message: "Invalid base64 string for MIME content".
The following example shows a request.
POST https://graph.microsoft.com/v1.0/me/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":"AdeleV@contoso.com"
}
}
]
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
In the request body, supply a JSON representation of message object.
The following example shows the response. Note: The response object shown here might be shortened for readability.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('94447c6e-ea4c-494c-a9ed-d905e366c5cb')/messages/$entity",
"@odata.etag":"W/\"CQAAABYAAABK4UfANE/UR5clSilZtIuWAAC1vdti\"",
"id":"AAMkADNlNYjSAAA=",
"createdDateTime":"2017-07-22T01:53:56Z",
"lastModifiedDateTime":"2017-07-22T01:53:57Z",
"changeKey":"CQAAABYAAABK4UfANE/UR5clSilZtIuWAAC1vdti",
"categories":[
],
"receivedDateTime":"2017-07-22T01:53:57Z",
"sentDateTime":"2017-07-22T01:53:57Z",
"hasAttachments":false,
"internetMessageId":"<MWHPR1301MB@MWHPR1301MB.namprd13.prod.outlook.com>",
"subject":"Did you see last night's game?",
"bodyPreview":"They were awesome!",
"importance":"low",
"parentFolderId":"AAMkADNlNWAAAAAAEPAAA=",
"conversationId":"AAQkADNlNFdXGBnqtY=",
"conversationIndex":"AQHTe7/VAniOJVgCxEmtF1z6ZY1rFQ==",
"isDeliveryReceiptRequested":false,
"isReadReceiptRequested":false,
"isRead":true,
"isDraft":true,
"webLink":"https://outlook.office365.com/owa/?ItemID=AAMkADNlNYjSAAA%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":"Adele Vance",
"address":"AdeleV@contoso.com"
}
}
],
"ccRecipients":[
],
"bccRecipients":[
],
"replyTo":[
]
}
POST https://graph.microsoft.com/v1.0/me/messages
Content-type: application/json
{
"subject":"9/8/2018: concert",
"body":{
"contentType":"HTML",
"content":"The group represents Washington."
},
"toRecipients":[
{
"emailAddress":{
"address":"AlexW@contoso.com"
}
}
],
"internetMessageHeaders":[
{
"name":"x-custom-header-group-name",
"value":"Washington"
},
{
"name":"x-custom-header-group-id",
"value":"WA001"
}
]
}
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
In the request body, supply a JSON representation of message object.
The following example shows the response. Note: Internet message headers are not returned by default in a POST response. The response object shown here may also be truncated for brevity. All of the properties will be returned from an actual call.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('7f180cbb-a5ae-457c-b7e8-6f5b42ba33e7')/messages/$entity",
"@odata.etag":"W/\"CQAAABYAAAC4ofQHEIqCSbQPot83AFcbAAAnjjuE\"",
"id":"AAMkADhNmAAA=",
"createdDateTime":"2018-09-09T02:54:56Z",
"lastModifiedDateTime":"2018-09-09T02:54:56Z",
"changeKey":"CQAAABYAAAC4ofQHEIqCSbQPot83AFcbAAAnjjuE",
"categories":[
],
"receivedDateTime":"2018-09-09T02:54:56Z",
"sentDateTime":"2018-09-09T02:54:56Z",
"hasAttachments":false,
"internetMessageId":"<MWHPR220MB1120.namprd22.prod.outlook.com>",
"subject":"9/8/2018: concert",
"bodyPreview":"The group represents Washington.",
"importance":"normal",
"parentFolderId":"AAMkADhAAAAAAEPAAA=",
"conversationId":"AAQkADhNCuP8OKSm-0NE=",
"isDeliveryReceiptRequested":false,
"isReadReceiptRequested":false,
"isRead":true,
"isDraft":true,
"webLink":"https://outlook.office365.com/owa/?ItemID=AAMkADhNmAAA%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\nThe group represents Washington.\r\n</body>\r\n</html>\r\n"
},
"toRecipients":[
{
"emailAddress":{
"name":"Alex Wilber",
"address":"AlexW@contoso.com"
}
}
],
"ccRecipients":[
],
"bccRecipients":[
],
"replyTo":[
],
"flag":{
"flagStatus":"notFlagged"
}
}
POST https://graph.microsoft.com/v1.0/me/messages
Content-type: text/plain
Q29udGVudC1UeXBlOiBhcHBsaWNhdGlvbi9wa2NzNy1taW1lOw0KCW5hbWU9c21pbWUucDdtOw0KCXNtaW1lLXR5cGU9ZW52ZWxvcGVkLWRhdGENCk1pbWUtVmVyc2lvbjogMS4wIChNYWMgT1MgWCBNYWlsIDEzLjAgXCgzNjAxLjAuMTBcKSkNClN1YmplY3Q6IFJlOiBUZXN0aW5nIFMvTUlNRQ0KQ29udGVudC1EaXNwb3Np...
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
[!INCLUDE sample-code] [!INCLUDE sdk-documentation]
[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]
The following example shows the response.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('0aaa0aa0-0000-0a00-a00a-0000009000a0')/messages/$entity",
"@odata.etag": "W/\"AAAAAAAAAAAa00AAAa0aAaAa0a0AAAaAAAAaAa0a\"",
"id": "AAMkADA1MTAAAAqldOAAA=",
"createdDateTime": "2021-04-23T18:13:44Z",
"lastModifiedDateTime": "2021-04-23T18:13:44Z",
"changeKey": "AAAAAAAAAAAA00aaaa000aaA",
"categories": [],
"receivedDateTime": "2021-04-23T18:13:44Z",
"sentDateTime": "2021-02-28T07:15:00Z",
"hasAttachments": false,
"internetMessageId": "<AAAAAAAAAA@AAAAAAA0001AA0000.codcod00.prod.outlook.com>",
"subject": "Internal Resume Submission: Sales Associate",
"bodyPreview": "Hi, Megan.I have an interest in the Sales Associate position. Please consider my resume, which you can access here...",
"importance": "normal",
"parentFolderId": "LKJDSKJHkjhfakKJHFKWKKJHKJdhkjHDK==",
"conversationId": "SDSFSmFSDGI5LWZhYjc4fsdfsd=",
"conversationIndex": "Adfsdfsdfsdfw==",
"isDeliveryReceiptRequested": null,
"isReadReceiptRequested": false,
"isRead": true,
"isDraft": true,
"webLink": "https://outlook.office365.com/owa/?ItemID=AAMkAGNhOWAvsurl=1&viewmodel=ReadMessageItem",
"inferenceClassification": "focused",
"body": {
"contentType": "text",
"content": "Hi, Megan.I have an interest in the Sales Associate position. Please consider my resume, which you can access here... Regards,Alex"
},
"sender": {
"emailAddress": {
"name": "Alex Wilber",
"address": "AlexW@contoso.com"
}
},
"from": {
"emailAddress": {
"name": "Alex Wilber",
"address": "AlexW@contoso.com"
}
},
"toRecipients": [
{
"emailAddress": {
"name": "Megan Bowen",
"address": "MeganB@contoso.com"
}
}
],
"ccRecipients": [],
"bccRecipients": [],
"replyTo": [],
"flag": {
"flagStatus": "notFlagged"
}
}
If the request body includes malformed MIME content, this method returns the following error message.
HTTP/1.1 400 Bad Request
Content-type: application/json
{
"error": {
"code": "ErrorMimeContentInvalidBase64String",
"message": "Invalid base64 string for MIME content."
}
}