How to use mailbox audit logs in Microsoft 365

In Microsoft 365, you can run mailbox audit logs to determine when a mailbox was updated unexpectedly or whether items are missing from a mailbox. For example, you may have to do this if items are moved or if they're deleted unexpectedly or incorrectly.

Note: For the vNext environment, by default, mailbox audit logs aren't enabled. The feature must be turned on in order for a user to begin a search.

How to run and check mailbox audit logs

Mailbox audit logging lets users obtain information about actions that are performed by non-owners and administrators. Mailbox audit logging is available to members of the Audit Reporting Mailbox self-service group only by using Windows Remote PowerShell.

To investigate this issue, create and use a Windows PowerShell script by using the sample script that's provided in Step 1 in this section, and then customize a search. By default, you can investigate actions that are performed by non-owners and administrators. This script exports content in a simplified, comma-separated values (.csv) file to help you troubleshoot reports about items that are missing or that were updated unexpectedly.

Step 1: Run the script

To run the script, follow these steps:

1. Open a text editor, such as Notepad, and then copy the following code into the file. The code uses the search-mailboxAuditLog command that is part of Microsoft Exchange Server.

    param ([PARAMETER(Mandatory=$TRUE,ValueFromPipeline=$FALSE)]
   [string]$Mailbox,
   [PARAMETER(Mandatory=$TRUE,ValueFromPipeline=$FALSE)]
   [string]$StartDate,
   [PARAMETER(Mandatory=$TRUE,ValueFromPipeline=$FALSE)]
   [string]$EndDate,
   [PARAMETER(Mandatory=$FALSE,ValueFromPipeline=$FALSE)]
   [string]$Subject,
   [PARAMETER(Mandatory=$False,ValueFromPipeline=$FALSE)]
   [switch]$IncludeFolderBind,
   [PARAMETER(Mandatory=$False,ValueFromPipeline=$FALSE)]
   [switch]$ReturnObject)
   BEGIN {
     [string[]]$LogParameters = @('Operation', 'LogonUserDisplayName', 'LastAccessed', 'DestFolderPathName', 'FolderPathName', 'ClientInfoString', 'ClientIPAddress', 'ClientMachineName', 'ClientProcessName', 'ClientVersion', 'LogonType', 'MailboxResolvedOwnerName', 'OperationResult')
     }
     END {
       if ($ReturnObject)
       {return $SearchResults}
       elseif ($SearchResults.count -gt 0)
       {
       $Date = get-date -Format yyMMdd_HHmmss
       $OutFileName = "AuditLogResults$Date.csv"
       write-host
       write-host -fore green "Posting results to file: $OutfileName"
       $SearchResults | export-csv $OutFileName -notypeinformation -encoding UTF8
       }
       }
       PROCESS
       {
       write-host -fore green 'Searching Mailbox Audit Logs...'
       $SearchResults = @(search-mailboxAuditLog $Mailbox -StartDate $StartDate -EndDate $EndDate -LogonTypes Owner, Admin, Delegate -ShowDetails -resultsize 50000)
       write-host -fore green '$($SearchREsults.Count) Total entries Found'
       if (-not $IncludeFolderBind)
       {
       write-host -fore green 'Removing FolderBind operations.'
       $SearchResults = @($SearchResults | ? {$_.Operation -notlike 'FolderBind'})
       write-host -fore green 'Filtered to $($SearchREsults.Count) Entries'
       }
       $SearchResults = @($SearchResults | select ($LogParameters + @{Name='Subject';e={if (($_.SourceItems.Count -eq 0) -or ($_.SourceItems.Count -eq $null)){$_.ItemSubject} else {($_.SourceItems[0].SourceItemSubject).TrimStart(' ')}}},
       @{Name='CrossMailboxOp';e={if (@('SendAs','Create','Update') -contains $_.Operation) {'N/A'} else {$_.CrossMailboxOperation}}}))
       $LogParameters = @('Subject') + $LogParameters + @('CrossMailboxOp')
       If ($Subject -ne '' -and $Subject -ne $null)
       {
       write-host -fore green 'Searching for Subject: $Subject'
       $SearchResults = @($SearchResults | ? {$_.Subject -match $Subject -or $_.Subject -eq $Subject})
       write-host -fore green 'Filtered to $($SearchREsults.Count) Entries'
       }
       $SearchResults = @($SearchResults | select $LogParameters)
       }
   

