Configure anti-phishing policies in Microsoft Defender for Office 365

Tip

Did you know you can try the features in Microsoft 365 Defender for Office 365 Plan 2 for free? Use the 90-day Defender for Office 365 trial at the Microsoft 365 Defender portal trials hub. Learn about who can sign up and trial terms here.

Applies to

Anti-phishing policies in Microsoft Defender for Office 365 can help protect your organization from malicious impersonation-based phishing attacks and other types of phishing attacks. For more information about the differences between anti-phishing policies in Exchange Online Protection (EOP) and anti-phishing policies in Microsoft Defender for Office 365, see Anti-phishing protection.

Admins can view, edit, and configure (but not delete) the default anti-phishing policy. For greater granularity, you can also create custom anti-phishing policies that apply to specific users, groups, or domains in your organization. Custom policies always take precedence over the default policy, but you can change the priority (running order) of your custom policies.

You can configure anti-phishing policies in Defender for Office 365 in the Microsoft 365 Defender portal or in Exchange Online PowerShell.

For information about configuring the more limited in anti-phishing policies that are available in Exchange Online Protection (that is, organizations without Defender for Office 365), see Configure anti-phishing policies in EOP.

The basic elements of an anti-phishing policy are:

  • The anti-phish policy: Specifies the phishing protections to enable or disable, and the actions to apply options.
  • The anti-phish rule: Specifies the priority and recipient filters (who the policy applies to) for an anti-phish policy.

The difference between these two elements isn't obvious when you manage anti-phishing policies in the Microsoft 365 Defender portal:

  • When you create a policy, you're actually creating an anti-phish rule and the associated anti-phish policy at the same time using the same name for both.
  • When you modify a policy, settings related to the name, priority, enabled or disabled, and recipient filters modify the anti-phish rule. All other settings modify the associated anti-phish policy.
  • When you remove a policy, the anti-phish rule and the associated anti-phish policy are removed.

In Exchange Online PowerShell, you manage the policy and the rule separately. For more information, see the Use Exchange Online PowerShell to configure anti-phishing policies section later in this article.

Every Defender for Office 365 organization has a built-in anti-phishing policy named Office 365 AntiPhish Default that has these properties:

  • The policy is applied to all recipients in the organization, even though there's no anti-phish rule (recipient filters) associated with the policy.
  • The policy has the custom priority value Lowest that you can't modify (the policy is always applied last). Any custom policies that you create always have a higher priority.
  • The policy is the default policy (the IsDefault property has the value True), and you can't delete the default policy.

To increase the effectiveness of anti-phishing protection in Defender for Office 365, you can create custom anti-phishing policies with stricter settings that are applied to specific users or groups of users.

What do you need to know before you begin?

Use the Microsoft 365 Defender portal to create anti-phishing policies

