Send Email using MS Graph API

Set Up Azure Application

Create developer account

First, you need to set up the Microsoft Graph API configurations. You must create a Free Microsoft 365 DeveloperTenant account to register your Azure account and get the tenant ID, which is later required to send the email. After creating the account, copy the email address in the "Administrator" section and use it to sign up for Azure. 

Create Azure account 

After creating a Microsoft 365 Developer Tenant account, you can sign up on Azure using the email address you provided in the previous step. 

Sign up for your Azure account using the email in the Administrator section. You will then have full access to it.

Register application

Now, with the Azure account set up, we can begin registering an application. 

To register an application, go to Azure Active Directory > App Registrations > New Registration and do the following:

1. Choose a name for the app
2. Select your support type as Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g., Skype, Xbox)
3. Leave redirect URI blank 
4. Click Register 

After this, you should see in the app's overview that you have an Application (client) ID and a Directory (tenant) ID. Copy these IDs, which will be used later to send API calls using your app and account.

Get client secret

Next up is to get your client secret.

To generate a new client secret, from the app's overview page, go to Certificates and Secrets > New Client Secret and enter a description and expiry date for the client secret: 

After doing so, you should now have a value and ID. Copy these values into Notepad.

Add API permissions

The last thing to do is to give the Azure app permission to send emails via the Microsoft Graph API.

1. From the app's overview page, go to API Permissions > Add a Permission > Microsoft Graph > Application Permissions.
2. Use the search bar to search for Mail.
3. Select Mail.Send and tick the checkbox.
4. Optionally, tick User.Read.All if you want to see the list of users who can use this Azure app.
5. Click Add Permissions to grant the necessary permissions.

Using Joget JSON tool to call API

Joget JSON API Tool is a plugin included in the Process builder that lets you issue JSON web service calls. To properly send an email with the MS Graph API, you will need two JSON tools: one to request an access token and the other to send the email.

Requesting access token

According to Microsoft's documentation, Get access without a user. To acquire the access token, you need a POST request to the URL: https://login.microsoftonline.com/[TENANT ID HERE]/oauth2/v2.0/token.

So, enter the appropriate information into your first JSON Tool and keep the Body Type as Request Parameters.

Next up is to give the request the appropriate parameters; this request has to include the following:

• Client ID
• Client secret
• Grant type
• Scope

Following the steps above, you should have your client ID and secret. Enter those two values as client_id and client_secret.

For the grant type, in this guide, you are using the client credentials authentication flow, you are using this for this guide so that we don't need to worry about logging the user in when getting an access token. Enter the value client_credentials with the name grant_type.

And finally, for the scope, enter the link: https://graph.microsoft.com/.default

Other authentications flow would let you be more specific with your scope, like entering Mail.send but for client credentials it must have a value with the /.default suffixed to the application ID URI, which by default is https://graph.microsoft.com/. Enter the link to the value with the name scope.

The result of this request takes form of a JSON object, if your request was successful, the JSON object should look something like this:

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "ext_expires_in": 3599,
    "access_token": "412076657279206c6f6e67206a756d626c6564207069656365206f662074657874"
}

The "access_token" property of this JSON object is what we need for our second JSON tool, and for this guide, you will store this value in a Workflow Variable. You can create a workflow variable by going to the Process Property, which in Joget DX8, is accessible via the pencil icon beside your process' name.

Add as many variables as you need and name them appropriately.

Back at your JSON tool, scroll down to the Store to Workflow Variable setting and enter the variable of your choice and give the JSON object name "access_token".

Upon completion, you will have successfully requested and stored our access token for the second JSON tool.

Sending the email

According of Microsoft's documentation user: sendMail and Microsoft Graph to send mail with Client Credential Flow (application permission) and personal account. To send an email, we will need another POST request with the link: https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}/sendMail or https://graph.microsoft.com/v1.0/users/me/sendMail.

For this guide, you will use the first one since you use the client credentials flow, as explained above. Enter the appropriate information into your second JSON tool and make the Body Type a Custom JSON Payload.

Getting userPrincipalName via Azure

1. This id | userPrincipalName refers to the ID or principal name of the user that will be sending the email.
2. The format of an ID will be a 32-character long random string separated into 5 sections, while the format of a principal name will resemble an email address.
3. Most emails and IDs will be invalid when placed in the request link; check it in your Azure profile to see which emails are allowed.
4. From the Home screen, go to Azure Active Directory > Users.
5. You can see a list of all the valid users, typically filled with around a dozen dummy accounts and your account.
6. To ensure the request is valid, copy and paste your User Principal Name or any other name from that list into your request link.

Getting userPrincipalName and ID via GET request (optional)

1. Optionally, you can extract both the User Principal Name and their ID by making a GET request to the link: https://graph.microsoft.com/v1.0/users.
2. Feed this GET request with a non-expired access token.
3. If the request is successful, you will receive an array of JSON objects representing all users' information, including their User Principal Name and ID.
   
   Note that this process utilizes the optional API permission User.Read.All. For this guide, this method will not be used.

The JSON payload

After pasting the appropriate request link, it is time to feed it the JSON Payload.

This JSON payload should consist of simply one JSON object called message. In the documentation user: sendMail for this API, you could put many properties like custom HTML and file attachments. But the only property that the JSON object must have is the property toRecipients. Everything else can be left blank or deleted, and the request would still be valid, but of course, that wouldn't send a proper email, so put the properties you would typically find in an email, like a subject and content.

{
  "message": {
    "subject": "#variable.message_subject#",
    "body": {
      "contentType": "Text",
      "content": "#variable.message#"
    },
    "toRecipients": [
      {
        "emailAddress": {
          "address": "#variable.recipient_email#"
        }
      }
    ],
    "ccRecipients": [
    ]
  },
  "saveToSentItems": "false"
 }

Enter the appropriate information for each property. You could either hard code the information in the JSON object or use hash variables like in the code block above.

Request Headers

After the JSON payload, you must insert the request headers. For this request, it needs two things for their header, Content-type and Authorization. 

Content-type is used so the request knows what type of payload it is using, which, in our case, is a JSON object, so enter the value application/JSON.

Authorization as the name suggests, it is used to authorize the request. This is where you will use your access token; the value for this request header will be a string in the format [TOKEN_TYPE] [TOKEN], the type of token you are using will be a Bearer token, and you can simply copy and paste the token or use a hash variable to extract the token that was stored in the workflow variable.

Conclusion

You can send an email using the MS Graph API with a minimum of 2 JSON tools. By the end, your application's process should look like the picture below: 2 tools for requesting an access token and sending the email, and any additional activity for automating some of the processes, like the demo app, is for automating creating the message.

Related documentation

This guide will give you the knowledge to have full control over this process, but if you are just looking for the basic functionality of sending an email using the MS Graph API, then see to the Send Email with MS Graph Plugin Tool, which automates this entire process.

Download sample app