A while ago I published this blog post about doing this using EWS and a few people have recently asked if it is also possible to do this with the Graph API(which it is) so I've decided to include this one in my Graph Basics series.

Moderation

https://graph.microsoft.com/v1.0/me/mailFolders('Inbox')/messages?
$filter=singleValueExtendedProperties/any(ep:ep/id eq 'String 0x001a' and ep/value eq 'IPM.Note.Microsoft.Approval.Request')

{
	id = "String 0x001A"
	value = "IPM.Note.Microsoft.Approval.Reply.Aprove"
}

{
	id = "String 0x001A"
	value = "IPM.Note.Microsoft.Approval.Reply.Reject"
}

{
	id = "String {00062008-0000-0000-C000-000000000046} Id 0x8524"
	value = "Approve"
}

{
	id = "Binary 0x31"
	value =  $ApprovalMail.singleValueExtendedProperties[0].value
}

If your getting an error such as Application is over its MailboxConcurrency limit while using the Microsoft Graph API this post may help you understand why.

Background  

The Mailbox  concurrency limit when your using the Graph API is 4 as per https://docs.microsoft.com/en-us/graph/throttling#outlook-service-limits . This is evaluated for each app ID and mailbox combination so this means you can have different apps running under the same credentials and the poor behavior of one won't cause the other to be throttled. If you compared that to EWS you could have up to 27 concurrent connections but they are shared across all apps on a first come first served basis.

Batching

