* Note: S/MIME message payloads are currently limited to 4 MB. Submission attempts that exceed this limit will result in anHTTP 413 Request Entity Too Large error response.
Permissions
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
HTTP request
POST /me/messages
POST /users/{id|userPrincipalName}/messages
POST /me/mailFolders/{id}/messages
POST /users/{id | userPrincipalName}/mailFolders/{id}/messages
Request headers
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.
Request body
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.
Response
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".
Examples
Example 1: Create a new message draft using JSON format
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.onmicrosoft.com"
}
}
]
}
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Message
{
Subject = "Did you see last night's game?",
Importance = Importance.Low,
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "They were <b>awesome</b>!",
},
ToRecipients = new List<Recipient>
{
new Recipient
{
EmailAddress = new EmailAddress
{
Address = "AdeleV@contoso.onmicrosoft.com",
},
},
},
};
var result = await graphClient.Me.Messages.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Message();
$requestBody->setSubject('Did you see last night\'s game?');
$requestBody->setImportance(new Importance('low'));
$body = new ItemBody();
$body->setContentType(new BodyType('html'));
$body->setContent('They were <b>awesome</b>!');
$requestBody->setBody($body);
$toRecipientsRecipient1 = new Recipient();
$toRecipientsRecipient1EmailAddress = new EmailAddress();
$toRecipientsRecipient1EmailAddress->setAddress('AdeleV@contoso.onmicrosoft.com');
$toRecipientsRecipient1->setEmailAddress($toRecipientsRecipient1EmailAddress);
$toRecipientsArray []= $toRecipientsRecipient1;
$requestBody->setToRecipients($toRecipientsArray);
$result = $graphServiceClient->me()->messages()->post($requestBody);
// THE PYTHON SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
client = GraphServiceClient(request_adapter)
request_body = Message()
request_body.subject = 'Did you see last night\'s game?'
request_body.importance(Importance.Low('importance.low'))
body = ItemBody()
body.contenttype(BodyType.HTML('bodytype.html'))
body.content = 'They were <b>awesome</b>!'
request_body.body = body
to_recipients_recipient1 = Recipient()
to_recipients_recipient1email_address = EmailAddress()
to_recipients_recipient1email_address.address = 'AdeleV@contoso.onmicrosoft.com'
to_recipients_recipient1.email_address = to_recipients_recipient1email_address
toRecipientsArray []= toRecipientsRecipient1;
request_body.torecipients(toRecipientsArray)
result = await client.me.messages.post(request_body = request_body)
// Code snippets are only available for the latest version. Current version is 5.x
var graphClient = new GraphServiceClient(requestAdapter);
var requestBody = new Message
{
Subject = "9/8/2018: concert",
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "The group represents Washington.",
},
ToRecipients = new List<Recipient>
{
new Recipient
{
EmailAddress = new EmailAddress
{
Address = "AlexW@contoso.OnMicrosoft.com",
},
},
},
InternetMessageHeaders = new List<InternetMessageHeader>
{
new InternetMessageHeader
{
Name = "x-custom-header-group-name",
Value = "Washington",
},
new InternetMessageHeader
{
Name = "x-custom-header-group-id",
Value = "WA001",
},
},
};
var result = await graphClient.Me.Messages.PostAsync(requestBody);
<?php
// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);
$requestBody = new Message();
$requestBody->setSubject('9/8/2018: concert');
$body = new ItemBody();
$body->setContentType(new BodyType('html'));
$body->setContent('The group represents Washington.');
$requestBody->setBody($body);
$toRecipientsRecipient1 = new Recipient();
$toRecipientsRecipient1EmailAddress = new EmailAddress();
$toRecipientsRecipient1EmailAddress->setAddress('AlexW@contoso.OnMicrosoft.com');
$toRecipientsRecipient1->setEmailAddress($toRecipientsRecipient1EmailAddress);
$toRecipientsArray []= $toRecipientsRecipient1;
$requestBody->setToRecipients($toRecipientsArray);
$internetMessageHeadersInternetMessageHeader1 = new InternetMessageHeader();
$internetMessageHeadersInternetMessageHeader1->setName('x-custom-header-group-name');
$internetMessageHeadersInternetMessageHeader1->setValue('Washington');
$internetMessageHeadersArray []= $internetMessageHeadersInternetMessageHeader1;
$internetMessageHeadersInternetMessageHeader2 = new InternetMessageHeader();
$internetMessageHeadersInternetMessageHeader2->setName('x-custom-header-group-id');
$internetMessageHeadersInternetMessageHeader2->setValue('WA001');
$internetMessageHeadersArray []= $internetMessageHeadersInternetMessageHeader2;
$requestBody->setInternetMessageHeaders($internetMessageHeadersArray);
$result = $graphServiceClient->me()->messages()->post($requestBody);
In the request body, supply a JSON representation of message object.
Response
Here is an example of 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.
POST https://graph.microsoft.com/v1.0/me/messages
Content-type: text/plain
Q29udGVudC1UeXBlOiBhcHBsaWNhdGlvbi9wa2NzNy1taW1lOw0KCW5hbWU9c21pbWUucDdtOw0KCXNtaW1lLXR5cGU9ZW52ZWxvcGVkLWRhdGENCk1pbWUtVmVyc2lvbjogMS4wIChNYWMgT1MgWCBNYWlsIDEzLjAgXCgzNjAxLjAuMTBcKSkNClN1YmplY3Q6IFJlOiBUZXN0aW5nIFMvTUlNRQ0KQ29udGVudC1EaXNwb3Np...