Creating a custom anti-phishing policy in the Microsoft 365 Defender portal creates the anti-phish rule and the associated anti-phish policy at the same time using the same name for both.

  1. In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Anti-phishing in the Policies section. To go directly to the Anti-phishing page, use https://security.microsoft.com/antiphishing.

  2. On the Anti-phishing page, click Create icon. Create.

  3. The policy wizard opens. On the Policy name page, configure these settings:

    • Name: Enter a unique, descriptive name for the policy.
    • Description: Enter an optional description for the policy.

    When you're finished, click Next.

  4. On the Users, groups, and domains page that appears, identify the internal recipients that the policy applies to (recipient conditions):

    • Users: The specified mailboxes, mail users, or mail contacts.
    • Groups:
      • Members of the specified distribution groups or mail-enabled security groups (dynamic distribution groups are not supported).
      • The specified Microsoft 365 Groups.
    • Domains: All recipients in the specified accepted domains in your organization.

    Click in the appropriate box, start typing a value, and select the value that you want from the results. Repeat this process as many times as necessary. To remove an existing value, click remove Remove icon. next to the value.

    For users or groups, you can use most identifiers (name, display name, alias, email address, account name, etc.), but the corresponding display name is shown in the results. For users, enter an asterisk (*) by itself to see all available values.

    Multiple values in the same condition use OR logic (for example, <recipient1> or <recipient2>). Different conditions use AND logic (for example, <recipient1> and <member of group 1>).

    • Exclude these users, groups, and domains: To add exceptions for the internal recipients that the policy applies to (recipient exceptions), select this option and configure the exceptions. The settings and behavior are exactly like the conditions.

    Important

    Multiple different types of conditions or exceptions are not additive; they're inclusive. The policy is applied only to those recipients that match all of the specified recipient filters. For example, you configure a recipient filter condition in the policy with the following values:

    • Users: romain@contoso.com
    • Groups: Executives

    The policy is applied to romain@contoso.com only if he's also a member of the Executives group. If he's not a member of the group, then the policy is not applied to him.

    Likewise, if you use the same recipient filter as an exception to the policy, the policy is not applied to romain@contoso.com only if he's also a member of the Executives group. If he's not a member of the group, then the policy still applies to him.

    When you're finished, click Next.

  5. On the Phishing threshold & protection page that appears, configure the following settings:

    • Phishing email threshold: Use the slider to select one of the following values:

      • 1 - Standard (This is the default value.)
      • 2 - Aggressive
      • 3 - More aggressive
      • 4 - Most aggressive

      For more information, see Advanced phishing thresholds in anti-phishing policies in Microsoft Defender for Office 365.

    • Impersonation: These settings are a condition for the policy that identifies specific senders to look for (individually or by domain) in the From address of inbound messages. For more information, see Impersonation settings in anti-phishing policies in Microsoft Defender for Office 365.

      • Enable users to protect: The default value is off (not selected). To turn it on, select the check box, and then click the Manage (nn) sender(s) link that appears.

        In the Manage senders for impersonation protection flyout that appears, do the following steps:

        • Internal senders: Click Add internal icon. Select internal. In the Add internal senders flyout that appears, click in the box and select an internal user from the list. You can filter the list by typing the user, and then selecting the user from the results. You can use most identifiers (name, display name, alias, email address, account name, etc.), but the corresponding display name is shown in the results.

          Repeat this step as many times as necessary. To remove an existing value, click remove Remove icon. next to the value.

          When you're finished, click Add

        • External senders: Click Add external icon. Select external. In the Add external senders flyout that appears, enter a display name in the Add a name box and an email address in the Add a vaild email box, and then click Add.

          Repeat this step as many times as necessary. To remove an existing value, click remove Remove icon. next to the value.

          When you're finished, click Add

        Note

        You can specify a maximum of 350 users for user impersonation protection in each anti-phishing policy.

        User impersonation protection does not work if the sender and recipient have previously communicated via email. If the sender and recipient have never communicated via email, the message can be identified as an impersonation attempt.

        You might get the error "The email address already exists" if you try to add a user to user impersonation protection when that email address is already specified for user impersonation protection in another anti-phishing policy. This error occurs only in the Defender portal. You won't get the error if you use the corresponding TargetedUsersToProtect parameter in the New-AntiPhishPolicy or Set-AntiPhishPolicy cmdlets in Exchange Online PowerShell.

        Back on the Manage senders for impersonation flyout, you can remove entries by selecting one or more entries from the list. You can search for entries using the Search icon. Search box.

        After you select at least one entry, the Remove selected users icon. Remove selected users icon appears, which you can use to remove the selected entries.

        When you're finished, click Done.

      • Enable domains to protect: The default value is off (not selected). To turn it on, select the check box, and then configure one or both of the following settings that appear:

        • Include the domains I own: To turn this setting on, select the check box. To view the domains that you own, click View my domains.

        • Include custom domains: To turn this setting on, select the check box, and then click the Manage (nn) custom domain(s) link that appears. In the Manage custom domains for impersonation protection flyout that appears, click Add domains icon. Add domains.

          In the Add custom domains flyout that appears, click in the Domain box, enter a value, and then press Enter or select the value that's displayed below the box. Repeat this step as many times as necessary. To remove an existing value, click remove Remove icon. next to the value.

          When you're finished, click Add domains

          Note

          You can specify a maximum of 50 custom domains for domain impersonation protection in each anti-phishing policy.

        Back on the Manage custom domains for impersonation flyout, you can remove entries by selecting one or more entries from the list. You can search for entries using the Search icon. Search box.

        After you select at least one entry, the Delete domains icon. Delete icon appears, which you can use to remove the selected entries.

    • Add trusted senders and domains: Specify impersonation protection exceptions for the policy by clicking on Manage (nn) trusted sender(s) and domain(s). In the Manage custom domains for impersonation protection flyout that appears, configure the following settings:

      • Senders: Verify the Sender tab is selected and click Add senders icon.. In the Add trusted senders flyout that appears, enter an email address in the box and then click Add. Repeat this step as many times as necessary. To remove an existing entry, click Delete icon for the entry.

        When you're finished, click Add.

      • Domains: Select the Domain tab and click Add domains icon..

        In the Add trusted domains flyout that appears, click in the Domain box, enter a value, and then press Enter or select the value that's displayed below the box. Repeat this step as many times as necessary. To remove an existing value, click remove Remove icon. next to the value.

        When you're finished, click Add.

      Note

      Trusted domain entries don't include subdomains of the specified domain. You need to add an entry for each subdomain.

      If Microsoft 365 system messages from the following senders are identified as impersonation attempts, you can add the senders to the trusted senders list:

      • noreply@email.teams.microsoft.com
      • noreply@emeaemail.teams.microsoft.com
      • no-reply@sharepointonline.com

      Back on the Manage custom domains for impersonation flyout, you can remove entries from the Sender and Domain tabs by selecting one or more entries from the list. You can search for entries using the Search icon. Search box.

      After you select at least one entry, the Delete icon appears, which you can use to remove the selected entries.

      When you're finished, click Done.

      Note

      The maximum number of sender and domain entries is 1024.

    • Enable mailbox intelligence: The default value is on (selected), and we recommend that you leave it on. To turn it off, clear the check box.

      • Enable intelligence based impersonation protection: This setting is available only if Enable mailbox intelligence is on (selected). This setting allows mailbox intelligence to take action on messages that are identified as impersonation attempts. You specify the action to take in the If mailbox intelligence detects an impersonated user setting on the next page.

        We recommend that you turn this setting on by selecting the check box. To turn this setting off, clear the check box.

        Note

        Mailbox intelligence protection does not work if the sender and recipient have previously communicated via email. If the sender and recipient have never communicated via email, the message will be identified as an impersonation attempt by mailbox intelligence.

    • Spoof: In this section, use the Enable spoof intelligence check box to turn spoof intelligence on or off. The default value is on (selected), and we recommend that you leave it on. You specify the action to take on messages from blocked spoofed senders in the If message is detected as spoof setting on the next page.

      To turn off spoof intelligence, clear the check box.

      Note

      You don't need to turn off anti-spoofing protection if your MX record doesn't point to Microsoft 365; you enable Enhanced Filtering for Connectors instead. For instructions, see Enhanced Filtering for Connectors in Exchange Online.

    When you're finished, click Next.

  6. On the Actions page that appears, configure the following settings:

    • Message actions: Configure the following actions in this section:

      • If message is detected as an impersonated user: This setting is available only if you selected Enable users to protect on the previous page. Select one of the following actions in the drop down list for messages where the sender is one of the protected users that you specified on the previous page:

        • Don't apply any action

        • Redirect message to other email addresses

        • Move message to the recipients' Junk Email folders

        • Quarantine the message: If you select this action, an Apply quarantine policy box appears where you select the quarantine policy that applies to messages that are quarantined by user impersonation protection. Quarantine policies define what users are able to do to quarantined messages, and whether users receive quarantine notifications. For more information, see Quarantine policies.

          A blank Apply quarantine policy value means the default quarantine policy is used (DefaultFullAccessPolicy for user impersonation detections). When you later edit the anti-phishing policy or view the settings, the default quarantine policy name is shown.

        • Deliver the message and add other addresses to the Bcc line

        • Delete the message before it's delivered

      • If the message is detected as an impersonated domain: This setting is available only if you selected Enable domains to protect on the previous page. Select one of the following actions in the drop down list for messages where the sender's email address is in one of the protected domains that you specified on the previous page:

        • Don't apply any action

        • Redirect message to other email addresses

        • Move message to the recipients' Junk Email folders

        • Quarantine the message: If you select this action, an Apply quarantine policy box appears where you select the quarantine policy that applies to messages that are quarantined by domain impersonation protection.

          A blank Apply quarantine policy value means the default quarantine policy is used (DefaultFullAccessPolicy for domain impersonation detections). When you later edit the anti-phishing policy or view the settings, the default quarantine policy name is shown.

        • Deliver the message and add other addresses to the Bcc line

        • Delete the message before it's delivered

      • If mailbox intelligence detects an impersonated user: This setting is available only if you selected Enable intelligence for impersonation protection on the previous page. Select one of the following actions in the drop down list for messages that were identified as impersonation attempts by mailbox intelligence:

        • Don't apply any action

        • Redirect message to other email addresses

        • Move message to the recipients' Junk Email folders

        • Quarantine the message: If you select this action, an Apply quarantine policy box appears where you select the quarantine policy that applies to messages that are quarantined by mailbox intelligence protection. Quarantine policies define what users are able to do to quarantined messages, and whether users receive quarantine notifications. For more information, see Quarantine policies.

          A blank Apply quarantine policy value means the default quarantine policy is used (DefaultFullAccessPolicy for mailbox intelligence detections). When you later edit the anti-phishing policy or view the settings, the default quarantine policy name is shown.

        • Deliver the message and add other addresses to the Bcc line

        • Delete the message before it's delivered

      • If message is detected as spoof: This setting is available only if you selected Enable spoof intelligence on the previous page. Select one of the following actions in the drop down list for messages from blocked spoofed senders:

        • Move message to the recipients' Junk Email folders

        • Quarantine the message: If you select this action, an Apply quarantine policy box appears where you select the quarantine policy that applies to messages that are quarantined by spoof intelligence protection. Quarantine policies define what users are able to do to quarantined messages, and whether users receive quarantine notifications. For more information, see Quarantine policies.

          A blank Apply quarantine policy value means the default quarantine policy is used (DefaultFullAccessPolicy for spoof intelligence detections). When you later edit the anti-phishing policy or view the settings, the default quarantine policy name is shown.

    • Safety tips & indicators: Configure the following settings:

      • Show first contact safety tip: For more information, see First contact safety tip.
      • Show user impersonation safety tip: This setting is available only if you selected Enable users to protect on the previous page.
      • Show domain impersonation safety tip: This setting is available only if you selected Enable domains to protect on the previous page.
      • Show user impersonation unusual characters safety tip This setting is available only if you selected Enable users to protect or Enable domains to protect on the previous page.
      • Show (?) for unauthenticated senders for spoof: This setting is available only if you selected Enable spoof intelligence on the previous page. Adds a question mark (?) to the sender's photo in the From box in Outlook if the message does not pass SPF or DKIM checks and the message does not pass DMARC or composite authentication.
      • Show "via" tag: This setting is available only if you selected Enable spoof intelligence on the previous page. Adds a via tag (chris@contoso.com via fabrikam.com) to the From address if it's different from the domain in the DKIM signature or the MAIL FROM address. The default value is on (selected). To turn it off, clear the check box.

      To turn on a setting, select the check box. To turn it off, clear the check box.

    When you're finished, click Next.

  7. On the Review page that appears, review your settings. You can select Edit in each section to modify the settings within the section. Or you can click Back or select the specific page in the wizard.

    When you're finished, click Submit.

  8. On the confirmation page that appears, click Done.

