Microsoft Graph API E-mail : Guide d'intégration complet pour les développeurs (2026)
L'API Microsoft Graph est le point de terminaison REST unifié pour accéder aux données d'e-mails d'Outlook et d'Exchange : lire, envoyer, rechercher et recevoir des webhooks pour chaque événement de boîte aux lettres. Ce guide vous guide dans la configuration d'OAuth 2.0, des exemples de code en direct, les limites de débit et la manière d'unifier Microsoft Graph avec Gmail et IMAP sous un seul SDK.
import demandes
# API unifiée pour e-mails Unipile
# Lit les e-mails Outlook via Microsoft Graph
BASE = "https://api.unipile.com:13465/api/v1"
EN-TÊTES = {
"X-API-KEY": "VOTRE_JETON_D_ACCES",
"Accepter": "application/json"
}
déf obtenir_les_e-mails_outlook(id_compte, limite=20):
r = requêtes.obtenir(
f"{BASE}/e-mails",
headers=HEADERS,
params={
"account_id": identifiant_compte,
"limite"limite
}
)
return r.json()["courriels"]
courriels = obtenir_les_e-mails_outlook("acc_outlook_123")
pour e en courriels :
print(e"sujet"], e["de"])Qu'est-ce que l'API Microsoft Graph pour les e-mails ?
L'API Microsoft Graph est la passerelle REST unifiée pour tous les services Microsoft 365, y compris les e-mails, le calendrier, les contacts et les fichiers. Pour les e-mails spécifiquement, elle expose le /v1.0/moi/messages point de terminaison, offrant aux développeurs un accès programmatique à chaque boîte aux lettres Outlook et Exchange. Il a remplacé les protocoles hérités (Authentification de base, EWS) et est maintenant la seule manière officiellement prise en charge d'accéder par programme aux e-mails Outlook à l'aide d'OAuth 2.0.
Le Microsoft Graph API pour les e-mails l'interface RESTful expose-t-elle les données de la boîte aux lettres Microsoft 365 – y compris les messages, les dossiers, les pièces jointes et les paramètres de la boîte aux lettres – sous https://graph.microsoft.com/v1.0/me/messages point de terminaison. Il s'authentifie via Azure Active Directory OAuth 2.0, prend en charge les autorisations déléguées et d'application et permet les événements en temps réel via modifier les abonnements aux notifications (webhooks). C'est le remplacement recommandé pour tous les flux d'authentification de base obsolètes.
API Microsoft Graph est la remplacement recommandé pour l’authentification de base obsolète – tout accès aux e-mails Outlook et Exchange nécessite désormais OAuth 2.0 via Graph. L’authentification de base a été entièrement désactivée en octobre 2022.
| Critère | Microsoft Graph API | SMTP / IMAP direct |
|---|---|---|
| Authentification | OAuth 2.0 (MSAL) | Nom d'utilisateur + mot de passe (obsolète) |
| Limites de taux | 10 000 requêtes / 10 min par application | Pas de limite standard (dépendant du serveur) |
| Fonctionnalités | Lire, envoyer, rechercher, webhooks, dossiers | Limité : envoi/réception de base uniquement |
| Complexité | Flux OAuth + Enregistrement d'application Azure | Faible mise en place, entretien élevé |
| Soutien d'Unipile | Natif - aucun flux OAuth nécessaire | Natif - Repli IMAP |
Pourquoi utiliser l'API Microsoft Graph pour l'intégration d'e-mails ?
S'appuyer sur Microsoft Graph permet à votre application d'accéder de manière sécurisée, basée sur des jetons, au plus grand écosystème de messagerie d'entreprise au monde, couvrant plus de 400 millions de boîtes aux lettres Outlook et Exchange. Voici les quatre principales raisons pour lesquelles les développeurs choisissent le point de terminaison d'e-mail de l'API Microsoft Graph.
Une seule inscription d'application Azure couvre toutes les boîtes aux lettres Outlook, Exchange et Microsoft 365. Les autorisations déléguées permettent aux utilisateurs de consentir une seule fois ; les autorisations d'application permettent un accès côté serveur sans surveillance et sans interaction utilisateur.
Lisez, envoyez, répondez, déplacez et supprimez des messages. Gérez les dossiers, recherchez l'intégralité de la boîte aux lettres, traitez les pièces jointes et définissez des règles de messagerie – le tout via la même interface REST avec un schéma de réponse JSON prévisible.
Abonnez-vous aux notifications de changement de boîte aux lettres et recevez un POST HTTP sur votre point de terminaison chaque fois qu'un nouvel e-mail arrive, qu'un message est lu ou qu'un dossier est modifié. Pas de sondage, pas de délais - événements livrés en quasi temps réel.
Un seul point de terminaison d'API couvre les comptes Outlook personnels, les locataires Microsoft 365 professionnels et les serveurs Exchange locaux (via hybride). Une seule intégration gère l'ensemble de l'écosystème de messagerie Microsoft sans chemins de code distincts.
Configuration de l'authentification OAuth Microsoft pour l'API Outlook
Microsoft OAuth DocsPar défaut, votre intégration utilise les identifiants OAuth d'Unipile. Pour obtenir un expérience entièrement en marque blanche Lorsque les utilisateurs finaux connectent leur compte Microsoft, créez votre propre application dans Microsoft Entra ID. Suivez le 7 étapes ci-dessous pour enregistrer votre application, configurer les autorisations et la connecter à Unipile.
Créer un compte Microsoft Entra ID
Si vous n'en avez pas déjà un, créez gratuitement Microsoft Entra ID compte (anciennement Azure Active Directory). C'est le portail d'administration où vous enregistrerez votre application OAuth.
Enregistrer une nouvelle application dans le portail Azure
Se connecter à portal.azure.com, allez à Microsoft Entra ID, et cliquez Nouvelle inscription.
- Nommez votre application : ce nom sera visible par vos utilisateurs finaux lors de l'écran de consentement OAuth.
- Types de comptes pris en charge : sélectionnez "Comptes dans n'importe quel répertoire organisationnel (tout Microsoft Entra ID, multilocataire) et comptes Microsoft personnels" pour prendre en charge les comptes Office 365 professionnels et personnels.
Ajouter les URI de redirection
Allez au Authentification panneau et cliquez Ajouter l'URI sous la section Web. Ajouter 2 URI de redirection en utilisant votre Unipile DSN (disponible dans la tableau de bord Unipile, en haut à droite)
https://{{YOUR_DSN_less_port}}/api/v1/hosted/microsoft_auth_request_callback/port{{YOUR_PORT}}
Configurer les autorisations de l'API
Aller à Permissions de l'API > Ajouter une autorisation > Microsoft Graph, puis ajoutez ce qui suit Autorisations déléguées:
Pour les fonctionnalités de calendrier, ajoutez également : Calendars.ReadWrite, Calendars.Read, Calendars.Read.Shared, Calendars.ReadWrite.Shared. Ajoutez-les également dans vos paramètres de portée du tableau de bord Unipile.
Créer un secret client
Aller à Certificats et secrets, cliquer Nouveau secret client. Nommer le secret et fixer une date d'expiration 730 jours (24 mois), puis cliquez sur "Ajouter".
Se connecter au tableau de bord Unipile
Allez au tableau de bord Unipile, navigatez vers Paramètres > Microsoft OAuth.
- Copier-coller le ID de l'application (client) depuis la page Vue d'ensemble d'Azure.
- Collez le valeur secrète depuis la page Certificats et secrets.
- Cliquer Économiser.
Tester la connexion
Depuis le tableau de bord Unipile, déclenchez un nouveau lien de compte Microsoft pour vérifier que vos identifiants OAuth personnalisés fonctionnent correctement. Vous devriez voir votre nom de l'application et l'image de marque dans l'invite de consentement de Microsoft au lieu des valeurs par défaut d'Unipile.
8
Devenir un éditeur vérifié
Recommandé pour la production, supprime l'avertissement "non vérifié" sur l'écran de consentement
Avec la vérification, une coche bleue apparaît dans l'invite de consentement. Sans elle, les comptes professionnels peuvent voir un avertissement "éditeur non vérifié".
Étape 1 : Rejoignez le Microsoft Partner Network
- Inscription à partenaire.microsoft.com et choisir Programme Partenaire Microsoft Cloud AI.
- Si vous avez besoin d'un compte professionnel, créer un nouvel locataire d'abord.
Étape 2 : Vérifiez votre domaine
Créer un fichier nommé microsoft-identity-association.json et l'héberger à :
Étape 3 : Associer votre identifiant Partner Global Account (PGA)
- Trouvez votre identifiant PGA via Centre partenaires.
- Dans le portail Azure, accédez à Enregistrements d'applications > Votre application > Image de marque et propriétés, entrez l'ID PGA, et enregistrez.
Pour plus de détails, consultez le Documentation de vérification Microsoft Publisher.
9
Gestion de "Approbation de l'administrateur requise"
Quand les utilisateurs finaux voient un bloc de consentement de la part de leur administrateur informatique
Si un utilisateur voit "Approbation de l'administrateur requise", le consentement requis n'a pas été accordé au niveau du locataire. Deux méthodes pour résoudre ce problème :
Méthode 1 : Demande de consentement de l'administrateur dans Microsoft Entra
Un administrateur Microsoft doit examiner et approuver la demande de consentement d'administrateur en attente. Voir Documentation Microsoft sur la révision des demandes de consentement administrateur.
Méthode 2 : Connexion OAuth en tant qu'administrateur avec consentement à l'échelle du locataire
- L'administrateur démarre le flux de connexion OAuth à partir de votre application.
- Lors de l'autorisation Microsoft, l'administrateur doit cocher : "Consentement au nom de votre organisation".
- Ceci accorde le consentement pour tous les utilisateurs de l'organisation et empêche l'invite pour les futurs utilisateurs.
Plein de détails dans le Guide de dépannage du consentement Microsoft.
Cas d'utilisation des e-mails dans Microsoft Graph API
L'endpoint d'e-mail de l'API Microsoft Graph alimente un large éventail d'applications SaaS qui s'appuient sur les boîtes aux lettres Outlook et Exchange. Voici les trois modèles d'intégration les plus courants utilisés aujourd'hui par les équipes développant sur l'API Graph.
Synchronisez les fils d'e-mails et les contacts Outlook directement dans votre CRM. Faites correspondre les expéditeurs aux enregistrements de transactions existants, enregistrez automatiquement chaque conversation et affichez l'historique des relations sans aucune copie manuelle depuis Outlook.
Guide de l'API EmailSuivez les fils d'e-mails des candidats dans les boîtes aux lettres Outlook. Analysez les e-mails de candidature entrants, extrayez les pièces jointes et acheminez-les vers le bon pipeline d'emploi - le tout via le point de terminaison d'e-mail de l'API Microsoft Graph sans aucune intervention manuelle.
API d'envoi de courrielsConvertir les e-mails Outlook entrants en tickets de support. Utiliser des webhooks Graph pour recevoir des événements de nouveaux e-mails en temps réel, classifier par sujet ou domaine d'expéditeur, et router vers la bonne file d'attente d'équipe - remplaçant ainsi le triage manuel par une logique automatisée.
API unifiée pour les e-mailsPrincipales fonctionnalités de l'API Microsoft Graph pour les e-mails
L'API Microsoft Graph pour les e-mails expose un ensemble complet de fonctionnalités bien au-delà de l'envoi et de la réception de base. Voici les six fonctionnalités les plus importantes que tout développeur devrait connaître avant de construire sur la pile d'e-mails de l'API Microsoft Graph.
Récupérez des messages individuels ou des listes paginées. Envoyez de nouveaux e-mails ou répondez en ligne. Déplacez des messages entre les dossiers ou marquez-les comme lus/non lus.
GET /v1.0/moi/messagesTélécharger, importer et lister les pièces jointes de fichiers sur n'importe quel message. Prend en charge les pièces jointes incorporées (en ligne) et le téléchargement de gros fichiers via des sessions de téléchargement pour les fichiers de plus de 3 Mo.
GET /v1.0/moi/messages/{id}/pièces jointesCréer, renommer et supprimer des dossiers de messagerie. Lister tous les dossiers de messagerie, déplacer des messages entre eux et gérer les hiérarchies de dossiers enfants, identiques à ce que les utilisateurs voient dans Outlook.
GET /v1.0/moi/dossiersCourrierUtilisez les paramètres de requête OData ($filter,$search, $orderby) pour trouver des e-mails par expéditeur, objet, plage de dates ou mot-clé. Prend en charge KQL pour la recherche plein texte avancée.
GET /moi/messages?$rechercher="projet"Abonnez-vous aux notifications de modification pour les événements de boîte aux lettres. Recevez des rappels HTTP POST quasi en temps réel lorsqu'un nouvel e-mail arrive, que des messages sont lus ou que des dossiers changent.
POST /v1.0/abonnementsCombinez jusqu'à 20 requêtes individuelles de l'API Graph en un seul appel HTTP à l'aide du point de terminaison batch $. Réduit considérablement les allers-retours pour des opérations telles que la lecture d'e-mails en masse.
POST /v1.0/$lotComment envoyer, lire et synchroniser des e-mails avec l'API Microsoft Graph
Trois modèles prêts pour la production couvrant les opérations essentielles dont tout développeur a besoin : l'envoi d'e-mails, la lecture de messages avec filtres et la synchronisation différentielle incrémentielle pour la surveillance de la boîte aux lettres en temps réel.
import demandes
# API unifiée pour e-mails Unipile
# Envoie via Microsoft Graph — aucun OAuth direct requis
BASE = "https://api.unipile.com:13465/api/v1"
EN-TÊTES = {
"X-API-KEY": "VOTRE_JETON_D_ACCES",
"Content-Type": "application/json"
}
déf envoyer_email_outlook(id_compte, à, sujet, corps)
charge utile = {
"account_id": identifiant_compte,
"à": [{"identifier": à}],
"sujet": sujet,
"corps": corps
}
r = requêtes.postef"{BASE}/courriels", en-têtes=EN-TÊTES, json=charge utile
return r.json()
# Exemple d'utilisation
envoyer_email_outlook(
"acc_outlook_123",
à="recipient@company.com",
sujet="Suivi de réunion",
corps="Bonjour, pour faire suite à notre appel..."
)POST https://graph.microsoft.com/v1.0/moi/envoyerEmail avec message.destinataires, objet du message, ou encore message.corps.contenu. Unipile abstrait le rafraîchissement du jeton OAuth et la gestion du MIME. Voir le Guide API d'envoi d'e-mails pour le support des pièces jointes et la réponse hiérarchisée.
import demandes
# Lire les e-mails Outlook avec des filtres via Unipile
BASE = "https://api.unipile.com:13465/api/v1"
EN-TÊTES = {"X-API-KEY": "VOTRE_JETON_D_ACCES"}
déf lister_les_emails_outlook(id_compte, filtre_expéditeur=Aucun, limite=20):
paramètres = {
"account_id": identifiant_compte,
"limite"limite
}
si filtre_expéditeur :
# Correspond à $filtre=from/emailAddress/address eq '...'
params["de"] = filtre_expéditeur
r = requêtes.obtenirf"{BASE}/courriels", en-têtes=En-têtes, paramètres=params)
return r.json().obtenir("articles", [])
# Récupérer les 20 derniers e-mails d'un expéditeur spécifique
courriels = lister_les_emails_outlook("acc_outlook_123", filtre_expéditeur="hr@acme.com")
pour e en courriels :
print(e"sujet"], e["de"], e["date"])$filtre, $rechercher, $sélectionner, $trier par, $au-dessus. utiliser $recherche="sujet:facture" pour la recherche plein texte KQL. Les pièces jointes de plus de 3 Mo nécessitent une télécharger la session (POST /createUploadSession) — pas une seule requête multipart.
import demandes
# Delta Sync — récupérer uniquement les e-mails NOUVEAUX depuis la dernière synchronisation
# Unipile gère le cycle de vie de deltaToken automatiquement
BASE = "https://api.unipile.com:13465/api/v1"
EN-TÊTES = {"X-API-KEY": "VOTRE_JETON_D_ACCES"}
déf synchroniser_nouveaux_emails(id_compte, curseur=Aucun :
"""
Retourne uniquement les emails reçus depuis le dernier appel.
curseur = jeton de pagination opaque (à stocker entre les appels).
"""
paramètres = {"account_id": id_compte}
si curseur
params["curseur"] = curseur
r = requêtes.obtenirf"{BASE}/emails/synchroniser", en-têtes=En-têtes, paramètres=params)
données = r.json()
return data.get("articles", []), données.get("curseur")
# Première synchronisation — pas de curseur
e-mails, curseur_suivant = synchroniser_nouveaux_emails("acc_outlook_123")
# Stocker le next_cursor dans votre DB, utilisez-le pour les appels ultérieurs
printf"{len(emails)} nouveaux emails — curseur suivant sauvegardé")GET /me/mailFolders/inbox/messages/delta retourne un @odata.deltaLink lors du premier appel. Stockez-le et utilisez-le la prochaine fois - Graph ne retourne que la différence. Aucun sondage boîte aux lettres pleine = 10 fois moins d'appels API par rapport à la norme GET /messages. Unipile's /e-mails/synchronisation endpoint encapsule ce modèle avec une gestion automatique des jetons.
Webhooks de l'API Microsoft Graph pour les événements d'e-mail
Les abonnements Microsoft Graph (webhooks) permettent à votre serveur de recevoir des notifications HTTP POST dès l'arrivée, la lecture, le déplacement ou la suppression d'un e-mail. Vous trouverez ci-dessous un exemple Python complet pour vous abonner aux événements de la boîte de réception, ainsi que des détails sur la gestion du cycle de vie.
Un abonnement webhook Graph a deux champs obligatoires : changerType (quelles épreuves regarder) et notificationUrl (votre point de terminaison HTTPS). Microsoft envoie une jeton de validation paramètre de requête lors du premier abonnement. Votre point de terminaison doit le renvoyer en texte brut dans les 10 secondes pour confirmer la propriété.
Les abonnements aux graphiques expirent au maximum après 4230 minutes (~3 jours) pour les ressources de messagerie. Votre serveur doit renouveler avant l'expiration via PATCH /v1.0/abonnements/{id} ou vous cesserez de recevoir les notifications silencieusement.
Notifications de cycle de vie
URLDeNotificationDeCycleDeVie lorsqu'un abonnement est sur le point d'expirer ou a été révoqué. Votre serveur doit répondre avec un code HTTP 202 pour accuser réception. Un échec de réponse entraîne la résiliation de l'abonnement.validationToken Handshake
?validationToken=XXX. Vous devez retourner le jeton sous forme de texte brut (Content-Type: text/plain) avec un code de réponse HTTP 200 dans les 10 secondes. Le dépassement du délai entraîne l'échec de la création de l'abonnement.Expiration de l'abonnement
dateHeureExpiration avant qu'il n'expire. Vous pouvez également recréer un abonnement à partir de zéro. Microsoft ne facture pas de frais supplémentaires pour les renouvellements.import demandes, date et heure
JETON_ACCÈS = "VOTRE_JETON_GRAPHE"
POINT DE TERMINAISON = "https://graph.microsoft.com/v1.0/abonnements"
# Date d'expiration : maximum 4230 min à partir de maintenant pour les ressources de messagerie
expiration = (
datetime.datetime.maintenant UTC()
+ datetime.timedelta(minutes=4200)
).isoformat() + "Z"
charge utile = {
"changer le type": "créé",
"urlDeNotification": "https://votredomaine.com/webhook",
"ressource": "mes/dossiersCourrier('Courrier entrant')/messages",
"dateEtHeureExpiration": expiration,
"étatClient": "monÉtatSecret"
}
r = requêtes.poste(
POINT DE TERMINAISON,
json=charge utile,
en-têtes={
"Autorisation": Bearer {ACCESS_TOKEN}",
"Content-Type": "application/json"
}
)
print(r.json()["id"])
# sub_xxxxxxxx-xxxx-xxxx-xxxxÉvitez la Complexité - Utilisez l'API d'Email Unifiée d'Unipile
Connectez Microsoft Graph, Gmail et IMAP avec un seul SDK. Fini les flux OAuth par fournisseur, la logique de rafraîchissement des jetons ou l'infrastructure de webhook à maintenir. Votre équipe livre des fonctionnalités d'e-mail en quelques jours, pas en quelques semaines.
Commencer gratuitementAucune carte de crédit requise. Conforme SOC 2 Type II.
Limites de débit et gestion des erreurs de l'API Microsoft Graph
Le point de terminaison de messagerie de l'API Microsoft Graph applique la limitation à plusieurs niveaux : par utilisateur, par application et par locataire. Comprendre ces limites avant de passer en production permet d'éviter les échecs silencieux et la dégradation de la fiabilité de votre intégration.
Lorsque le débit est limité, Microsoft Graph renvoie 429 Trop de requêtes avec un Réessayer après En-tête spécifiant le nombre de secondes à attendre. Lisez toujours cet en-tête et attendez en conséquence - bombarder après un 429 prolongera la fenêtre de limitation, pas la réduira.
| Code HTTP | Nom d'erreur | Cause | Réparer |
|---|---|---|---|
| 429 | TropDeDemandes | Limite de débit dépassée (10 000 requêtes / 10 min par application ou 1 000 requêtes / 1 min par utilisateur) | Lire l'en-tête Retry-After. Implémenter une backoff exponentielle. Utiliser le lot $pour combiner les requêtes. |
| 401 | Non autorisé | Jeton d'accès expiré ou en-tête d'autorisation manquant | Actualiser le jeton via MSAL. Vérifier l'expiration du jeton avant chaque requête. Utiliser la mise en cache des jetons. |
| 403 | Interdit | Permission Mail.Read ou Mail.Send manquante dans l'enregistrement de l'application Azure | Ajouter les autorisations Graph requises dans le portail Azure et donner à nouveau le consentement (ou le consentement de l'administrateur pour les autorisations de l'application). |
| 404 | RessourceIntrouvable | L'identifiant du message ou de dossier n'existe pas (supprimé ou locataire incorrect) | Vérifier les identifiants via GET avant d'agir en conséquence. Gérer le 404 avec élégance comme un signal de suppression douce. |
| 500 | Erreur interne du serveur | Erreur transitoire du serveur Microsoft | Réessayez avec une stratégie de retrait exponentiel (1s, 2s, 4s). Enregistrez l'en-tête request-id pour le support Microsoft. |
Au-delà de Microsoft Graph : API unifiée pour les e-mails de Gmail, Outlook et IMAP
La gestion de l'intégration des e-mails de l'API Microsoft Graph n'est qu'un début. La plupart des produits SaaS doivent prendre en charge Gmail, Outlook et IMAP simultanément – ce qui signifie trois flux OAuth distincts, trois boucles de rafraîchissement de jetons et trois systèmes de webhook. Unipile's API unifiée pour les e-mails abstraire les trois fournisseurs derrière un point de terminaison unique.
Avec Unipile, Intégration d'API d'e-mail unifiée, vous écrivez une intégration et supportez instantanément les trois types de fournisseurs. Les comptes liés sont gérés par Unipile - votre backend ne communique qu'avec un seul point d'extrémité REST, que la boîte aux lettres de l'utilisateur fonctionne sur Microsoft Graph, Gmail ou IMAP.
Aucun flux OAuth à gérer Unipile gère l'acquisition, le renouvellement et la révocation des jetons pour Microsoft Graph et Gmail en votre nom.
Événements de webhook unifiés - une notificationUrl reçoit les événements d'e-mail de tous les fournisseurs avec un schéma JSON normalisé. Aucune gestion des abonnements par fournisseur.
Conforme SOC 2 Type II - toutes les données d'e-mail en transit sont chiffrées. Unipile ne stocke pas le contenu des e-mails au-delà de ce qu'exige votre intégration.
Commencez à intégrer l'e-mail Microsoft Graph en quelques minutes
Rejoignez plus de 200 équipes SaaS qui utilisent Unipile pour connecter Outlook, Gmail et IMAP sous une seule API. Pas de verrouillage propriétaire. Conforme SOC 2.
Questions fréquemment posées
Tout ce que les développeurs demandent avant de construire sur le point de terminaison de messagerie de l'API Microsoft Graph - de l'authentification aux limites de débit en passant par la couverture des fournisseurs.
https://graph.microsoft.com/v1.0/me/messages et utilise l'authentification OAuth 2.0 via Azure Active Directory. Il prend en charge la lecture, l'envoi, la recherche et la gestion des e-mails, ainsi que la réception de notifications de changements en temps réel via des abonnements webhook./v1.0/abonnements avec un changerType (par exemple, " créé "), un notificationUrl en pointant vers votre point de terminaison HTTPS, et un ressource (par exemple, " me/mailFolders('Inbox')/messages "). Microsoft envoie immédiatement une requête GET avec un jeton de validation - votre serveur doit le renvoyer en texte brut dans les 10 secondes. Les abonnements expirent après 4230 minutes maximum et doivent être renouvelés via PATCH avant l'expiration.