Contents:
Connect Microsoft 365 Defender via the Graph API to gain deeper insight into how emails are evaluated by your tenant’s security tools, capture threat signatures and policy decisions.
Prerequisites
- An Azure AD tenant with Microsoft 365 Defender
- Permissions to create App Registrations and grant admin consent
- The email address validated in delivr.to
Setup Steps
1. Create an Azure App Registration
Head to the App registrations portal in Azure AD and click New registration. Give it a sensible name such as delivr.to Defender Integration, leave the rest as default, and click Register.
2. Add API Permissions
Go to API Permissions and click Add permission. Select Microsoft Graph, choose Application permissions, then search for ThreatHunting.Read.All. Check the tickbox and click Add permissions.
Click Grant admin consent for <YOUR TENANT> and confirm.
3. Generate a Client Secret
Go to Certificates & secrets, click New client secret, give it a sensible description, and click Add. Take a note of the Value — this is your Client Secret and won’t be shown again.
4. Note Your App IDs
Click Overview and note the Application (client) ID and Directory (tenant) ID.
5. Add the Integration in delivr.to
Head to Integrations in your settings and navigate to the Security Tool Integrations section. Select the mailbox you wish to associate and click Integrate with Defender 365.
Populate the fields with your Tenant ID, Client ID, and Client Secret.
6. Confirm Success
Click Add. If successful, you’ll see a confirmation message and your new integration will appear in the table.
Permissions Detail
delivr.to requests the ThreatHunting.Read.All OAuth scope — the minimum privilege required to retrieve email-based anti-malware event data. Only two KQL queries are ever executed:
| When | Query |
|---|---|
| During integration | EmailEvents | where Subject contains "delivr.to" |
| During email status check | EmailEvents | where Subject contains "<CAMPAIGN ID>" | where RecipientEmailAddress == "<RECIPIENT>" |
Troubleshooting
| Issue | Solution |
|---|---|
| Authorization fails | Check you have permission to create App Registrations and grant admin consent |
| Status stuck on Pending | Verify the client secret hasn’t expired and re-enter credentials |
| No results appearing | Ensure the validated email matches the mailbox Defender is protecting |
| Permission errors | Confirm ThreatHunting.Read.All has been granted with admin consent |