user: sendMail

Article
2024-06-22

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Send the message specified in the request body using either JSON or MIME format.

When using JSON format, you can include an attachment and use a mention to call out another user in the new message.

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.

This method saves the message in the Sent Items folder.

Alternatively, create a draft message to send later.

To learn more about the steps involved in the backend before a mail is delivered to recipients, see here.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type	Least privileged permissions	Higher privileged permissions
Delegated (work or school account)	Mail.Send	Not available.
Delegated (personal Microsoft account)	Mail.Send	Not available.
Application	Mail.Send	Not available.

HTTP request

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

Request headers

Name	Type	Description
Authorization	string	Bearer {token}. Required. Learn more about authentication and authorization.
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 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.

To use mention to call out another user in the new message:

Include the required toRecipients property, the mentions property, and any writable message properties in the request body.
For each mention in the mentions property, you must specify the mentioned property.

When specifying the body in MIME format, provide the MIME content as a base64-encoded string in the request body. Don't include parameters.

Response

If successful, this method returns 202 Accepted response code. It doesn't return anything in the response body.

Note: A 202 Accepted response code indicates that the request has been accepted; however, it does not indicate that the request processing has completed. Delivery of the message is subject to Exchange Online limitations and throttling.

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: Send a new email using JSON format

Request

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

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "[email protected]"
        }
      }
    ],
    "ccRecipients": [
      {
        "emailAddress": {
          "address": "[email protected]"
        }
      }
    ]
  },
  "saveToSentItems": "false"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Me.SendMail;
using Microsoft.Graph.Beta.Models;

