Automate creating, sending, and processing messages

Emails are represented by the message resource in Microsoft Graph.

By default, messages are identified by a unique entry ID in the id property. When a message is initially created and saved as a draft or sent, the store provider assigns the message an entry ID. By default, that ID changes when the message is copied or moved to another folder, store, or .PST file. You reference the message by its current ID for further processing.

Creating and sending mail

In Outlook, you can create and send an email in the same sendMail action, or you can create a draft, subsequently add content and send the draft.

Similarly, when responding to an email, you can create and send the response in the same action (reply, reply-all, or forward). Or, you can create a draft for the response (reply, reply-all, or forward), add content, and then send the draft at a later time.

To distinguish between a draft and a sent message programmatically, check the isDraft property.

By default, draft messages are saved in the Drafts folder, sent messages are saved in the Sent Items folder. For convenience, you can identify the Drafts folder and SentItems folder by their corresponding well-known folder names.

Setting the from and sender properties

When a message is being composed, in most cases, Outlook sets the from and sender properties to the same signed-in user. You can update these properties in the following scenarios:

  • The from property can be changed if the Exchange administrator has assigned sendAs rights of the mailbox to some other users. The administrator can do this by selecting Mailbox Permissions of the mailbox owner in the Azure portal, or by using the Exchange Admin Center or a Windows PowerShell Add-ADPermission cmdlet. Then, you can programmatically set the from property to one of these users who have sendAs rights for that mailbox.
  • The sender property can be changed if the mailbox owner has delegated one or more users to be able to send messages from that mailbox. The mailbox owner can delegate in Outlook. When a delegate sends a message on behalf of the mailbox owner, Outlook sets the sender property to the delegate‚Äôs account, and the from property remains as the mailbox owner. Programmatically, you can set the sender property to a user who has got delegate permissions for that mailbox.

Using MailTips to check recipient status and save time (preview)

Use MailTips to make smart decisions before sending an email. MailTips can tell you information such as the recipient's mailbox is restricted to specific senders, or approval is required for emailing the recipient.

Reading messages with control over the body format returned

You can read a message in a mailbox by referencing its ID:

GET /me/messages/AAMkADhMGAAA=

Or, you can get the messages in a specific folder. For example, to read messages in the signed-in user's Drafts folder:

GET /me/mailfolders('Drafts')

The body of an Outlook message can be either HTML or text, with HTML as the default message body type returned in a GET response.

When getting a message, you can specify the following request header to return the body and uniqueBody properties in text format:

Prefer: outlook.body-content-type="text"

You can specify the following header, or, just skip the header, to get the message body in HTML format:

Prefer: outlook.body-content-type="html"

When you specify either header, a successful response would include the corresponding Preference-Applied header:

  • For text format requests: Preference-Applied: outlook.body-content-type="text"
  • For HTML format requests: Preference-Applied: outlook.body-content-type="html"

If the body is HTML, by default, Outlook removes any potentially unsafe HTML (for example, JavaScript) embedded in the body property before returning the body content in a REST response.

To get the entire, original HTML content, include the following HTTP request header:

Prefer: outlook.allow-unsafe-html

Integrating with '@' social gesture (preview)

@-mentions are notifications to alert users if they are mentioned in messages. The mention resource enables apps to set and get the common online social gesture, the '@' prefix, in emails. You can:

Other shared capabilities

Take advantage of the following common capabilities that are shared among Microsoft Graph entities:

Next steps

Find out more about: