Integrating with Defender


This section outlines the steps required to integrate delivr.to with Microsoft 365 Defender, via the Graph API.

For this, you will need to create an App Registration in Azure, assign it the necessary privileges, and then provide delivr.to with the credentials. Let’s set this app up first.

Creating the Azure application

  • Head to the App registrations portal in Azure AD here and click New registration
  • Give it a sensible name such as delivr.to Defender Integration, leave the rest default and click Register
  • Go to API Permissions and click Add permission
  • Select Microsoft Graph and choose Application permissions
  • In the search bar, enter ThreatHunting.Read.All, check the tickbox and click Add permissions
  • Click Grant admin consent for <YOUR TENANT> and then Yes on the confirmation box
  • Go to Certificates & secrets, click New client secret, give it a sensible description and then click Add
  • Take a note of the Value as it won’t be displayed again. This is your Client Secret
  • Click Overview and take a note of the Application (client) ID and Directory (tenant) ID, this is your Client ID and Tenant ID respectively

delivr.to asks for the OAuth scope ThreatHunting.Read.All, which is the least amount of privilege required to retrieve detailed information about an email-based anti-malware event. Only two KQL queries will ever be executed, one during integration to confirm the privilege is correctly set, and one each time the status of an email is checked.

  • KQL executed during integration: 
    EmailEvents
| where Subject contains "delivr.to"
  • KQL executed during email status checking: 
    EmailEvents
| where Subject contains "<CAMPAIGN ID>"
| where RecipientEmailAddress == "<RECIPIENT ADDRESS>"

Adding the integration

  • Head to the Settings portal and navigate to the Security Tool Integrations section
  • Select the mailbox you wish to associate with this integration from the dropdown and click Integrate with Defender 365
  • Populate the fields with the Tenant ID, Client ID, and Client Secret that you generated in the previous section
  • Click Add

Defender integration

If successful, you should see this message, and your new integration will appear in the table.

Defender integration success


You’re all set! You should now be able to send your campaigns and automatically see what has been delivered!