var requestBody = new SendMailPostRequestBody
{
	Message = new Message
	{
		Subject = "Meet for lunch?",
		Body = new ItemBody
		{
			ContentType = BodyType.Text,
			Content = "The new cafeteria is open.",
		},
		ToRecipients = new List<Recipient>
		{
			new Recipient
			{
				EmailAddress = new EmailAddress
				{
					Address = "[email protected]",
				},
			},
		},
		CcRecipients = new List<Recipient>
		{
			new Recipient
			{
				EmailAddress = new EmailAddress
				{
					Address = "[email protected]",
				},
			},
		},
	},
	SaveToSentItems = false,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Me.SendMail.PostAsync(requestBody);

Important

Microsoft Graph SDKs use the v1.0 version of the API by default, and do not support all the types, properties, and APIs available in the beta version. For details about accessing the beta API with the SDK, see Use the Microsoft Graph SDKs with the beta API.

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta users send-mail post --user-id {user-id} --body '{\
  "message": {\
    "subject": "Meet for lunch?",\
    "body": {\
      "contentType": "Text",\
      "content": "The new cafeteria is open."\
    },\
    "toRecipients": [\
      {\
        "emailAddress": {\
          "address": "[email protected]"\
        }\
      }\
    ],\
    "ccRecipients": [\
      {\
        "emailAddress": {\
          "address": "[email protected]"\
        }\
      }\
    ]\
  },\
  "saveToSentItems": "false"\
}\
'

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphusers.NewItemSendMailPostRequestBody()
message := graphmodels.NewMessage()
subject := "Meet for lunch?"
message.SetSubject(&subject) 
body := graphmodels.NewItemBody()
contentType := graphmodels.TEXT_BODYTYPE 
body.SetContentType(&contentType) 
content := "The new cafeteria is open."
body.SetContent(&content) 
message.SetBody(body)


recipient := graphmodels.NewRecipient()
emailAddress := graphmodels.NewEmailAddress()
address := "[email protected]"
emailAddress.SetAddress(&address) 
recipient.SetEmailAddress(emailAddress)

toRecipients := []graphmodels.Recipientable {
	recipient,
}
message.SetToRecipients(toRecipients)


recipient := graphmodels.NewRecipient()
emailAddress := graphmodels.NewEmailAddress()
address := "[email protected]"
emailAddress.SetAddress(&address) 
recipient.SetEmailAddress(emailAddress)

ccRecipients := []graphmodels.Recipientable {
	recipient,
}
message.SetCcRecipients(ccRecipients)
requestBody.SetMessage(message)
saveToSentItems := false
requestBody.SetSaveToSentItems(&saveToSentItems) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Me().SendMail().Post(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody sendMailPostRequestBody = new com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody();
Message message = new Message();
message.setSubject("Meet for lunch?");
ItemBody body = new ItemBody();
body.setContentType(BodyType.Text);
body.setContent("The new cafeteria is open.");
message.setBody(body);
LinkedList<Recipient> toRecipients = new LinkedList<Recipient>();
Recipient recipient = new Recipient();
EmailAddress emailAddress = new EmailAddress();
emailAddress.setAddress("[email protected]");
recipient.setEmailAddress(emailAddress);
toRecipients.add(recipient);
message.setToRecipients(toRecipients);
LinkedList<Recipient> ccRecipients = new LinkedList<Recipient>();
Recipient recipient1 = new Recipient();
EmailAddress emailAddress1 = new EmailAddress();
emailAddress1.setAddress("[email protected]");
recipient1.setEmailAddress(emailAddress1);
ccRecipients.add(recipient1);
message.setCcRecipients(ccRecipients);
sendMailPostRequestBody.setMessage(message);
sendMailPostRequestBody.setSaveToSentItems(false);
graphClient.me().sendMail().post(sendMailPostRequestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const sendMail = {
  message: {
    subject: 'Meet for lunch?',
    body: {
      contentType: 'Text',
      content: 'The new cafeteria is open.'
    },
    toRecipients: [
      {
        emailAddress: {
          address: '[email protected]'
        }
      }
    ],
    ccRecipients: [
      {
        emailAddress: {
          address: '[email protected]'
        }
      }
    ]
  },
  saveToSentItems: 'false'
};

await client.api('/me/sendMail')
	.version('beta')
	.post(sendMail);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\SendMail\SendMailPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\Message;
use Microsoft\Graph\Beta\Generated\Models\ItemBody;
use Microsoft\Graph\Beta\Generated\Models\BodyType;
use Microsoft\Graph\Beta\Generated\Models\Recipient;
use Microsoft\Graph\Beta\Generated\Models\EmailAddress;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new SendMailPostRequestBody();
$message = new Message();
$message->setSubject('Meet for lunch?');
$messageBody = new ItemBody();
$messageBody->setContentType(new BodyType('text'));
$messageBody->setContent('The new cafeteria is open.');
$message->setBody($messageBody);
$toRecipientsRecipient1 = new Recipient();
$toRecipientsRecipient1EmailAddress = new EmailAddress();
$toRecipientsRecipient1EmailAddress->setAddress('[email protected]');
$toRecipientsRecipient1->setEmailAddress($toRecipientsRecipient1EmailAddress);
$toRecipientsArray []= $toRecipientsRecipient1;
$message->setToRecipients($toRecipientsArray);

$ccRecipientsRecipient1 = new Recipient();
$ccRecipientsRecipient1EmailAddress = new EmailAddress();
$ccRecipientsRecipient1EmailAddress->setAddress('[email protected]');
$ccRecipientsRecipient1->setEmailAddress($ccRecipientsRecipient1EmailAddress);
$ccRecipientsArray []= $ccRecipientsRecipient1;
$message->setCcRecipients($ccRecipientsArray);

$requestBody->setMessage($message);
$requestBody->setSaveToSentItems(false);

$graphServiceClient->me()->sendMail()->post($requestBody)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Users.Actions

$params = @{
	message = @{
		subject = "Meet for lunch?"
		body = @{
			contentType = "Text"
			content = "The new cafeteria is open."
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "[email protected]"
				}
			}
		)
		ccRecipients = @(
			@{
				emailAddress = @{
					address = "[email protected]"
				}
			}
		)
	}
	saveToSentItems = "false"
}

# A UPN can also be used as -UserId.
Send-MgBetaUserMail -UserId $userId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.send_mail.send_mail_post_request_body import SendMailPostRequestBody
from msgraph_beta.generated.models.message import Message
from msgraph_beta.generated.models.item_body import ItemBody
from msgraph_beta.generated.models.body_type import BodyType
from msgraph_beta.generated.models.recipient import Recipient
from msgraph_beta.generated.models.email_address import EmailAddress
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = SendMailPostRequestBody(
	message = Message(
		subject = "Meet for lunch?",
		body = ItemBody(
			content_type = BodyType.Text,
			content = "The new cafeteria is open.",
		),
		to_recipients = [
			Recipient(
				email_address = EmailAddress(
					address = "[email protected]",
				),
			),
		],
		cc_recipients = [
			Recipient(
				email_address = EmailAddress(
					address = "[email protected]",
				),
			),
		],
	),
	save_to_sent_items = False,
)

await graph_client.me.send_mail.post(request_body)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

HTTP/1.1 202 Accepted

Example 2: Send a message that includes an @-mention

This example shows a message by the signed-in user to Samantha Booth. The message also includes a mention of another user, Dana Swope.

Request

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

{
  "message": {
    "subject": "Project kickoff",
    "toRecipients": [
      {
        "emailAddress": {
          "name": "Samantha Booth",
          "address": "[email protected]"
        }
      }
    ],
    "mentions": [
      {
        "mentioned": {
          "name": "Dana Swope",
          "address": "[email protected]"
        }
      }
    ]
  }
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Me.SendMail;
using Microsoft.Graph.Beta.Models;

var requestBody = new SendMailPostRequestBody
{
	Message = new Message
	{
		Subject = "Project kickoff",
		ToRecipients = new List<Recipient>
		{
			new Recipient
			{
				EmailAddress = new EmailAddress
				{
					Name = "Samantha Booth",
					Address = "[email protected]",
				},
			},
		},
		Mentions = new List<Mention>
		{
			new Mention
			{
				Mentioned = new EmailAddress
				{
					Name = "Dana Swope",
					Address = "[email protected]",
				},
			},
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Me.SendMail.PostAsync(requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta users send-mail post --user-id {user-id} --body '{\
  "message": {\
    "subject": "Project kickoff",\
    "toRecipients": [\
      {\
        "emailAddress": {\
          "name": "Samantha Booth",\
          "address": "[email protected]"\
        }\
      }\
    ],\
    "mentions": [\
      {\
        "mentioned": {\
          "name": "Dana Swope",\
          "address": "[email protected]"\
        }\
      }\
    ]\
  }\
}\
'

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphusers.NewItemSendMailPostRequestBody()
message := graphmodels.NewMessage()
subject := "Project kickoff"
message.SetSubject(&subject) 


recipient := graphmodels.NewRecipient()
emailAddress := graphmodels.NewEmailAddress()
name := "Samantha Booth"
emailAddress.SetName(&name) 
address := "[email protected]"
emailAddress.SetAddress(&address) 
recipient.SetEmailAddress(emailAddress)

toRecipients := []graphmodels.Recipientable {
	recipient,
}
message.SetToRecipients(toRecipients)


mention := graphmodels.NewMention()
mentioned := graphmodels.NewEmailAddress()
name := "Dana Swope"
mentioned.SetName(&name) 
address := "[email protected]"
mentioned.SetAddress(&address) 
mention.SetMentioned(mentioned)

mentions := []graphmodels.Mentionable {
	mention,
}
message.SetMentions(mentions)
requestBody.SetMessage(message)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Me().SendMail().Post(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody sendMailPostRequestBody = new com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody();
Message message = new Message();
message.setSubject("Project kickoff");
LinkedList<Recipient> toRecipients = new LinkedList<Recipient>();
Recipient recipient = new Recipient();
EmailAddress emailAddress = new EmailAddress();
emailAddress.setName("Samantha Booth");
emailAddress.setAddress("[email protected]");
recipient.setEmailAddress(emailAddress);
toRecipients.add(recipient);
message.setToRecipients(toRecipients);
LinkedList<Mention> mentions = new LinkedList<Mention>();
Mention mention = new Mention();
EmailAddress mentioned = new EmailAddress();
mentioned.setName("Dana Swope");
mentioned.setAddress("[email protected]");
mention.setMentioned(mentioned);
mentions.add(mention);
message.setMentions(mentions);
sendMailPostRequestBody.setMessage(message);
graphClient.me().sendMail().post(sendMailPostRequestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const sendMail = {
  message: {
    subject: 'Project kickoff',
    toRecipients: [
      {
        emailAddress: {
          name: 'Samantha Booth',
          address: '[email protected]'
        }
      }
    ],
    mentions: [
      {
        mentioned: {
          name: 'Dana Swope',
          address: '[email protected]'
        }
      }
    ]
  }
};

await client.api('/me/sendMail')
	.version('beta')
	.post(sendMail);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\SendMail\SendMailPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\Message;
use Microsoft\Graph\Beta\Generated\Models\Recipient;
use Microsoft\Graph\Beta\Generated\Models\EmailAddress;
use Microsoft\Graph\Beta\Generated\Models\Mention;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new SendMailPostRequestBody();
$message = new Message();
$message->setSubject('Project kickoff');
$toRecipientsRecipient1 = new Recipient();
$toRecipientsRecipient1EmailAddress = new EmailAddress();
$toRecipientsRecipient1EmailAddress->setName('Samantha Booth');
$toRecipientsRecipient1EmailAddress->setAddress('[email protected]');
$toRecipientsRecipient1->setEmailAddress($toRecipientsRecipient1EmailAddress);
$toRecipientsArray []= $toRecipientsRecipient1;
$message->setToRecipients($toRecipientsArray);

$mentionsMention1 = new Mention();
$mentionsMention1Mentioned = new EmailAddress();
$mentionsMention1Mentioned->setName('Dana Swope');
$mentionsMention1Mentioned->setAddress('[email protected]');
$mentionsMention1->setMentioned($mentionsMention1Mentioned);
$mentionsArray []= $mentionsMention1;
$message->setMentions($mentionsArray);

$requestBody->setMessage($message);

$graphServiceClient->me()->sendMail()->post($requestBody)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Users.Actions

$params = @{
	message = @{
		subject = "Project kickoff"
		toRecipients = @(
			@{
				emailAddress = @{
					name = "Samantha Booth"
					address = "[email protected]"
				}
			}
		)
		mentions = @(
			@{
				mentioned = @{
					name = "Dana Swope"
					address = "[email protected]"
				}
			}
		)
	}
}

# A UPN can also be used as -UserId.
Send-MgBetaUserMail -UserId $userId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.send_mail.send_mail_post_request_body import SendMailPostRequestBody
from msgraph_beta.generated.models.message import Message
from msgraph_beta.generated.models.recipient import Recipient
from msgraph_beta.generated.models.email_address import EmailAddress
from msgraph_beta.generated.models.mention import Mention
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = SendMailPostRequestBody(
	message = Message(
		subject = "Project kickoff",
		to_recipients = [
			Recipient(
				email_address = EmailAddress(
					name = "Samantha Booth",
					address = "[email protected]",
				),
			),
		],
		mentions = [
			Mention(
				mentioned = EmailAddress(
					name = "Dana Swope",
					address = "[email protected]",
				),
			),
		],
	),
)

await graph_client.me.send_mail.post(request_body)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

HTTP/1.1 202 Accepted

Example 3: Send a message that includes custom Internet message headers

Request

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

{
  "message": {
    "subject": "9/9/2018: concert",
    "body": {
      "contentType": "HTML",
      "content": "The group represents Nevada."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "[email protected]"
        }
      }
    ],
    "internetMessageHeaders": [
      {
        "name": "x-custom-header-group-name",
        "value": "Nevada"
      },
      {
        "name": "x-custom-header-group-id",
        "value": "NV001"
      }
    ]
  }
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Me.SendMail;
using Microsoft.Graph.Beta.Models;

var requestBody = new SendMailPostRequestBody
{
	Message = new Message
	{
		Subject = "9/9/2018: concert",
		Body = new ItemBody
		{
			ContentType = BodyType.Html,
			Content = "The group represents Nevada.",
		},
		ToRecipients = new List<Recipient>
		{
			new Recipient
			{
				EmailAddress = new EmailAddress
				{
					Address = "[email protected]",
				},
			},
		},
		InternetMessageHeaders = new List<InternetMessageHeader>
		{
			new InternetMessageHeader
			{
				Name = "x-custom-header-group-name",
				Value = "Nevada",
			},
			new InternetMessageHeader
			{
				Name = "x-custom-header-group-id",
				Value = "NV001",
			},
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Me.SendMail.PostAsync(requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta users send-mail post --user-id {user-id} --body '{\
  "message": {\
    "subject": "9/9/2018: concert",\
    "body": {\
      "contentType": "HTML",\
      "content": "The group represents Nevada."\
    },\
    "toRecipients": [\
      {\
        "emailAddress": {\
          "address": "[email protected]"\
        }\
      }\
    ],\
    "internetMessageHeaders": [\
      {\
        "name": "x-custom-header-group-name",\
        "value": "Nevada"\
      },\
      {\
        "name": "x-custom-header-group-id",\
        "value": "NV001"\
      }\
    ]\
  }\
}\
'

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphusers.NewItemSendMailPostRequestBody()
message := graphmodels.NewMessage()
subject := "9/9/2018: concert"
message.SetSubject(&subject) 
body := graphmodels.NewItemBody()
contentType := graphmodels.HTML_BODYTYPE 
body.SetContentType(&contentType) 
content := "The group represents Nevada."
body.SetContent(&content) 
message.SetBody(body)


recipient := graphmodels.NewRecipient()
emailAddress := graphmodels.NewEmailAddress()
address := "[email protected]"
emailAddress.SetAddress(&address) 
recipient.SetEmailAddress(emailAddress)

toRecipients := []graphmodels.Recipientable {
	recipient,
}
message.SetToRecipients(toRecipients)


internetMessageHeader := graphmodels.NewInternetMessageHeader()
name := "x-custom-header-group-name"
internetMessageHeader.SetName(&name) 
value := "Nevada"
internetMessageHeader.SetValue(&value) 
internetMessageHeader1 := graphmodels.NewInternetMessageHeader()
name := "x-custom-header-group-id"
internetMessageHeader1.SetName(&name) 
value := "NV001"
internetMessageHeader1.SetValue(&value) 

internetMessageHeaders := []graphmodels.InternetMessageHeaderable {
	internetMessageHeader,
	internetMessageHeader1,
}
message.SetInternetMessageHeaders(internetMessageHeaders)
requestBody.SetMessage(message)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Me().SendMail().Post(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody sendMailPostRequestBody = new com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody();
Message message = new Message();
message.setSubject("9/9/2018: concert");
ItemBody body = new ItemBody();
body.setContentType(BodyType.Html);
body.setContent("The group represents Nevada.");
message.setBody(body);
LinkedList<Recipient> toRecipients = new LinkedList<Recipient>();
Recipient recipient = new Recipient();
EmailAddress emailAddress = new EmailAddress();
emailAddress.setAddress("[email protected]");
recipient.setEmailAddress(emailAddress);
toRecipients.add(recipient);
message.setToRecipients(toRecipients);
LinkedList<InternetMessageHeader> internetMessageHeaders = new LinkedList<InternetMessageHeader>();
InternetMessageHeader internetMessageHeader = new InternetMessageHeader();
internetMessageHeader.setName("x-custom-header-group-name");
internetMessageHeader.setValue("Nevada");
internetMessageHeaders.add(internetMessageHeader);
InternetMessageHeader internetMessageHeader1 = new InternetMessageHeader();
internetMessageHeader1.setName("x-custom-header-group-id");
internetMessageHeader1.setValue("NV001");
internetMessageHeaders.add(internetMessageHeader1);
message.setInternetMessageHeaders(internetMessageHeaders);
sendMailPostRequestBody.setMessage(message);
graphClient.me().sendMail().post(sendMailPostRequestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const sendMail = {
  message: {
    subject: '9/9/2018: concert',
    body: {
      contentType: 'HTML',
      content: 'The group represents Nevada.'
    },
    toRecipients: [
      {
        emailAddress: {
          address: '[email protected]'
        }
      }
    ],
    internetMessageHeaders: [
      {
        name: 'x-custom-header-group-name',
        value: 'Nevada'
      },
      {
        name: 'x-custom-header-group-id',
        value: 'NV001'
      }
    ]
  }
};

await client.api('/me/sendMail')
	.version('beta')
	.post(sendMail);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\SendMail\SendMailPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\Message;
use Microsoft\Graph\Beta\Generated\Models\ItemBody;
use Microsoft\Graph\Beta\Generated\Models\BodyType;
use Microsoft\Graph\Beta\Generated\Models\Recipient;
use Microsoft\Graph\Beta\Generated\Models\EmailAddress;
use Microsoft\Graph\Beta\Generated\Models\InternetMessageHeader;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new SendMailPostRequestBody();
$message = new Message();
$message->setSubject('9/9/2018: concert');
$messageBody = new ItemBody();
$messageBody->setContentType(new BodyType('hTML'));
$messageBody->setContent('The group represents Nevada.');
$message->setBody($messageBody);
$toRecipientsRecipient1 = new Recipient();
$toRecipientsRecipient1EmailAddress = new EmailAddress();
$toRecipientsRecipient1EmailAddress->setAddress('[email protected]');
$toRecipientsRecipient1->setEmailAddress($toRecipientsRecipient1EmailAddress);
$toRecipientsArray []= $toRecipientsRecipient1;
$message->setToRecipients($toRecipientsArray);

$internetMessageHeadersInternetMessageHeader1 = new InternetMessageHeader();
$internetMessageHeadersInternetMessageHeader1->setName('x-custom-header-group-name');
$internetMessageHeadersInternetMessageHeader1->setValue('Nevada');
$internetMessageHeadersArray []= $internetMessageHeadersInternetMessageHeader1;
$internetMessageHeadersInternetMessageHeader2 = new InternetMessageHeader();
$internetMessageHeadersInternetMessageHeader2->setName('x-custom-header-group-id');
$internetMessageHeadersInternetMessageHeader2->setValue('NV001');
$internetMessageHeadersArray []= $internetMessageHeadersInternetMessageHeader2;
$message->setInternetMessageHeaders($internetMessageHeadersArray);

$requestBody->setMessage($message);

$graphServiceClient->me()->sendMail()->post($requestBody)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Users.Actions

$params = @{
	message = @{
		subject = "9/9/2018: concert"
		body = @{
			contentType = "HTML"
			content = "The group represents Nevada."
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "[email protected]"
				}
			}
		)
		internetMessageHeaders = @(
			@{
				name = "x-custom-header-group-name"
				value = "Nevada"
			}
			@{
				name = "x-custom-header-group-id"
				value = "NV001"
			}
		)
	}
}

# A UPN can also be used as -UserId.
Send-MgBetaUserMail -UserId $userId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.send_mail.send_mail_post_request_body import SendMailPostRequestBody
from msgraph_beta.generated.models.message import Message
from msgraph_beta.generated.models.item_body import ItemBody
from msgraph_beta.generated.models.body_type import BodyType
from msgraph_beta.generated.models.recipient import Recipient
from msgraph_beta.generated.models.email_address import EmailAddress
from msgraph_beta.generated.models.internet_message_header import InternetMessageHeader
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = SendMailPostRequestBody(
	message = Message(
		subject = "9/9/2018: concert",
		body = ItemBody(
			content_type = BodyType.Html,
			content = "The group represents Nevada.",
		),
		to_recipients = [
			Recipient(
				email_address = EmailAddress(
					address = "[email protected]",
				),
			),
		],
		internet_message_headers = [
			InternetMessageHeader(
				name = "x-custom-header-group-name",
				value = "Nevada",
			),
			InternetMessageHeader(
				name = "x-custom-header-group-id",
				value = "NV001",
			),
		],
	),
)

await graph_client.me.send_mail.post(request_body)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

HTTP/1.1 202 Accepted

Example 4: Sends a message with a file attachment

Request

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

{
  "message": {
    "subject": "Meet for lunch?",
    "body": {
      "contentType": "Text",
      "content": "The new cafeteria is open."
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "[email protected]"
        }
      }
    ],
    "attachments": [
      {
        "@odata.type": "#microsoft.graph.fileAttachment",
        "name": "attachment.txt",
        "contentType": "text/plain",
        "contentBytes": "SGVsbG8gV29ybGQh"
      }
    ]
  }
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Me.SendMail;
using Microsoft.Graph.Beta.Models;

var requestBody = new SendMailPostRequestBody
{
	Message = new Message
	{
		Subject = "Meet for lunch?",
		Body = new ItemBody
		{
			ContentType = BodyType.Text,
			Content = "The new cafeteria is open.",
		},
		ToRecipients = new List<Recipient>
		{
			new Recipient
			{
				EmailAddress = new EmailAddress
				{
					Address = "[email protected]",
				},
			},
		},
		Attachments = new List<Attachment>
		{
			new FileAttachment
			{
				OdataType = "#microsoft.graph.fileAttachment",
				Name = "attachment.txt",
				ContentType = "text/plain",
				ContentBytes = Convert.FromBase64String("SGVsbG8gV29ybGQh"),
			},
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Me.SendMail.PostAsync(requestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc-beta users send-mail post --user-id {user-id} --body '{\
  "message": {\
    "subject": "Meet for lunch?",\
    "body": {\
      "contentType": "Text",\
      "content": "The new cafeteria is open."\
    },\
    "toRecipients": [\
      {\
        "emailAddress": {\
          "address": "[email protected]"\
        }\
      }\
    ],\
    "attachments": [\
      {\
        "@odata.type": "#microsoft.graph.fileAttachment",\
        "name": "attachment.txt",\
        "contentType": "text/plain",\
        "contentBytes": "SGVsbG8gV29ybGQh"\
      }\
    ]\
  }\
}\
'

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphusers.NewItemSendMailPostRequestBody()
message := graphmodels.NewMessage()
subject := "Meet for lunch?"
message.SetSubject(&subject) 
body := graphmodels.NewItemBody()
contentType := graphmodels.TEXT_BODYTYPE 
body.SetContentType(&contentType) 
content := "The new cafeteria is open."
body.SetContent(&content) 
message.SetBody(body)


recipient := graphmodels.NewRecipient()
emailAddress := graphmodels.NewEmailAddress()
address := "[email protected]"
emailAddress.SetAddress(&address) 
recipient.SetEmailAddress(emailAddress)

toRecipients := []graphmodels.Recipientable {
	recipient,
}
message.SetToRecipients(toRecipients)


attachment := graphmodels.NewFileAttachment()
name := "attachment.txt"
attachment.SetName(&name) 
contentType := "text/plain"
attachment.SetContentType(&contentType) 
contentBytes := []byte("sGVsbG8gV29ybGQh")
attachment.SetContentBytes(&contentBytes) 

attachments := []graphmodels.Attachmentable {
	attachment,
}
message.SetAttachments(attachments)
requestBody.SetMessage(message)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Me().SendMail().Post(context.Background(), requestBody, nil)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody sendMailPostRequestBody = new com.microsoft.graph.beta.users.item.sendmail.SendMailPostRequestBody();
Message message = new Message();
message.setSubject("Meet for lunch?");
ItemBody body = new ItemBody();
body.setContentType(BodyType.Text);
body.setContent("The new cafeteria is open.");
message.setBody(body);
LinkedList<Recipient> toRecipients = new LinkedList<Recipient>();
Recipient recipient = new Recipient();
EmailAddress emailAddress = new EmailAddress();
emailAddress.setAddress("[email protected]");
recipient.setEmailAddress(emailAddress);
toRecipients.add(recipient);
message.setToRecipients(toRecipients);
LinkedList<Attachment> attachments = new LinkedList<Attachment>();
FileAttachment attachment = new FileAttachment();
attachment.setOdataType("#microsoft.graph.fileAttachment");
attachment.setName("attachment.txt");
attachment.setContentType("text/plain");
byte[] contentBytes = Base64.getDecoder().decode("SGVsbG8gV29ybGQh");
attachment.setContentBytes(contentBytes);
attachments.add(attachment);
message.setAttachments(attachments);
sendMailPostRequestBody.setMessage(message);
graphClient.me().sendMail().post(sendMailPostRequestBody);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const sendMail = {
  message: {
    subject: 'Meet for lunch?',
    body: {
      contentType: 'Text',
      content: 'The new cafeteria is open.'
    },
    toRecipients: [
      {
        emailAddress: {
          address: '[email protected]'
        }
      }
    ],
    attachments: [
      {
        '@odata.type': '#microsoft.graph.fileAttachment',
        name: 'attachment.txt',
        contentType: 'text/plain',
        contentBytes: 'SGVsbG8gV29ybGQh'
      }
    ]
  }
};

await client.api('/me/sendMail')
	.version('beta')
	.post(sendMail);

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\SendMail\SendMailPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\Message;
use Microsoft\Graph\Beta\Generated\Models\ItemBody;
use Microsoft\Graph\Beta\Generated\Models\BodyType;
use Microsoft\Graph\Beta\Generated\Models\Recipient;
use Microsoft\Graph\Beta\Generated\Models\EmailAddress;
use Microsoft\Graph\Beta\Generated\Models\Attachment;
use Microsoft\Graph\Beta\Generated\Models\FileAttachment;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new SendMailPostRequestBody();
$message = new Message();
$message->setSubject('Meet for lunch?');
$messageBody = new ItemBody();
$messageBody->setContentType(new BodyType('text'));
$messageBody->setContent('The new cafeteria is open.');
$message->setBody($messageBody);
$toRecipientsRecipient1 = new Recipient();
$toRecipientsRecipient1EmailAddress = new EmailAddress();
$toRecipientsRecipient1EmailAddress->setAddress('[email protected]');
$toRecipientsRecipient1->setEmailAddress($toRecipientsRecipient1EmailAddress);
$toRecipientsArray []= $toRecipientsRecipient1;
$message->setToRecipients($toRecipientsArray);

$attachmentsAttachment1 = new FileAttachment();
$attachmentsAttachment1->setOdataType('#microsoft.graph.fileAttachment');
$attachmentsAttachment1->setName('attachment.txt');
$attachmentsAttachment1->setContentType('text/plain');
$attachmentsAttachment1->setContentBytes(\GuzzleHttp\Psr7\Utils::streamFor(base64_decode('SGVsbG8gV29ybGQh')));
$attachmentsArray []= $attachmentsAttachment1;
$message->setAttachments($attachmentsArray);

$requestBody->setMessage($message);

$graphServiceClient->me()->sendMail()->post($requestBody)->wait();

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Beta.Users.Actions

$params = @{
	message = @{
		subject = "Meet for lunch?"
		body = @{
			contentType = "Text"
			content = "The new cafeteria is open."
		}
		toRecipients = @(
			@{
				emailAddress = @{
					address = "[email protected]"
				}
			}
		)
		attachments = @(
			@{
				"@odata.type" = "#microsoft.graph.fileAttachment"
				name = "attachment.txt"
				contentType = "text/plain"
				contentBytes = "SGVsbG8gV29ybGQh"
			}
		)
	}
}

# A UPN can also be used as -UserId.
Send-MgBetaUserMail -UserId $userId -BodyParameter $params

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.send_mail.send_mail_post_request_body import SendMailPostRequestBody
from msgraph_beta.generated.models.message import Message
from msgraph_beta.generated.models.item_body import ItemBody
from msgraph_beta.generated.models.body_type import BodyType
from msgraph_beta.generated.models.recipient import Recipient
from msgraph_beta.generated.models.email_address import EmailAddress
from msgraph_beta.generated.models.attachment import Attachment
from msgraph_beta.generated.models.file_attachment import FileAttachment
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = SendMailPostRequestBody(
	message = Message(
		subject = "Meet for lunch?",
		body = ItemBody(
			content_type = BodyType.Text,
			content = "The new cafeteria is open.",
		),
		to_recipients = [
			Recipient(
				email_address = EmailAddress(
					address = "[email protected]",
				),
			),
		],
		attachments = [
			FileAttachment(
				odata_type = "#microsoft.graph.fileAttachment",
				name = "attachment.txt",
				content_type = "text/plain",
				content_bytes = base64.urlsafe_b64decode("SGVsbG8gV29ybGQh"),
			),
		],
	),
)

await graph_client.me.send_mail.post(request_body)

Important

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

HTTP/1.1 202 Accepted

Example 5: Send a new message using MIME format

Request

POST https://graph.microsoft.com/beta/me/sendMail
Content-type: text/plain

RnJvbTogQWRlbGUgVmFuY2UgPEFkZWxlVkBjb250b3NvLmNvbT4KVG86IEFsZXggV2lsYmVyIDxB
bGV4V0Bjb250b3NvLmNvbT4KU3ViamVjdDpUZXN0IE1lc3NhZ2UKQ29udGVudC1UeXBlOiBtdWx0
aXBhcnQvbWl4ZWQ7Cglib3VuZGFyeT0iXzAwNF9UWVpQUjA0TUI2OTgxNzNGRDAwMjE1MkQ1QURC
OEZCNDdDOEJDQVRZWlBSMDRNQjY5ODFhcGNwXyIKTUlNRS1WZXJzaW9uOiAxLjAKCi0tXzAwNF9U
WVpQUjA0TUI2OTgxNzNGRDAwMjE1MkQ1QURCOEZCNDdDOEJDQVRZWlBSMDRNQjY5ODFhcGNwXwpD
b250ZW50LVR5cGU6IG11bHRpcGFydC9hbHRlcm5hdGl2ZTsKCWJvdW5kYXJ5PSJfMDAwX1RZWlBS
MDRNQjY5ODE3M0ZEMDAyMTUyRDVBREI4RkI0N0M4QkNBVFlaUFIwNE1CNjk4MWFwY3BfIgoKLS1f
MDAwX1RZWlBSMDRNQjY5ODE3M0ZEMDAyMTUyRDVBREI4RkI0N0M4QkNBVFlaUFIwNE1CNjk4MWFw
Y3BfCkNvbnRlbnQtVHlwZTogdGV4dC9wbGFpbjsgY2hhcnNldD0iaXNvLTg4NTktMSIKQ29udGVu
dC1UcmFuc2Zlci1FbmNvZGluZzogcXVvdGVkLXByaW50YWJsZQoKdGVzdCB0ZXh0IGJvZHkKCgot
LV8wMDBfVFlaUFIwNE1CNjk4MTczRkQwMDIxNTJENUFEQjhGQjQ3QzhCQ0FUWVpQUjA0TUI2OTgx
YXBjcF8KQ29udGVudC1UeXBlOiB0ZXh0L2h0bWw7IGNoYXJzZXQ9Imlzby04ODU5LTEiCkNvbnRl
bnQtVHJhbnNmZXItRW5jb2Rpbmc6IHF1b3RlZC1wcmludGFibGUKCjxodG1sPgo8aGVhZD4KPC9o
ZWFkPgo8Ym9keT4KdGVzdCBodG1sIGJvZHkKPC9ib2R5Pgo8L2h0bWw+CgotLV8wMDBfVFlaUFIw
NE1CNjk4MTczRkQwMDIxNTJENUFEQjhGQjQ3QzhCQ0FUWVpQUjA0TUI2OTgxYXBjcF8tLQoKLS1f
MDA0X1RZWlBSMDRNQjY5ODE3M0ZEMDAyMTUyRDVBREI4RkI0N0M4QkNBVFlaUFIwNE1CNjk4MWFw
Y3BfCkNvbnRlbnQtVHlwZTogdGV4dC9wbGFpbjsKQ29udGVudC1EaXNwb3NpdGlvbjogYXR0YWNo
bWVudDsKICAgICAgICBmaWxlbmFtZT0idGVzdC50eHQiCgp0aGlzIGlzIHRoZSBhdHRhY2htZW50
IHRleHQKCi0tXzAwNF9UWVpQUjA0TUI2OTgxNzNGRDAwMjE1MkQ1QURCOEZCNDdDOEJDQVRZWlBS
MDRNQjY5ODFhcGNwXy0t

Response

The following example shows the response.

HTTP/1.1 202 Accepted

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."
  }
}

Example 6: Send a new message flagged for follow-up

Request

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

{
  "subject": "Please respond by Friday",
  "toRecipients": [
    {
      "emailAddress": {
        "address": "[email protected]"
      }
    }
  ],
  "flag": {
    "flagStatus": "flagged",
    "startDateTime": {
      "dateTime": "2023-08-30T12:13:00",
      "timeZone": "Eastern Standard Time"
    },
    "dueDateTime": {
      "dateTime": "2023-09-01T17:00:00",
      "timeZone": "Eastern Standard Time"
    }
  }
}

Response

HTTP/1.1 202 Accepted

Share via

user: sendMail

Permissions

HTTP request

Request headers

Request body

Response

Examples

Example 1: Send a new email using JSON format

Request

Response

Example 2: Send a message that includes an @-mention

Request

Response

Example 3: Send a message that includes custom Internet message headers

Request

Response

Example 4: Sends a message with a file attachment

Request

Response

Example 5: Send a new message using MIME format

Request

Response

Example 6: Send a new message flagged for follow-up

Request

Response

Feedback

Additional resources