2. On the File menu, select Save As.

3. In the Save as type box, select All File.

4. In the File name box, enter Run-MailboxAuditLogSearcher.ps1, and then select Save.

5. Open Windows PowerShell, and then connect to Windows Remote PowerShell.

6. Locate the folder in which you saved the script, and then run the script:

   .\Run-MailboxAuditLogSearcher.ps1
   

   Note

   • If you run the script without parameters, you are prompted for the following default parameters:
     • Mailbox
     • StartDate
     • EndDate
   • To search for entries from the current day, add one day to the end-date value in the prompt window. For example, if the current date is 3/14/2017, and you want to include the current day in your search, enter 3/15/2017 as the end date.

Step 2: Customize a mailbox audit log search

In Microsoft 365, mailbox audit logging entries are retained in the mailbox for 90 days. You are prompted to indicate a start date and end date for the search. You can use several optional parameters to customize the search. For a description of these parameters, see the "More information" section.

If items are found after the script runs, you receive a message that resembles the following message:

Searching Mailbox Audit Logs...
11 Total entries Found
Removing FolderBind operations.
Filtered to 1 Entries

Posting results to file: AuditLogResults121024_142419.csv

This example message indicates that the search process has found 11 entries. By default, the FolderBind entries are filtered out, and the following operation types remain:

• Copy
• Create
• HardDelete
• MessageBind
• Move
• MoveToDeletedItems
• SendAs
• SendOnBehalf
• SoftDelete
• Update

Review the output of the .csv file. The most useful columns are exported, and some of these columns are merged to make the output easier to review. For more information about the columns that are exported, see the 'More information' section.

Owner mailbox audit logging

Mailbox audit logging is turned on by default for all organizations. One of the main benefits of enabling mailbox auditing by default is that you don't have to manage audited mailbox actions. Microsoft manages these actions for you, and we automatically add new mailbox actions to be audited by default as we release them.

However, your organization might have to audit a different set of mailbox actions for user mailboxes and shared mailboxes. For more information about how to change the mailbox actions that are audited for each sign-in type, and how to revert to the Microsoft-managed default actions, see Change or restore mailbox actions logged by default.

More information

Optional script parameters

The following list describes optional parameters that generate different results when they are used together with the Run-MailboxAuditLogSearcher script:

• IncludeFolderBind: Prevents the FolderBind operation from being filtered from the output. You can use FolderBind information to investigate mailbox access issue.

  For example, the following cmdlet searches the "Test User 1" mailbox and includes all operations:

  .\Run-MailboxAuditLogSearcher.ps1 -IncludeFolderBind -Mailbox "<Test User 1gt;" -StartDate "<04/10/17gt;" -EndDate "<04/27/17gt;&quot
  

• Subject: Enables you to specify the subject of an item in order to limit the search for operations that are performed on that item.

  For example, the following cmdlet filters out all output except items that have the subject set as 'Good News':

  .\Run-MailboxAuditLogSearcher.ps1 -Subject "<Good News>" -Mailbox "<test1@contoso.comgt;" -StartDate "<04/10/17gt;" -EndDate "<04/27/17gt;&quot
  

• ReturnObject: Causes the results to be displayed on screen (but not be exported to a .csv file).

  For example, the following cmdlet displays the output on screen:

  .\Run-MailboxAuditLogSearcher.ps1 -ReturnObject -Mailbox "<Test User 1gt;" -StartDate "<04/10/17gt;" -EndDate "<04/27/17gt;&quot
  

Exported columns from the .csv file

The most useful columns of the .csv file are exported. Some of these columns are merged to make the output easier to review. The following table lists the columns that are exported.

More information about mailbox audit logging

• The Search-MailboxAuditLog cmdlet is used in the sample script in Step 1 to search a single mailbox synchronously. You can do this also by running the cmdlet in Windows Remote PowerShell.

  For more information about the cmdlet, go to the following TechNet article:

  Search-MailboxAuditLog

• You can search one or more mailboxes asynchronously. To do this, run the following cmdlet in Windows Remote PowerShell:

  New-MailboxAuditLogSearch
  

  For more information about this cmdlet, go to the following article:

  New-MailboxAuditLogSearch

  For more information about the default mailbox audit logging entries, go to the "Mailbox audit log entries" section of the following article:

  Mailbox Audit Logging in Exchange 2016