Sending mails with embedded images via the Microsoft Graph

February 24, 2016

The Microsoft Graph keeps getting better and better. Since it was released, a lot more endpoints and functionality has been added. In one of my applications I make use of the sendMail endpoint to send notification about progress updates. I wanted to improve the notification mail by embedding images into the mails. The information for this can be found in the documentation of the Microsoft Graph, but it involves going through a couple of pages and trying things out yourself as there is not a sample available.

Info: these are some useful pages - sendmail endpoint - attachment resource type - fileAttachment resource type

In this article I walk you through the process how you can send mails via the Microsoft Graph API with embedded images.

Mail message model

It all starts with the model of your mail message. All the properties that you can pass for a mail message can be found here:

On the documentation page you see a JSON sample object with its properties. Of course you do not to include all these properties when you want to send a mail. Also the sample shows you how to send an attachment, but not how to embed an image. The answer for this can be found in the fileAttachment resource type documentation. Here are the essential properties you will need in your mail model:

The most important part about the mail model is the Attachment class. This contains all the required properties for successfully including images to the mail.

Important: it is important to include the @odata.type for your attachment. If you do not include it, your request ends up in a bad request. If you want to embed an image, it has to be set to #microsoft.graph.fileAttachment.

Creating the mail message with an embedded image

If you already developed an application in the past where you were required to embed images in mails. You will know you have to work with Content-ID or CID references in the HTML mark-up. Once these CID references are in place, you have to link the images as a resource and specify the CID per attachment. This is no different when working with the Microsoft Graph. As you can see in the model, you can also specify the contentId property to the attachment.

First of all, you create the mail mark-up like this:

Note: as the image source I specified CID:thumbsUp. You will have to specify this CID reference when you add the attachment to the mail message.

Here is a sample of how you can build the mail message with the model specified above and the embedded image:

Important: in attachment I specify contentBytes and contentType of the image. ContentBytes is the binary contents of the file, also known as Base64. ContentType is the image type like image/png or image/jpeg.

Sending out the mail

Now you only need to send out the mail message. This can be done like this:

Note: this code makes use of a NuGet package called RestSharp which makes it easier to do rest calls from C#. You are free to use whatever you want.

When you run this code, it would give you the following result:

Mail message with an embedded image

Mail message with an embedded image

Sample application

I have created a sample application for this. You can find it on GitHub:

If you want to try this application, you will first have to create an Azure AD application and fill in the Client ID and Redirect URL in the app.config file. You will also have to add your tenant ID. This can be the domain name ( or the ID.