Use the Microsoft 365 Defender portal to view anti-phishing policies

  1. In the Microsoft 365 Defender portal, go to Email & Collaboration > Policies & Rules > Threat policies > Anti-phishing in the Policies section.

  2. On the Anti-phishing page, the following properties are displayed in the list of anti-phishing policies:

    • Name
    • Status
    • Priority
    • Last modified
  3. When you select a policy by clicking on the name, the policy settings are displayed in a flyout.

Use the Microsoft 365 Defender portal to modify anti-phishing policies

  1. In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Anti-phishing in the Policies section. To go directly to the Anti-phishing page, use https://security.microsoft.com/antiphishing.

  2. On the Anti-phishing page, select a policy from the list by clicking on the name.

  3. In the policy details flyout that appears, select Edit in each section to modify the settings within the section. For more information about the settings, see the Use the Microsoft 365 Defender portal to create anti-phishing policies section earlier in this article.

    For the default anti-phishing policy, the Users, groups, and domains section isn't available (the policy applies to everyone), and you can't rename the policy.

To enable or disable a policy or set the policy priority order, see the following sections.

Enable or disable custom anti-phishing policies

You can't disable the default anti-phishing policy.

  1. In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Anti-phishing in the Policies section. To go directly to the Anti-phishing page, use https://security.microsoft.com/antiphishing.

  2. On the Anti-phishing page, select a custom policy from the list by clicking on the name.

  3. At the top of the policy details flyout that appears, you'll see one of the following values:

    • Policy off: To turn on the policy, click Turn on icon. Turn on .
    • Policy on: To turn off the policy, click Turn off icon. Turn off.
  4. In the confirmation dialog that appears, click Turn on or Turn off.

  5. Click Close in the policy details flyout.

