Safelist aggregation procedures

In Exchange Server, safelist aggregation refers to sender and recipient data that's collected from all users' Junk Email options in Microsoft Outlook, Outlook on the web, or the Set-MailboxJunkEmailConfiguration cmdlet and shared with the built-in Exchange antispam agents. For more information, see Safelist aggregation.

You can use the procedures in this topic to:

  • Configure limits on the number of safe senders and blocked senders that are stored for specific mailboxes.

  • Manually run safelist aggregation

  • Verify that safelist aggregation is working correctly.

For more information about adding and removing entries from a user's safelist collection, see Use the Exchange Management Shell to configure the safelist collection on a mailbox.

What do you need to know before you begin?

  • Estimated time to complete each procedure: 5 minutes

  • You need to be assigned permissions before you can perform this procedure or procedures. To see what permissions you need, see the "Recipient Provisioning Permissions" section in the Recipients Permissions topic, and the "Antispam features" section in the Antispam and antimalware permissions topic.

  • You can only use PowerShell to perform this procedure. To learn how to open the Exchange Management Shell in your on-premises Exchange organization, see Open the Exchange Management Shell.

  • By default, antispam features aren't enabled in the Transport service on a Mailbox server. Typically, you only enable the antispam features on a Mailbox server if your Exchange organization doesn't do any prior antispam filtering before accepting incoming messages. For more information, see Enable antispam functionality on Mailbox servers.

  • Be aware of the replication traffic that might be generated when you run the Update-SafeList cmdlet. Running the command on multiple mailboxes where safelists are heavily used might generate a significant amount of network traffic. We recommend that if you run the command on multiple mailboxes, you should run the command during off-peak, non-business hours.

  • For information about keyboard shortcuts that may apply to the procedures in this topic, see Keyboard shortcuts in the Exchange admin center.

Tip

Having problems? Ask for help in the Exchange forums. Visit the forums at: Exchange Server, Exchange Online, or Exchange Online Protection.

Use the Exchange Management Shell to configure the mailbox safelist collection limits

You can configure the maximum number of safe senders and blocked senders a user can configure. By default, users can configure up to 5,000 safe senders and 500 blocked senders.

To configure the maximum number of safe senders and blocked senders, use the following syntax:

Set-Mailbox <MailboxIdentity> -MaxSafeSenders <Integer> -MaxBlockedSenders <Integer>

This example configures the mailbox john@contoso.com to have a maximum of 2,000 safe senders and 200 blocked senders.

Set-Mailbox john@contoso.com -MaxSafeSenders 2000 -MaxBlockedSenders 200

How do you know this worked?

To verify that you have successfully configured the mailbox safelist collection limits, replace <MailboxIdentity> with the identity of the mailbox, and run the following command to verify the mailbox property values.

Get-Mailbox <MailboxIdentity> | Format-List Name,Max*Senders

Use the Exchange Management Shell to manually run safelist aggregation

Safelist aggregation is done automatically, so you don't need to schedule or manually run the Update-Safelist cmdlet. However, you may want to occasionally run this cmdlet to test safelist aggregation.

To manually run safelist aggregation, use the following syntax:

Update-Safelist <MailboxIdentity> [-Type <SafeSenders | SafeRecipients | Both>] [-IncludeDomains]

This example writes the Safe Senders List for the mailbox john@contoso.com to Active Directory.

Update-Safelist john@contoso.com

For detailed syntax and parameter information, see Update-SafeList.

Notes:

  • You don't need to use the Type parameter because:

    • The default value is SafeSenders.

    • The Content Filter agent doesn't use Safe Recipients list data, so the SafeRecipients or Both values are unnecessary.

  • By default, safelist aggregation doesn't include domain entries from the Safe Senders list (just email addresses), but you can configure it to include domain entries from the safelist collection. For more information, see Configure Content Filtering to Use Safe Domain Data.

How do you know this worked?

To verify that you have successfully configured safelist aggregation, perform the following steps:

Step 1: Use the Exchange Management Shell to verify the Content Filter agent is enabled on the Exchange server

Run the following command:

Get-ContentFilterConfig | Format-List Enabled

If the output shows the Enabled property to be True, content filtering is enabled. If it isn't, run the following command to enable content filtering and the Content Filter agent on the Exchange server:

Set-ContentFilterConfig -Enabled $true

Step 2: (Optional) Use ADSI Edit to verify replication of the safelist aggregation data to Edge Transport servers

This step is only required if you run the Content Filter agent on a subscribed Edge Transport server in your perimeter network.

You can view the user objects in the Active Directory Lightweight Directory Services (AD LDS) instance on the Edge Transport server to:

  • Verify that the safelist collection data is updated for the user objects.

  • Verify that the Microsoft Exchange EdgeSync service has replicated the data to the AD LDS instance.

There are three safelist collection attributes for each user object:

  • msExchSafeRecipientsHash: Stores the hash of the Safe Recipients List collection for the user.

  • msExchSafeSendersHash: Stores the hash of the Safe Senders List collection for the user.

  • msExchBlockedSendersHash: Stores the hash of the Blocked Senders List collection for the user.

If a hexadecimal string, such as 0xac 0xbd 0x03 0xca, is present on the attribute, the user object was updated. If the attribute has a value of <Not Set>, the attribute wasn't updated.

You can search for and view the attributes by using ADSI Edit on the Edge Transport server (run ADSIEdit.msc).

Step 3: Send a test message to verify safelist aggregation is working

To test whether safelist aggregation is functioning, you need to send yourself a message from a safe sender that would otherwise be blocked by content filtering (for example, the message contains a blocked phrase). If safelist aggregation is functioning, the message should arrive in your Inbox.

  1. Open your Exchange mailbox in Outlook, and add an external email address (associated with an account that you can access) to your Safe Senders List. For more information, see Add names to the Junk Email Filter lists.

  2. Use the Update-SafeList cmdlet to manually replicate the safelist collection from your mailbox to Active Directory:

    Update-Safelist <YourMailboxIdentity>
    
  3. Optional: if you're running the Content Filter agent on a subscribed Edge Transport server in the perimeter network, run the Start-EdgeSynchronization cmdlet to force EdgeSync replication.

  4. Add a specific word as a blocked phrase to your content filtering configuration. For example:

    Add-ContentFilterPhrase -Influence BadWord -Phrase "SafeList aggregation test"
    

    For details, see Use the Exchange Management Shell to configure allowed and blocked phrases for content filtering.

  5. From the external email account in step 1, send a message to your Exchange mailbox that includes the blocked phrase that you configured in step 4.

    If the message is successfully delivered to your Inbox, safelist aggregation is working correctly.