Searching on the Categories property of an Email can pose a challenge because this property is a Multi-valued String property (which aren't that common in email) eg in a Message the property may look like the following

So this needs to be queried in a different way then a normal String or single valued property in an Email would, where you could use a number of filter options (eg equal, contains,startswith). In EWS it was only possible to query this property using AQS because of the way SearchFilters translated to the underlying ROP based restrictions used by the Exchange Mailbox Store. In the Microsoft Graph the Linq format in Filters does translate more favourably so can be used eg the following simple query can find Messages in a folder based on a specific category

https://graph.microsoft.com/v1.0/me/messages?filter=Categories/any(a:a+eq+'Green+Category')

you can create a SearchFolder based on this query which would search all folder in a Mailbox which would produce a SearchFolder Creation request like

{
"@odata.type": "microsoft.graph.mailSearchFolder",
"displayName": "Green Email",
"includeNestedFolders": true,
"sourceFolderIds": ["MsgFolderRoot"],
"filterQuery": "Categories/any(a:a+eq+'Green+Category')"
}

Based on a previous post on creating Search Folders I have this script https://github.com/gscales/Powershell-Scripts/blob/master/Graph101/SearchFolder.ps1 which you can use to Create a Category Search folder as well as other SearchFolder CRUD operations eg

Invoke-CreateCategorySearchFolder -MailboxName user@domain.onmicrosoft.com -SearchFolderName CategoryTest -CategoryName "Category 1"

One of the email UI features that I find the most useful in Outlook on the Web and Outlook mobile is the People favorites feature which saves having to do a search for historical email from particular high use contacts. Favorites is a feature that has evolved especially in Outlook on the web and Outlook mobile eg People/Persona favorites and category favorites. The way this is implemented in the Mailbox is interesting eg   People/Persona favorites get their own search folder under the favoritePersonas Folder in the Non_IPM_Subtree in a Mailbox eg

As well as a configuration object under the 

\ApplicationDataRoot\32d4b5e5-7d33-4e7f-b073-f8cffbbb47a1\outlookfavorites eg

The configuration object is of interest as this tells as a lot about what type of favorites are being created and used in a Mailbox. It also can serve in a custom app if you want to reproduce the same type of favorites folder tree (you will need to use EWS for this as the Graph API is unfortunately hamstrung for this type of application). On the favourites object is a Extended property call RawJson that contains all the information that is of interest eg.

For this post I've created an EWS script that first finds the above folder and then gets all the Shortcut Items in that folder and retrieves the rawJson extended property on each of the ShortCut Items. It then does a little bit more data abstraction from the Json to make it into a report-able object. So for instance we can do a

Quick view of what Shortcuts are being used (which clients,Last-Visted(for groups)and type) eg

In the above Legacy = Outlook Desktop and Outlook Services is the Outlook Mobile client on Android

Just the Personal favorites

The script for this post is available on GitHub https://github.com/gscales/Powershell-Scripts/blob/master/Favourites.ps1

Mailbox analytics is something Microsoft have been working on for a number of years and its seems to be something that has received a little more effort in these pandemic times. If you have ever looked at the Non_IPM_Subtree of your mailbox you will see a lot of data being stored in their from various apps and substrate processes. A while back i wrote a ChangeDiscovery script to allow me to dump out quick what changes where happening in a Mailbox in a short time frame (eg i wanted to see what happened to all the items in a Mailbox when i performed a specific task). If you run this script with a slightly longer time-frame (eg looking over a day) it picks up all the Items that are being written and created for the Mailbox insights processes and other substrate processes.

Most of these emails get written under the 

Usually if I then wanted to look at these type of items I would use OutlookSpy or MFCMapi to browse the raw MAPI properties on items to see if they where of interest. Given the number of these items now and the performance on MAPI in Online mode doing this is extremely tedious so I modified my change discovery script further to dump the RawJson and Data properties that most of the insight items use so you can then look at the whole bunch in Excel. eg the following two properties

 So now i can dump basically everything that is happening in a Mailbox to a CSV in the last day and you can see some of this analytics data is pretty interesting  

eg

and if you looked at the data from the ActivitiesDaily

This is just a quick snippet of data on one item but things like the hourly breakdown of the number of the Messages being read per hour by a user is something that is really interesting and not something you can determine just using the raw data in a Mailbox.

While this raw data may surface elsewhere in a number of different guises and formats that are a lot of specific things you could use it for (outside of the narrative Microsoft are using for this).

The Modified change discovery script is available on Github https://github.com/gscales/Powershell-Scripts/blob/master/ChangeDiscovery.ps1

To run the script and look back 12 hours and dump the RawJson properties use something like

Invoke-MailboxChangeDiscovery -MailboxName gscales@mailbox.com -disableImpersonation -getJsonMetaData -secondstolookback 43200

for 24 hours use

Invoke-MailboxChangeDiscovery -MailboxName gscales@mailbox.com -disableImpersonation -getJsonMetaData -secondstolookback 86400

If you are doing any archiving, clean-up or just searching for Messages that are older then a specific date you will need to make use of a filter on the receivedDateTime.

The receivedDateTime property

This property represents when the Message was received expressed and stored in UTC time, this means when you query it you should also make sure your query value is in UTC.

So for instance if I where looking for all the Email in the JunkEmail folder older then 30 days I could use

/v1.0/users('gscales@datarumble.com')/MailFolders('JunkEmail')/messages?$Top=10&$filter=receivedDateTime lt 2020-10-21T00:00:00Z

If the mailboxes are in a TimeZone other then UTC then first convert the actual date to the local date you want to include to UTC eg in Powershell something like

(Get-Date).adddays(-30).Date.ToUniversalTime().ToString("o")

This means if my timezone is +11 UTC my actual query time would look like

2020-10-20T13:00:00.0000000Z based on an Actual day value of 2020-10-21T00:00:00.0000000+11:00

Precision

The last thing to consider around receivedDateTime is precision, Exchange Server stores the Item with a precision down to the milliseconds in EWS you could adjust the precision of your queries down to the millisecond however the Graph API doesn't allow you to do this. So if your querying items in the Graph and using the GT or LT operators you may see them work more as GE and LE due to the loss in precision. While this sounds like a little thing it can be quite painful depending on what your trying to do.

Orderby

By default when you use a filter you will get the results back in ascending order so if you want to see the latest messages first make sure you use

OrderBy=receivedDateTime desc

if you add more fields into the Filter clause they will also need to be added to the OrderBy

I've created a Powershell Script to go along with the doc call ItemAgeModule.ps1 available from https://github.com/gscales/Powershell-Scripts/blob/master/Graph101/ItemAgeModule.ps1

Some Examples are get the last 10 email in the Inbox older then 30 days would look like

Get-EmailOlderThan -MailboxName gscales@domain.com -FolderName Inbox -OlderThanDays 30 -MessageCount 10

To get all the Email in the Junk-Email Folder older the 30 days use the following and it will page them back 100 items at a time

Get-EmailOlderThan -MailboxName gscales@domain.com -FolderName Inbox -OlderThanDays 30

To get all Email older then 30 days with a specific subject then you can use (note the OrderByExtraFields is needed which should have a comma seperated list of extra fields used in the filter)

Get-EmailOlderThan -MailboxName gscales@domain.com -FolderName Inbox -OlderThanDays 30 -filter "Subject eq 'test'" -OrderByExtraFields subject

Moving the Emails you find

As mentioned one of the main reasons you may have for finding messages of a specific age is to Archive, Move or Delete them. For this you need to use the move operation on the Item endpoint eg in graph this is basically a post like

https://graph.microsoft.com/v1.0/me/messages/AAK.....=/move

with the destination folder in the body of the POST (either a folderId or WellknownFolderName) eg

{  "destinationId": "archive" }

Would move messages to the mailbox's archive folder (not my in-place archive)

So if I wanted to archive all the Messages in my Inbox from a particular sender that was older then 2 years I could use

Move-EmailOlderThan -MailboxName gscales@domain.com -FolderName Inbox -OlderThanDays 30 -filter "from/emailAddress/address eq 'user@domain.com'" -OrderByExtraFields "from/emailAddress/address" -Destination archive

This code makes use of batching and moves items in lots of 4 as not to go over the concurrent user quota

Or if I wanted to soft delete items I could move them to the RecoverableItemsDeletions folder

eg

Move-EmailOlderThan -MailboxName gscales@domain.com -FolderName Inbox -OlderThanDays 30 -filter "from/emailAddress/address eq 'info@twitter.com'" -OrderByExtraFields "from/emailAddress/address" -Destination RecoverableItemsDeletions -verbose

the script for this post can be found https://github.com/gscales/Powershell-Scripts/blob/master/Graph101/ItemAgeModule.ps1

Back to 101 Graph PowerShell Binder Mini-Site

 Microsoft made a recent change to where the compliance messages get stored in a Mailbox for private Teams Chats from the \Conversation History\Teams Chat Folder to a non_ipm_subtree folder called TeamsMessagesData (see https://office365itpros.com/2020/10/14/microsoft-changes-location-teams-compliance-records/ for some good commentary on this change). In terms of programmatic access to these messages this change affects the ability of the Graph (and Outlook REST) Endpoints to access them. While you could never access the Folder directly with the Graph API (because of the FolderClass) the messages themselves would appear in the \Messages endpoint (this is because they where captured by the underlying AllItems Search folder that backs this endpoint). Now the messages are in the Non_IPM_Subtree you loose the ability of that Search Folder to access those messages. This first up broke my OWA add-in from https://gsexdev.blogspot.com/2019/03/microsoft-teams-private-chat-history.html that could be used to show the Chat History for a user using the compliance messages in a Mailbox  eg

While the Graph and Outlook REST Endpoints can't be used to access these compliance records anymore (unless you create your own search folder to expose them). You can use EWS to still access them, to fix my Outlook Add-in this meant switching the code from using the Outlook Rest Endpoint to EWS to accessing these message. I also wrote a script to show how these message could be accessed via powershell

There are two ways of getting the TeamsMessagesData Folder in EWS the first is you can use an Extended property that exists on the Inbox folder that will contain the hex entryId to the TeamsMessagesData Folder you then need to convert that to an EWS id and then bind to the Folder eg (In the script I've done this)

The other way is just find the folder using its name in the Root of the Non_IPM_Subtree. (In the Plugin I do this)

With the script it means is I can do something like this to view the Chat messages in a Mailbox (last 30 days) eg

As well as changing the Add-in from using the Outlook Rest endpoint to EWS I've also included a look back dropdown so if you want to see more then the default 60 days of messages you now can eg

(what you will see will depend on the Retention policy for your compliance records ).

The script is available from https://github.com/gscales/Powershell-Scripts/blob/master/GetTeamsChatMessages.ps1

I've created a few new Binder entries in GitHub for using Shared Mailboxes in the Graph API using PowerShell

 After the events of the last weeks around the latest zero day vulnerabilities in Exchange  and once you've finished cleaning up any back doors that may have been left on servers its a good idea to review some other less known but established ways bad actors may hide persistent access within Mailboxes. One of these are Inbox Rules (but Mail Flow rules could also be used) and a more advanced method is the hidden Inbox rule exploit that was first talked about https://blog.compass-security.com/2018/09/hidden-inbox-rules-in-microsoft-exchange/ and I covered it in https://gsexdev.blogspot.com/2019/05/audting-inbox-rules-with-ews-and-graph.html and somebody else https://mgreen27.github.io/posts/2019/06/09/O365HiddenRules.html there are a number of tools and techniques around detecting these types of rule but are all focused more toward Office365 as that was where at the time this exploit was being mostly employed. In my post at the time I modified the Microsoft script https://github.com/gscales/O365-InvestigationTooling/blob/master/Get-AllTenantRulesAndForms.ps1 so it would include the PidTagRuleMsgProvider property in its final report so you could easy spot any null, empty or custom values that would effectively hide rules from being enumerated via other more conventional methods. Because this tool was designed for o365 it can't easily be run against onPrem Exchange so I've put together a modified version that can be and posted it up here.  https://github.com/gscales/Powershell-Scripts/blob/master/EWShiddenRuleEnum.ps1  I've retained the funky Encoded compressed version of the EWS Managed API dll that the original used and extended some of the properties to include things like the display-name of the user and the last modified date time of the rule object. To use this script you need to have EWS Impersonation enabled for the user you either pass into the script or the user the script is running under. https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-configure-impersonation

Mostly the changes to the script involved (other then cleanup) where around the remote power shell differences (this script will try to open a remote ps connection if one isn't already established) and passing in the hostname of the EWS endpoint.

To use this script first import the script module

Import-module ./EWShiddenRuleEnum.ps1

Then 

Invoke-EnumerateAllInboxRules

parameters that can/must be used

EWSHostName this is the EWS endpoint hostname the script doesn't use autodiscover so if your not running directly on the destination server you must pass this in

ExchangePSHostName this is the servername that the Remote powershell session will be open against if your not running directly on the destination server you must pass this in

Credentials are the credentials that will be used in EWS to connect and impersonate mailboxes, the remote powershell credentials used are the running users. (credentials can be entered in either UPN format or downlevel format domain\username and this can be environment dependent as to what works)

Filter this allows you to filter the Get-Mailbox query with any valid filter you would normally use in the PowerShell eg Invoke-EnumerateAllInboxRules -filter '{servername -eq hostname}'

The script will produce a CSV report of rules and forms in the current directory, you can open this in Excel and apply filters to make it easy to read and interpret. 

If you don't go down the path of rebuilding Exchange servers that where exploited make sure you also look at any Transport Agents you have installed and verify the assemblies, its a a lesser known method of persistent access but it has been used before https://www.bankinfosecurity.com/researchers-spies-exploit-microsoft-exchange-backdoor-a-12459 to some success.   

For messages from internal senders the property doesn't appear to get set and if the feature isn't enabled in your tenant then you won't see this property either. You can negate the boolean value of the property which will turn off the external tag.

Using it in the Microsoft Graph API

One of the Microsoft Teams features that I like the least is call history, for a number of reasons firstly its quite limited only 30 days worth of data and only includes direct calls and not meetings (which are often just scheduled calls). So when it comes to actually answering a question (like the one I found myself asking last week) when did I last have a call or meeting with person X it can't be used to answer this question.  The other thing is having that information available in the context of Outlook/OWA is a lot more useful for me (anyway) then digging through anther client to find its doesn't answer the question anyway. However while the call history in Teams only goes back 30 days the Teams CDR (Call Data Records) which I covered in https://dev.to/gscales/accessing-microsoft-teams-summary-records-cdr-s-for-calls-and-meetings-using-exchange-web-services-3581 do go back as far as your mailbox folder retention period. So with a little work I can use Exchange Web Services to create an Outlook/OWA addin that can be used to show the Call history for a person inline in OWA when you active it on a message you received from that user Eg

How this works is that the CDR item that is stored in the Mailbox stores the participants of the Call or Meeting in the recipients collection of the CDR mailbox item. The means you can make a KQL query on the participants to find all the CDR items that involve a particular user based on the sender address of the Email that the OWA Addin is activated on. eg the EWS Query ends up looking like

The extended properties that are used for the Start and End are pidTagStart and pidTagEnd which get set on the CDR mailbox item and then the SenderEmailSMTP address is used to work out who is the Organizer or the call initiator. To work out the type of Call the ItemClass is used so the last part of the ItemClass will tell you what the CRD is for eg call or meeting (If your wondering if you could do the same with the Microsoft Graph the answer is no because the Items in question are not a subclass of IPM.Note so aren't accessible when using the Microsoft Graph)

I've posted the code for the Addin in the following GitHub repository https://github.com/gscales/Microsoft-Teams-Call-History-Outlook-OWA-Addin

Out of Office (or automaticRepliesSetting) can be used for a vast number of different applications. For example in this Teams In/Out board 

With the Microsoft Graph API there are two ways that can be used to get the automaticRepliesSetting either via the Mailbox setting Endpoint eg

https://docs.microsoft.com/en-us/graph/api/resources/automaticrepliessetting?view=graph-rest-1.0

There's been a few contact creation scripts popup recently for the Graph API like this as well as a few questions on the forums around this topic lately. None of these examples and questions are taking advantage of using batching in the Microsoft Graph which will give you a significant uplift in performance vs the single request method when creating larger numbers of items and also help you a little around throttling.

I've added a new post to my Graph 101 binder on GitHub that includes an example of doing a CSV Contact import using batching and Service Principal Authentication https://github.com/gscales/Graph-Powershell-101-Binder/blob/master/Contacts/Batch%20Importing%20Contacts.md 

If your interested in a EWS version that can use larger batches (eg 60-100 contacts per request) I've also include an example on GitHub for this https://github.com/gscales/Powershell-Scripts/blob/master/Graph101/BatchContactCreationEWS.ps1

 One of the more complex things to migrate in EWS when migrating to the Graph API is any directory access code that uses one of the following EWS operations

• FindPeople
• ResolveName
• ExpandGroup (ExpandDL)

• msExchRecipientDisplayType
• msExchRecipientTypeDetails
• msExchRemoteRecipientType

https://graph.microsoft.com/v1.0/users?$top=999&$filter=proxyAddresses/any(x:x%20eq%20'smtp:info@users.com')

https://graph.microsoft.com/v1.0/users?$top=999&$filter=endsWith(mail,'@msgdevelop.com')&$Count=true

One of the new features added to the Microsoft Graph recently was the ability to create and send Mime Messages (you have been able to get Message as Mime for a while). This is useful in a number of different scenarios especially when trying to create a Message with inline Images which has historically been hard to do with both the Graph and EWS (if you don't use MIME). It also opens up using SMIME for encryption and a more easy migration path for sending using SMTP in some apps.

MimeKit is a great open source library for parsing and creating MIME messages so it offers a really easy solution for tackling this issue. The current documentation on Send message via MIME lacks any real sample so I've put together a quick console app that use MSAL, MIME kit and the Graph SDK to send a Message via MIME. As the current Graph SDK also doesn't support sending via MIME either there is a workaround for this in the future my guess is this will be supported.

Sending a message with a large attachment used to be the least worst option when it came to shipping data between people. In the Modern workplace where document and file sharing options are a lot better sending email with a large attachment can tends now to be the worst option especially when it comes to version control, expiration etc. However if you do find yourself with the need to send an email with large attachments (larger then 4MB) and you want to make use of the Microsft Graph API then it requires you use a different method from just sending the message in one post eg https://docs.microsoft.com/en-us/graph/outlook-large-attachments?tabs=http

This does make sending a Message a lot more complex eg if you have a Message less the 4MB you can just make one REST Post to send that message. If you have a large attachment you then have a multi step process eg

1. Create a Draft message where you set all the other message property eg Subject,To,Body
2. Take the MessageId(graph item id) returned in Step 1 and Create an Upload Session
3. Read the attachment and upload the attachment in chunks until you have uploaded the entire file
4. Send the Draft Message

I've put together a Powershell sample and posted it on GitHub  https://github.com/gscales/Powershell-Scripts/blob/master/Graph101/SendMessageWithLargeAttachment.ps1 that performs the above to run this use something like

Invoke-SendMessageWithLargeAttachment -MailboxName gscales@....com -filePath "C:\temp\rates.pdf" -verbose -uploadChunkSize 400000 -Subject "Test Message 1234" -body "Rgds Glen" -To glenscales@yahoo.com

The chunk size you use is up to you a larger chunk size will generally mean a faster upload but if the Network is more unreliable a smaller chunk is better

With the full depreciation of Basic Authentication around the corner I've put together a Github doc to show one implementation of using MSAL with the EWS Managed API that supports both Hybrid Modern Authentication and token caching and refresh. It can be found https://github.com/gscales/EWS-BasicToOAuth-Info/blob/main/EWA%20Managed%20API%20MASL%20Token%20Refresh.md

FindItemsResults fiItems = service.FindItems(QueryFolder,"Attachmentnames:.pdf", iv);

https://graph.microsoft.com/v1.0/me/mailFolders('Inbox')/messages
?$search="attachmentnames:.pdf"

https://graph.microsoft.com/v1.0/me/mailFolders('Inbox')/messages?
$search="participants:Fred"

https://graph.microsoft.com/v1.0/me/mailFolders('Inbox')
/messages?$search="received:yesterday"

https://graph.microsoft.com/v1.0/me/mailFolders('Inbox')/messages?
$search="received:2019-01-01...2019-02-01"

https://graph.microsoft.com/v1.0/me/mailFolders('Inbox')/messages?
$search="(received>=2019-01-01 AND received<=2019-02-01)"

https://graph.microsoft.com/v1.0/me/messages?
$search="(received>=2019-01-01 AND received<=2019-02-01)"

• It can't be used to search delegate Mailboxes so only the primary mailbox 
• It only returns the pageCount for items not the Total number of Items found in a search (to be fair $search does this as well which is really annoying)
• Searches are scoped across the entire mailbox 
• Just Messages and Events are searchable at the moment