Mentions
Mentions are a special kind of notification which is sent to a person based on the person’s email address. Mentions are part of the message api. Known also as @mentions.
Availability
The Graph API exposes two versions, v1.0 and beta.
Currently, mentions are supported only in beta version.
The message resource type has
mentionsPreviewproperty: inner propertyisMentionedindicates whether the signed-in user is mentioned in the messagementionsrelationship: details about people mentioned in the message
The examples bellow will show code snippets for .NET and Microsoft.Graph.Beta NuGet package.
Features
With the message api, you can
- Check who was mentioned in a message
- Filter messages where the signed-in user was mentioned
- Add mentions to a message
- Remove mentions from a message
Not supported features:
- Filtering messages where a different user than actually signed-in user was mentioned
- Using the property
mentionsPreviewin$selectquery parameter
Based on the things above:
GET beta/me/messages?$expand=mentions($filter=mentioned/address eq 'john.doe@contoso.com')
returns all messages.
Filter on mentioned collection
GET beta/me/messages?$filter=mentions/any(m:m/mentioned/address eq 'john.doe@contoso.com')
is not applied.
An attempt to explicitly return mentionsPreview
GET beta/me/messages?$select=id,mentionsPreview
fails with the error code 400 Bad Request.
Check people mentioned in messages
To check who was mentioned in message, simply expand mentions navigation property
GET beta/me/messages?$expand=mentions&$select=subject,from,body
C# code:
var graphClient = new GraphServiceClient(credential);
var response = await graphClient.Me.Messages.GetAsync(req =>
{
req.QueryParameters.Select = new[] { "subject", "from", "body" };
req.QueryParameters.Expand = new[] { "mentions" };
});
var messages = new List<Message>();
var iterator = PageIterator<Message, MessageCollectionResponse>.CreatePageIterator(graphClient, response, m =>
{
messages.Add(m);
return true;
});
await iterator.IterateAsync();
foreach (var message in messages.Where(x => x.Mentions?.Count > 0))
{
Console.WriteLine($"From: {message.From.EmailAddress.Address}");
Console.WriteLine($"Subject: {message.From.EmailAddress.Address}");
Console.WriteLine("Mentioned people:");
foreach (var mention in message.Mentions)
{
Console.WriteLine($"{mention.Mentioned.Address} mentioned by {mention.CreatedBy}: {mention.MentionText}");
}
}
Filter messages with mentions
To get all messages where the signed-in user was mentioned, send the request with the filter
GET beta/me/messages?$filter=mentionsPreview/isMentioned eq true&$expand=mentions&$select=subject,from,body
C# code:
var graphClient = new GraphServiceClient(credential);
var response = await graphClient.Me.Messages.GetAsync(req =>
{
req.QueryParameters.Select = new[] { "subject", "from", "body" };
req.QueryParameters.Filter = "mentionsPreview/isMentioned eq true";
req.QueryParameters.Expand = new[] { "mentions" };
});
var messages = new List<Message>();
var iterator = PageIterator<Message, MessageCollectionResponse>.CreatePageIterator(graphClient, response, m =>
{
messages.Add(m);
return true;
});
await iterator.IterateAsync();
foreach (var message in messages)
{
Console.WriteLine($"From: {message.From.EmailAddress.Address}");
Console.WriteLine($"Subject: {message.From.EmailAddress.Address}");
Console.WriteLine("Mentioned people:");
foreach (var mention in message.Mentions)
{
Console.WriteLine($"{mention.Mentioned.Address} mentioned by {mention.CreatedBy}: {mention.MentionText}");
}
}
Add mentions
When you want to mention some person, you need to
- add a person to the recipients collection to ensure that the person will receive that email
- add a person to the mentioned collection to notify that the person was mentioned
Create a draft with mentions
Create a new message and fill details about mentioned people. Add all mentioned people to toRecipients collection, otherwise they will not receive an email
POST beta/me/messages
{
"subject": "The incident",
"body": {
"contentType": "Html",
"content": "Hi Adele, send me the report. You <a href=\"john.doe@contoso.com\">@John Doe</a> prepare the report about the incident"
},
"toRecipients": [
{
"emailAddress": {
"address": "john.doe@contoso.com"
}
},
{
"emailAddress": {
"address": "adele.vance@contoso.com"
}
}
],
"mentions": [
{
"mentioned": {
"address": "john.doe@contoso.com"
},
"mentionText": "prepare the report about the incident"
}
]
}
Use the message id from the response
C# code:
var graphClient = new GraphServiceClient(credential);
var requestBody = new Message
{
Subject = "The incident",
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "Hi Adele, send me the report. You <a href=\"john.doe@contoso.com\">@John Doe</a> prepare the report about the incident",
},
ToRecipients = new List<Recipient>
{
new Recipient
{
EmailAddress = new EmailAddress
{
Address = "john.doe@contoso.com",
}
},
new Recipient
{
EmailAddress = new EmailAddress
{
Address = "adele.vance@contoso.com",
}
}
},
Mentions = new List<Mention>
{
new Mention
{
Mentioned = new EmailAddress
{
Address = "john.doe@contoso.com",
},
MentionText = "prepare the report about the incident",
}
}
};
var draft = await graphClient.Me.Messages.PostAsync(requestBody);
// send the message
await graphClient.Me.Messages[draft.Id].Send.PostAsync();
Send a message with mentions
Remember that the mentioned person must be added also to toRecipients collection to ensure that the person will receive the email.
POST beta/me/sendMail
{
"message": {
"subject": "The incident",
"body": {
"contentType": "Html",
"content": "Hi Adele, send me the report. You <a href=\"john.doe@contoso.com\">@John Doe</a> prepare the report about the incident"
},
"toRecipients": [
{
"emailAddress": {
"address": "john.doe@contoso.com"
}
},
{
"emailAddress": {
"address": "adele.vance@contoso.com"
}
}
],
"mentions": [
{
"mentioned":{
"address": "john.doe@contoso.com"
},
"mentionText": "prepare the report about the incident"
}
]
}
}
C# code:
var graphClient = new GraphServiceClient(credential);
var message = new Message
{
Subject = "The incident",
Body = new ItemBody
{
ContentType = BodyType.Html,
Content = "Hi Adele, send me the report. You <a href=\"john.doe@contoso.com\">@John Doe</a> prepare the report about the incident"
},
ToRecipients = new List<Recipient>
{
new Recipient
{
EmailAddress = new EmailAddress
{
Address = "john.doe@contoso.com"
}
},
new Recipient
{
EmailAddress = new EmailAddress
{
Address = "adele.vance@contoso.com"
}
}
},
Mentions = new List<Mention>
{
new Mention
{
Mentioned = new EmailAddress
{
Address = "john.doe@contoso.com"
},
MentionText= "prepare the report about the incident"
}
}
};
await graphClient.Me.Messages.PostAsync(message);
Remove mentions
To remove a mentioned person, you need to know the message id and the specific mention id to be removed.
DELETE beta/me/messages/{message_id}/mentions/{mention_id}
C# code:
var graphClient = new GraphServiceClient(credential);
await graphClient.Me.Messages["{message_id}"].Mentions["{mention_id}"].DeleteAsync();
