Search-mailboxauditlog in Powershell: All You Need to Know

The majority of mailboxes inside an organization contain sensitive and personally identifiable information that needs to be guarded.

This creates the need to track who logs onto these mailboxes for online protection reasons, keeping control of mailbox updates and changes within an Exchange Server.

Delegate, user, and owner audit processes in an Exchange Server can be performed via the Admin Center, but if you want to have more control over the audit, then using PowerShell commands is a smart choice.

However, instead of visualizing and creating mailbox log audit reports in the Exchange Admin Center, we’ll learn how to use Search-MailboxAuditLog in PowerShell right away.

What is Search-MailboxAuditLog in PowerShell?

Search-MailboxAuditLog is a PowerShell cmdlet used to perform synchronous searches of mailbox audit logs.

This cmdlet, alongside other PowerShell commands, serves mailbox audit logging purposes within an Exchange Server.

The output of this cmdlet returns visualized results within PowerShell for individual and specified mailboxes, allowing admins to interpret and understand audit results.

The syntax of Search-MailboxAuditLog is the following:

This syntax can be modified to customize the output returned after running the cmdlet. Each parameter and switch in the syntax has a meaning - these are the most noteworthy parameters to consider:

• Identity: Specifies the mailbox for which you want to retrieve audit log entries. The Identity switch can either be a specific mailbox or multiple mailboxes;
• ShowDetails: The ShowDetails switch prompts the cmdlet to provide more info when it displays search results for an admin audit log;
• EndDate: Sets the end date for the search, defining the upper limit of the date range for which you want to retrieve audit log entries;
• StartDate: Set the start date to search mailbox audit logs;
• GroupMailbox: Filters the results to include entries related to group mailboxes, providing insights into activities specific to shared or group mailboxes;
• LogonTypes: Filters the results based on specific logon types, which can be administrator logons, logontypes owner, non-owner, delegate logon types (full mailbox access permission), and more. To return audit log entries for mailbox access by the primary mailbox owner, it’s necessary to include the ShowDetails switch;
• HasAttatchment: Allows the user to filter the results by showing the total entries found with attachments;
• Operations: Specifies the type of operations to include in the results, such as HardDelete, Get Date, MailboxLogin, and more.

What Can You Use Search-Mailbox Audit Log Cmdlet For?

Although Search-MailboxAuditLog is used mainly for mailbox audit log entries purposes, the command has other use cases and benefits, such as the following:

1. Auditing Mailbox Activity: The cmdlet is mainly used to track and audit activities within mailboxes, which allows administrators to monitor certain changes and updates that affect mailbox items;
2. Investigate Unauthorized Mailbox Access: Search-MailboxAuditLog reveals instances of unauthorized access to mailboxes. By checking the mailbox audit log entries, you can see who changed, deleted, moved, or checked files in one or multiple mailboxes;
3. Monitor Mailbox Access: The cmdlet allows administrators to see who has mailbox access permission by retrieving the log entries of certain mailboxes;
4. Detecting Message Moves: By modifying the cmdlet’s parameters, it’s possible to track and detect message moves within mailboxes, which is beneficial for maintaining email organization;
5. Generate Compliance Reports: After retrieving log entries for specified mailboxes, administrators can generate and visualize reports for compliance management purposes, allowing them to adhere to specific organizational requirements.
   

Prerequisites to Use Search-MailboxAuditLog Cmdlet in PowerShell

Since auditing activities across mailboxes is such a delicate matter, not all users within an Exchange Server will have the required permissions to run Search-MailboxAuditLog.

First, it’s necessary to have Windows PowerShell installed on your computer. Ensure that you have the latest module version installed and enough administrator permissions to proceed.

Then, to find cmdlets permissions, start Windows PowerShell, and run the following PowerShell script:

In this case, replace <cmdlet> with SearchMailboxAuditLog as shown in the following example:

The output will show you the roles that give access to the cmdlet. In case you are missing some permissions, it would be necessary to contact your Exchange Online administrator so these permissions can be granted.

How to Use Search-MailboxAuditLog PowerShell Command

Now that we understand the meaning and purpose of this cmdlet, let’s check out how to use Search-MailboxAuditLog in PowerShell, with examples and use cases.

Step 1: Connect to Exchange Online PowerShell

The first thing you need to do is to connect to Exchange Online PowerShell using your credentials.

Run PowerShell on your computer, and on the prompt window, type in the following command:

Replace “[email protected]” with your email address, use your Microsoft Account credentials, and complete the login process.

Once you’ve successfully logged in, proceed with the following step.

Step 2: Identify the Mailbox Audit Logs Locations

One of the most important parts of the Search-MailboxAuditLog cmdlet is the Identity parameter.

