Compter les courriels externes dans Microsoft 365 via l’API de la passerelle

Le contexte : une question simple, une réponse compliquée

« Combien de courriels externes reçoit‑on réellement ? » Cette question revient souvent — pour dimensionner une passerelle, justifier un budget sécurité, ou analyser l’exposition au hameçonnage. Elle paraît triviale, mais dans Microsoft 365, y répondre précisément est étonnamment difficile, surtout pour les boîtes partagées et les listes de distribution, qui ne se comportent pas comme des boîtes classiques.

Pourquoi les méthodes évidentes échouent

Ces deux outils natifs donnent une photo partielle. Pour une mesure complète et historique, il faut regarder là où tous les courriels passent vraiment : la passerelle de sécurité.

La bonne source : la passerelle de sécurité courriel

La plupart des organisations placent, en amont d’Exchange, une passerelle de sécurité (filtre anti‑spam, anti‑hameçonnage, bac à sable de pièces jointes). Cette passerelle a deux atouts décisifs pour notre besoin :

• Elle voit chaque courriel externe à la frontière, avant même qu’Exchange le reçoive — donc aussi ceux qui seront ensuite supprimés.
• Elle conserve un historique long (souvent bien plus de 90 jours) et consultable.

Autrement dit, elle détient déjà la réponse. Il ne reste qu’à l’interroger — et la plupart de ces produits exposent une API REST pour ça.

Étape 1 — Obtenir et sécuriser une clé API

Dans le portail d’administration de la passerelle, générez une clé API (section « Security » ou « API », selon le produit). Trois règles d’or :

• Créez la clé sur un compte d’administration dédié (« API user »), pas sur un compte personnel : si ce compte est un jour désactivé, la clé meurt avec lui.
• Notez que régénérer une clé est souvent irréversible : l’ancienne cesse immédiatement de fonctionner.
• Stockez la clé dans un fichier à permissions restreintes, jamais en clair dans un script :

# Linux/macOS : fichier lisible par vous seul
umask 077
mkdir -p ~/.secrets
printf '%s' 'VOTRE_CLE_API' > ~/.secrets/passerelle.key
chmod 600 ~/.secrets/passerelle.key

Étape 2 — Découvrir l’API (base, authentification, endpoint)

Repérez dans la documentation de votre passerelle : l’URL de base de l’API, le mode d’authentification (le plus souvent un en‑tête Authorization portant la clé), et l’endpoint qui liste ou compte les messages scannés. Un premier appel de test confirme que l’authentification fonctionne :

CLE=$(cat ~/.secrets/passerelle.key)
curl -s "https://API_DE_LA_PASSERELLE/v1/messages?limit=1" \
  -H "Authorization: Bearer $CLE" | head

Étape 3 — Trouver le bon filtre (par essais successifs)

Les API de passerelle offrent en général des filtres par destinataire, par date et par verdict (propre, spam, hameçonnage…). Testez le paramètre de filtrage par destinataire sur une adresse connue pour valider la syntaxe, puis élargissez à la plage de dates voulue. Procédez par petits pas : un appel limité à quelques résultats avant de lancer un comptage complet.

Étape 4 — Le piège des listes de distribution

Attention : filtrer par destinataire fonctionne bien pour une boîte partagée (une vraie adresse de dépôt), mais pas toujours pour une liste de distribution, dont l’adresse n’est qu’un point d’éclatement vers plusieurs membres. Pour ces cas, deux approches :

• Classifier d’abord les adresses (boîte partagée vs liste de distribution vs groupe) et n’appliquer le filtre direct qu’aux boîtes partagées.
• Pour les listes, compter au niveau des membres ou via un autre critère disponible dans l’API.

Sans cette distinction, on sous‑compte silencieusement les listes — une erreur facile à commettre.

Étape 5 — Script de comptage (total sur plusieurs mois)

Une fois le filtre validé, on boucle sur la période voulue. Pour accélérer, on parallélise les appels (par mois, par destinataire). Exemple de squelette en PowerShell :

$Cle   = Get-Content "$HOME/.secrets/passerelle.key" -Raw
$Base  = "https://API_DE_LA_PASSERELLE/v1"
$Dest  = "boite-partagee@exemple.test"
$Debut = "2026-01-01"; $Fin = "2026-06-30"

$headers = @{ Authorization = "Bearer $Cle" }
$url = "$Base/messages?recipient=$Dest&from=$Debut&to=$Fin&verdict=clean"
$res = Invoke-RestMethod -Uri $url -Headers $headers
Write-Host "Total externes pour $Dest : $($res.total)"

Adaptez les noms de paramètres (recipient, from, to, verdict) à votre API. Pour une répartition par mois, exécutez le même appel sur douze fenêtres et agrégez les totaux.

Étape 6 — Variante « tendance mensuelle »

Pour obtenir une courbe plutôt qu’un simple total, découpez la période en mois et stockez chaque total dans un tableau. Vous obtenez une tendance exploitable (hausse du volume externe, pics saisonniers, effet d’une campagne de hameçonnage) — très parlante pour un rapport de direction.

Pièges à retenir

• Le Message Trace et Graph ne suffisent pas : c’est la passerelle qui détient la vérité complète.
• Filtre par destinataire ≠ listes de distribution : classifiez les adresses.
• Clé API sur un compte dédié, stockée en lieu sûr, jamais dans le code.
• Vérifiez les limites de pagination de l’API (un « total » peut être tronqué si on ne pagine pas).

À retenir

Pour mesurer précisément le volume de courriels externes dans Microsoft 365 sur une longue période, ne vous battez pas contre les limites des outils natifs : interrogez votre passerelle de sécurité courriel via son API. Avec une clé bien sécurisée, quelques appels filtrés et une attention particulière aux listes de distribution, vous obtenez des totaux fiables et des tendances mensuelles — une base solide pour vos décisions de sécurité et de budget.

Vous voulez mesurer et réduire votre exposition aux courriels externes (volume, hameçonnage, filtrage) ? Parlez à WeITSM.