Back on the main policy page, the Status value of the policy will be On or Off.

Set the priority of custom anti-phishing policies

By default, anti-phishing policies are given a priority that's based on the order they were created in (newer policies are lower priority than older policies). A lower priority number indicates a higher priority for the policy (0 is the highest), and policies are processed in priority order (higher priority policies are processed before lower priority policies). No two policies can have the same priority, and policy processing stops after the first policy is applied.

To change the priority of a policy, you click Increase priority or Decrease priority in the properties of the policy (you can't directly modify the Priority number in the Microsoft 365 Defender portal). Changing the priority of a policy only makes sense if you have multiple policies.

Notes:

  • In the Microsoft 365 Defender portal, you can only change the priority of the anti-phishing policy after you create it. In PowerShell, you can override the default priority when you create the anti-phish rule (which can affect the priority of existing rules).
  • Anti-phishing policies are processed in the order that they're displayed (the first policy has the Priority value 0). The default anti-phishing policy has the priority value Lowest, and you can't change it.
  1. In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Anti-phishing in the Policies section. To go directly to the Anti-phishing page, use https://security.microsoft.com/antiphishing.

  2. On the Anti-phishing page, select a custom policy from the list by clicking on the name.

  3. At the top of the policy details flyout that appears, you'll see Increase priority or Decrease priority based on the current priority value and the number of custom policies:

    • The policy with the Priority value 0 has only the Decrease priority option available.
    • The policy with the lowest Priority value (for example, 3) has only the Increase priority option available.
    • If you have three or more policies, the policies between the highest and lowest priority values have both the Increase priority and Decrease priority options available.

    Click Increase priority icon. Increase priority or Decrease priority icon Decrease priority to change the Priority value.

  4. When you're finished, click Close in the policy details flyout.

Use the Microsoft 365 Defender portal to remove custom anti-phishing policies

When you use the Microsoft 365 Defender portal to remove a custom anti-phishing policy, the anti-phish rule and the corresponding anti-phish policy are both deleted. You can't remove the default anti-phishing policy.

  1. In the Microsoft 365 Defender portal at https://security.microsoft.com, go to Email & Collaboration > Policies & Rules > Threat policies > Anti-phishing in the Policies section. To go directly to the Anti-phishing page, use https://security.microsoft.com/antiphishing.

  2. On the Anti-phishing page, select a custom policy from the list by clicking on the name of the policy.

  3. At the top of the policy details flyout that appears, click More actions icon. More actions > Delete policy icon Delete policy.

  4. In the confirmation dialog that appears, click Yes.

Use Exchange Online PowerShell to configure anti-phishing policies

As previously described, an anti-spam policy consists of an anti-phish policy and an anti-phish rule.

In Exchange Online PowerShell, the difference between anti-phish policies and anti-phish rules is apparent. You manage anti-phish policies by using the *-AntiPhishPolicy cmdlets, and you manage anti-phish rules by using the *-AntiPhishRule cmdlets.

  • In PowerShell, you create the anti-phish policy first, then you create the anti-phish rule that identifies the policy that the rule applies to.
  • In PowerShell, you modify the settings in the anti-phish policy and the anti-phish rule separately.
  • When you remove an anti-phish policy from PowerShell, the corresponding anti-phish rule isn't automatically removed, and vice versa.

Use PowerShell to create anti-phishing policies

Creating an anti-phishing policy in PowerShell is a two-step process:

  1. Create the anti-phish policy.
  2. Create the anti-phish rule that specifies the anti-phish policy that the rule applies to.

Notes:

  • You can create a new anti-phish rule and assign an existing, unassociated anti-phish policy to it. An anti-phish rule can't be associated with more than one anti-phish policy.
  • You can configure the following settings on new anti-phish policies in PowerShell that aren't available in the Microsoft 365 Defender portal until after you create the policy:
    • Create the new policy as disabled (Enabled $false on the New-AntiPhishRule cmdlet).
    • Set the priority of the policy during creation (Priority <Number>) on the New-AntiPhishRule cmdlet).
  • A new anti-phish policy that you create in PowerShell isn't visible in the Microsoft 365 Defender portal until you assign the policy to an anti-phish rule.