It’s necessary to have the correct identity of the mailbox you want to check audit logs of - otherwise, the cmdlet will return an error.

Remember that the Identity parameter can be the name, alias, email address or user ID used to identify one or multiple mailboxes.

Step 3: Enable Mailbox Audit Logging

To perform a mailbox audit log, it’s necessary to enable mailbox audit logging using the Set-Mailbox cmdlet.

To do so, you need the correct identity parameter for the specified mailbox in Microsoft 365. Open PowerShell, go to the command prompt window, and run the following cmdlet:

This cmdlet is used to modify the settings of existing mailboxes. More specifically, the “-AuditEnabled” switch set to $True allows the auditing of the desired mailbox.

If you are looking to perform an Exchange online audit for several mailboxes, you can bulk-enable audit logging by using this command:

This PowerShell command enables mailbox audit logging for all mailboxes in the Exchange environment, ensuring that auditing is turned on for each user's actions.

Step 4: Run the Search-MailboxAuditLog Command

Once auditing has been enabled for the desired mailbox, it’s time to run the Search-MailboxAuditLog command.

Let’s take a look at some examples. Check out the following command:

The output of this command returns a list of audit log entries for Simon’s mailbox. The command will return 1,000 results for actions performed by Delegates and Admins between 1/1/2022 and 1/1/2023.

But what if you want to retrieve the admin audit logs of multiple mailboxes at the same time? In this case, see the following example:

This command returns a result list of 1,000 actions performed by Admins between 1/1/2022 and 12/31/2022 for James and Simon’s mailboxes. As you can see, it’s not necessary to run the cmdlet individually multiple times, as multiple audit log retrieval is possible by modifying the Identity parameter.

The command can also be modified to retrieve audit log information performed by mailbox owners:

In this example, the command will retrieve the audit logs of the owner of the Meeting Room Mailbox between 1/1/2022 and 3/1/2023. It will also filter the results based on the HardDelete, meaning that it will focus on entries with permanent deletions.

Why is Search-MailboxAuditLog Not Working?

Did you try to run Search-MailboxAuditLog in your session, but the cmdlet failed to work? Let’s check out the three main causes behind this issue.

1. PowerShell Errors in Multi-Geo Environments

If you are trying to run Search-MailboxAuditLog in multi-geo environments, and the following message pops up: "An error occurred while trying to access the audit log,” it means that you are in a different region from the mailbox that you're trying to search.

The only solution to this problem is to anchor your PowerShell session to a user located in the same region as the mailbox.

To do this, add the ?email=<emailaddress> value to the end of the ConnectionUri value when connecting to PowerShell, as indicated by Microsoft Official Resources.

Keep in mind that the <emailaddress> parameter must belong to a user in the desired geo-location.

2. Incorrect Parameters or Permissions

One of the main reasons why the Search-MailboxAuditLog cmdlet fails is that there are general errors in the command.

You might not have Exchange Administrator Permissions, or there’s a syntax error in the identity parameter of the specified recipients.

Try to get info from other users and run the cmdlet multiple times before checking the syntax. Likewise, ensure that you have enough permissions and turn on mailbox audit with Set-Mailbox, as shown above.

3. You Are Using the Wrong Command

If you are not getting the information you want from the audit log, remember that Search-MailboxAuditLog is used just to search audit logs and visualize them.

This means that you’ll only have access to a visual resource within PowerShell and not a downloadable report.

The output of the cmdlet can look something like this:

All the actions performed by the cmdlet will be shown on the screen as indicated by the cmdlet’s switches.

If, on the other hand, you want to export mailbox audit logs into a .CSV file or HTML file directly sent to a single mailbox, then use the New-MailboxAuditLogSearch cmdlet instead.

The New-MailboxAuditLogSearch cmdlet is a different command that allows you to get a file of the audit logs, and which means it is different from Search-MailboxAuditLog.

Likewise, there are other default cmdlets that enable administrators to visualize, retrieve, and audit mailbox data that might suit what you are searching for.

Summary: Using Search-MailboxAuditLog in PowerShell

Using Search-MailboxAuditLog in PowerShell allows for more control over changes and updates to existing mailboxes. You are now ready to use this cmdlet, but before doing so, it’s important to have the following three factors in mind:

1. Use Search-MailboxAuditLog when you need to visualize audit log info, review mailbox changes, check updates to mailbox items, monitor mailbox access and identify unauthorized uses of mailboxes;
2. The Search-MailboxAuditLog cmdlet only displays results in the Exchange Management Shell window - it doesn’t generate or send an audit file;
3. If the cmdlet is not working as intended, make sure that there are no syntax errors, check the geo-location of the mailbox, enable mailbox auditing with Set-Mailbox first, and review the Identity parameter of the user mailbox you want to check.