Send mail

  • 3 minutes to read
  • Contributors
    • Dan Kershaw [MSFT]
    • Andrew Omondi
    • Angelgolfer
    • Jeremy Thake (Microsoft)
    • Office GSX

Send the message specified in the request body. The message is saved in the Sent Items folder by default.

You can include a file attachment in the same sendMail action call.

Permissions

One of the following permissions is 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.Send
Delegated (personal Microsoft account) Mail.Send
Application Mail.Send

HTTP request

POST /me/sendMail
POST /users/{id | userPrincipalName}/sendMail

Request headers

Header Value
Authorization Bearer {token}. Required.
Content-Type application/json

Request body

In the request body, provide a JSON object with the following parameters.

Parameter Type Description
message Message The message to send. Required.
saveToSentItems Boolean Indicates whether to save the message in Sent Items. Specify it only if the parameter is false; default is true. Optional.

Response

If successful, this method returns 202 Accepted response code. It does not return anything in the response body.

Example

Here is an example of how to call this API.

Request 1

Here is an example of the request.

POST https://graph.microsoft.com/v1.0/me/sendMail
Content-type: application/json

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "fannyd@contoso.onmicrosoft.com"
        }
      }
    ],
    "ccRecipients": [
      {
        "emailAddress": {
          "address": "danas@contoso.onmicrosoft.com"
        }
      }
    ]
  },
  "saveToSentItems": "false"
}
Response 1

Here is an example of the response.

HTTP/1.1 202 Accepted

SDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var emailAddress = new EmailAddress
{
	Address = "danas@contoso.onmicrosoft.com",
};

var ccRecipients = new Recipient
{
	EmailAddress = emailAddress,
};

var ccRecipientsList = new List<Recipient>();
ccRecipientsList.Add( ccRecipients );

var emailAddress = new EmailAddress
{
	Address = "fannyd@contoso.onmicrosoft.com",
};

var toRecipients = new Recipient
{
	EmailAddress = emailAddress,
};

var toRecipientsList = new List<Recipient>();
toRecipientsList.Add( toRecipients );

var body = new ItemBody
{
	ContentType = BodyType.Text,
	Content = "The new cafeteria is open.",
};

var message = new Message
{
	Subject = "Meet for lunch?",
	Body = body,
	ToRecipients = toRecipientsList,
	CcRecipients = ccRecipientsList,
};

var saveToSentItems = "false";

await graphClient.Me
	.SendMail(message,saveToSentItems)
	.Request()
	.PostAsync()

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Request 2

The next example creates a message with custom Internet message headers and sends the message.

POST https://graph.microsoft.com/v1.0/me/sendMail
Content-type: application/json

{
  "message": {
    "subject": "9/9/2018: concert",
    "body": {
      "contentType": "HTML",
      "content": "The group represents Nevada."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "AlexW@contoso.OnMicrosoft.com"
        }
      }
    ],
    "internetMessageHeaders":[
      {
        "name":"x-custom-header-group-name",
        "value":"Nevada"
      },
      {
        "name":"x-custom-header-group-id",
        "value":"NV001"
      }
    ]
  }
}
Response 2

Here is an example of the response.

HTTP/1.1 202 Accepted

SDK sample code


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var internetMessageHeaders = new InternetMessageHeader
{
	Name = "x-custom-header-group-id",
	Value = "NV001",
};

var _internetMessageHeaders = new InternetMessageHeader
{
	Name = "x-custom-header-group-name",
	Value = "Nevada",
};

var internetMessageHeadersList = new List<InternetMessageHeader>();
internetMessageHeadersList.Add( _internetMessageHeaders );
internetMessageHeadersList.Add( internetMessageHeaders );

var emailAddress = new EmailAddress
{
	Address = "AlexW@contoso.OnMicrosoft.com",
};

var toRecipients = new Recipient
{
	EmailAddress = emailAddress,
};

var toRecipientsList = new List<Recipient>();
toRecipientsList.Add( toRecipients );

var body = new ItemBody
{
	ContentType = BodyType.Html,
	Content = "The group represents Nevada.",
};

var message = new Message
{
	Subject = "9/9/2018: concert",
	Body = body,
	ToRecipients = toRecipientsList,
	InternetMessageHeaders = internetMessageHeadersList,
};

await graphClient.Me
	.SendMail(message,saveToSentItems)
	.Request()
	.PostAsync()

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.