Step 1: Use PowerShell to create an anti-phish policy

To create an anti-phish policy, use this syntax:

New-AntiPhishPolicy -Name "<PolicyName>" [-AdminDisplayName "<Comments>"] <Additional Settings>

This example creates an anti-phish policy named Research Quarantine with the following settings:

  • The policy is enabled (we aren't using the Enabled parameter, and the default value is $true).
  • The description is: Research department policy.
  • Changes the default action for spoofing detections to Quarantine, and uses the default quarantine policy for the quarantined messages (we aren't using the SpoofQuarantineTag parameter).
  • Enables organization domains protection for all accepted domains, and targeted domains protection for fabrikam.com.
  • Specifies Quarantine as the action for domain impersonation detections, and uses the default quarantine policy for the quarantined messages (we aren't using the TargetedDomainQuarantineTag parameter).
  • Specifies Mai Fujito (mfujito@fabrikam.com) as the user to protect from impersonation.
  • Specifies Quarantine as the action for user impersonation detections, and uses the default quarantine policy for the quarantined messages (we aren't using the TargetedUserQuarantineTag parameter).
  • Enables mailbox intelligence (EnableMailboxIntelligence), allows mailbox intelligence protection to take action on messages (EnableMailboxIntelligenceProtection), specifies Quarantine as the action for detected messages, and uses the default quarantine policy for the quarantined messages (we aren't using the MailboxIntelligenceQuarantineTag parameter).
  • Enables all safety tips.
New-AntiPhishPolicy -Name "Monitor Policy" -AdminDisplayName "Research department policy" -AuthenticationFailAction Quarantine -EnableOrganizationDomainsProtection $true -EnableTargetedDomainsProtection $true -TargetedDomainsToProtect fabrikam.com -TargetedDomainProtectionAction Quarantine -EnableTargetedUserProtection $true -TargetedUsersToProtect "Mai Fujito;mfujito@fabrikam.com" -TargetedUserProtectionAction Quarantine -EnableMailboxIntelligence $true -EnableMailboxIntelligenceProtection $true -MailboxIntelligenceProtectionAction Quarantine -EnableSimilarUsersSafetyTips $true -EnableSimilarDomainsSafetyTips $true -EnableUnusualCharactersSafetyTips $true

For detailed syntax and parameter information, see New-AntiPhishPolicy.

Note

For detailed instructions to specify the quarantine policies to use in an anti-phish policy, see Use PowerShell to specify the quarantine policy in anti-phishing policies.

Step 2: Use PowerShell to create an anti-phish rule

To create an anti-phish rule, use this syntax:

New-AntiPhishRule -Name "<RuleName>" -AntiPhishPolicy "<PolicyName>" <Recipient filters> [<Recipient filter exceptions>] [-Comments "<OptionalComments>"]

This example creates an anti-phish rule named Research Department with the following conditions:

  • The rule is associated with the anti-phish policy named Research Quarantine.
  • The rule applies to members of the group named Research Department.
  • Because we aren't using the Priority parameter, the default priority is used.
New-AntiPhishRule -Name "Research Department" -AntiPhishPolicy "Research Quarantine" -SentToMemberOf "Research Department"

For detailed syntax and parameter information, see New-AntiPhishRule.

Use PowerShell to view anti-phish policies

To view existing anti-phish policies, use the following syntax:

Get-AntiPhishPolicy [-Identity "<PolicyIdentity>"] [| <Format-Table | Format-List> <Property1,Property2,...>]

This example returns a summary list of all anti-phish policies along with the specified properties.

Get-AntiPhishPolicy | Format-Table Name,IsDefault

This example returns all the property values for the anti-phish policy named Executives.

Get-AntiPhishPolicy -Identity "Executives"

For detailed syntax and parameter information, see Get-AntiPhishPolicy.

Use PowerShell to view anti-phish rules

To view existing anti-phish rules, use the following syntax:

Get-AntiPhishRule [-Identity "<RuleIdentity>"] [-State <Enabled | Disabled] [| <Format-Table | Format-List> <Property1,Property2,...>]

This example returns a summary list of all anti-phish rules along with the specified properties.

Get-AntiPhishRule | Format-Table Name,Priority,State

To filter the list by enabled or disabled rules, run the following commands:

Get-AntiPhishRule -State Disabled | Format-Table Name,Priority
Get-AntiPhishRule -State Enabled | Format-Table Name,Priority

This example returns all the property values for the anti-phish rule named Contoso Executives.

Get-AntiPhishRule -Identity "Contoso Executives"

For detailed syntax and parameter information, see Get-AntiPhishRule.

Use PowerShell to modify anti-phish policies

Other than the following items, the same settings are available when you modify an anti-phish policy in PowerShell as when you create the policy as described in the Step 1: Use PowerShell to create an anti-phish policy section earlier in this article.

  • The MakeDefault switch that turns the specified policy into the default policy (applied to everyone, always Lowest priority, and you can't delete it) is only available when you modify an anti-phish policy in PowerShell.

  • You can't rename an anti-phish policy (the Set-AntiPhishPolicy cmdlet has no Name parameter). When you rename an anti-phishing policy in the Microsoft 365 Defender portal, you're only renaming the anti-phish rule.

To modify an anti-phish policy, use this syntax:

Set-AntiPhishPolicy -Identity "<PolicyName>" <Settings>

For detailed syntax and parameter information, see Set-AntiPhishPolicy.

Note

For detailed instructions to specify the quarantine policies to use in an anti-phish policy, see Use PowerShell to specify the quarantine policy in anti-phishing policies.

Use PowerShell to modify anti-phish rules

The only setting that isn't available when you modify an anti-phish rule in PowerShell is the Enabled parameter that allows you to create a disabled rule. To enable or disable existing anti-phish rules, see the next section.

Otherwise, no additional settings are available when you modify an anti-phish rule in PowerShell. The same settings are available when you create a rule as described in the Step 2: Use PowerShell to create an anti-phish rule section earlier in this article.

To modify an anti-phish rule, use this syntax:

Set-AntiPhishRule -Identity "<RuleName>" <Settings>

For detailed syntax and parameter information, see Set-AntiPhishRule.

Use PowerShell to enable or disable anti-phish rules

Enabling or disabling an anti-phish rule in PowerShell enables or disables the whole anti-phishing policy (the anti-phish rule and the assigned anti-phish policy). You can't enable or disable the default anti-phishing policy (it's always applied to all recipients).

To enable or disable an anti-phish rule in PowerShell, use this syntax:

<Enable-AntiPhishRule | Disable-AntiPhishRule> -Identity "<RuleName>"

This example disables the anti-phish rule named Marketing Department.

Disable-AntiPhishRule -Identity "Marketing Department"

This example enables same rule.

Enable-AntiPhishRule -Identity "Marketing Department"

For detailed syntax and parameter information, see Enable-AntiPhishRule and Disable-AntiPhishRule.

Use PowerShell to set the priority of anti-phish rules

The highest priority value you can set on a rule is 0. The lowest value you can set depends on the number of rules. For example, if you have five rules, you can use the priority values 0 through 4. Changing the priority of an existing rule can have a cascading effect on other rules. For example, if you have five custom rules (priorities 0 through 4), and you change the priority of a rule to 2, the existing rule with priority 2 is changed to priority 3, and the rule with priority 3 is changed to priority 4.

To set the priority of an anti-phish rule in PowerShell, use the following syntax:

Set-AntiPhishRule -Identity "<RuleName>" -Priority <Number>

This example sets the priority of the rule named Marketing Department to 2. All existing rules that have a priority less than or equal to 2 are decreased by 1 (their priority numbers are increased by 1).

Set-AntiPhishRule -Identity "Marketing Department" -Priority 2

Notes:

  • To set the priority of a new rule when you create it, use the Priority parameter on the New-AntiPhishRule cmdlet instead.

  • The default anti-phish policy doesn't have a corresponding anti-phish rule, and it always has the unmodifiable priority value Lowest.

Use PowerShell to remove anti-phish policies

When you use PowerShell to remove an anti-phish policy, the corresponding anti-phish rule isn't removed.

To remove an anti-phish policy in PowerShell, use this syntax:

Remove-AntiPhishPolicy -Identity "<PolicyName>"

This example removes the anti-phish policy named Marketing Department.

Remove-AntiPhishPolicy -Identity "Marketing Department"

For detailed syntax and parameter information, see Remove-AntiPhishPolicy.

Use PowerShell to remove anti-phish rules

When you use PowerShell to remove an anti-phish rule, the corresponding anti-phish policy isn't removed.

To remove an anti-phish rule in PowerShell, use this syntax:

Remove-AntiPhishRule -Identity "<PolicyName>"

This example removes the anti-phish rule named Marketing Department.

Remove-AntiPhishRule -Identity "Marketing Department"

For detailed syntax and parameter information, see Remove-AntiPhishRule.

How do you know these procedures worked?

To verify that you've successfully configured anti-phishing policies in Defender for Office 365, do any of the following steps:

  • On the Anti-phishing page in the Microsoft 365 Defender portal at https://security.microsoft.com/antiphishing, verify the list of policies, their Status values, and their Priority values. To view more details, select the policy from the list by clicking on the name and viewing the details in the flyout that appears.

  • In Exchange Online PowerShell, replace <Name> with the name of the policy or rule, and run the following command and verify the settings:

    Get-AntiPhishPolicy -Identity "<Name>"
    
    Get-AntiPhishRule -Identity "<Name>"