Démarrer

Comment lire les e-mails via une API : un guide du développeur pour l'accès à la boîte de réception (2026)

Table des matières
Parcourir les sections
Guide du développeur 2026

Comment lire les e-mails via une API : Guide pour développeurs Accès à la boîte de réception

Portée : Ce guide couvre API synchronisées pour la lecture des boîtes de réception existantes des utilisateurs - API Gmail, Microsoft Graph, IMAP et couches unifiées comme Unipile. Ceci est distinct des services transactionnels (SendGrid, Mailgun) qui envoient des e-mails sortants depuis votre domaine.

Concevez des produits qui lisent les e-mails des utilisateurs par programme. À partir d'un seul GET /api/v1/emails Appels aux webhooks en temps réel, ce guide couvre chaque approche avec du code fonctionnel en Node.js, Python et cURL.

Commencez l'essai gratuit Guide de l'API Email
read_inbox.js
// Lire les courriels avec un seul appel API unifié const response = await fetch( 'https://api3.unipile.com:PORT/api/v1/emails', { headers : { 'X-API-KEY': process.env.UNIPILE_API_KEY, 'identifiant_de_compte': accountId } } ); const { e-mails } = await réponse.json(); // Même forme JSON pour Gmail, Outlook et IMAP e-mails.chaque(courriel => { console.log(Objet du courriel, participant principal); });
200 OK - 47 e-mails retournés (Gmail + Outlook + IMAP)
Fonctionne avec : Gmail Outlook IMAP Gmail, Outlook et IMAP
Définition

Qu'est-ce qu'une API de lecture d'e-mails ?

Une API de lecture d'e-mails est une interface HTTP qui permet à votre application d'accéder, de récupérer et de traiter les e-mails de la boîte aux lettres existante d'un utilisateur, sans stocker de mots de passe ni créer d'intégrations spécifiques au fournisseur. C'est la base de tout produit nécessitant une visibilité sur la boîte de réception : synchronisation CRM, copilotes d'e-mails IA, automatisation du support ou archivage de conformité.

Définition rapide

Une lire l'API des e-mails expose des points d'accès pour s'authentifier auprès de la boîte aux lettres d'un utilisateur (via OAuth 2.0 ou des identifiants IMAP), lister les messages de la boîte de réception, récupérer les corps complets des e-mails avec pièces jointes, et s'abonner aux événements de livraison en temps réel. Il fonctionne sur le compte Gmail, Outlook ou IMAP existant de l'utilisateur. pas un domaine que vous contrôlez. Cela le distingue des API d'e-mails transactionnels (SendGrid, Mailgun, Resend), qui envoient des e-mails sortants pour le compte de votre application.

Ce guide couvre
APIs de synchronisation/lecture d'e-mails

Connectez-vous aux boîtes de réception existantes des utilisateurs. Lisez, synchronisez et réagissez aux e-mails en temps réel. Authentification via OAuth 2.0 ou IMAP. L'utilisateur accorde l'accès à sa propre boîte aux lettres.

Exemples : API Gmail, Microsoft Graph, IMAP, Unipile
Pas ce guide
API d'e-mails transactionnels

Envoyer des e-mails sortants à partir d'un domaine que vous contrôlez. Utilisé pour les reçus, les notifications, les réinitialisations de mot de passe. Pas d'accès à la boîte de réception.

Exemples : SendGrid, Mailgun, Resend, Postmark
Cas d'usage

Pourquoi la lecture par programme des e-mails est importante

« La capacité de lire les e-mails des utilisateurs via une API débloque une catégorie de produits qui étaient tout simplement impossibles avec SMTP seul. Voici les quatre principaux cas d'utilisation qui stimulent l'adoption en 2026. ».

Synchronisation CRM et Sales Engagement

Les outils de vente doivent pouvoir consulter tous les échanges d'e-mails entre un commercial et un prospect, automatiquement, sans saisie manuelle. Une API de lecture d'e-mails extrait les conversations directement de la boîte de réception du commercial et les synchronise en temps réel avec votre CRM.

Enregistrer automatiquement les échanges par e-mail dans les fiches de contact
Analyser les signaux pertinents pour les transactions à partir des fils de discussion de la boîte de réception
Détecter l'intention de réponse et mettre à jour l'étape du pipeline

Agents IA et copilotes d'e-mail

Les grands modèles linguistiques ont besoin de contexte. En fournissant à votre agent IA un flux d'e-mails de boîte de réception en temps réel, vous pouvez créer des copilotes qui rédigent des réponses, résument des fils de discussion, extraient les éléments d'action et priorisent automatiquement les conversations.

Diffuser les nouveaux e-mails vers un pipeline de traitement LLM
Générer des brouillons de réponses contextuels
Extraire les tâches, les dates et les engagements des fils de discussion

Automatisation du support client

Les équipes de support reçoivent des milliers d'e-mails par jour. Une API d'e-mail lu permet à votre plateforme de classer les demandes entrantes, de les acheminer vers la bonne file d'attente et de déclencher des réponses automatisées, le tout avant qu'un humain n'ouvre un ticket.

Classifier les e-mails de support par sujet et urgence
Routage vers des files d'attente d'agents en fonction du contenu de l'e-mail
Déclencher des réponses automatiques pour les modèles de requêtes courants

Conformité, Archivage et eDiscovery

Les industries réglementées doivent conserver et indexer chaque e-mail. Une API d'e-mail lu fournit l'accès programmatique nécessaire pour archiver continuellement les boîtes de réception, signaler les violations de politique et produire des enregistrements d'e-mail sur demande pour un examen juridique.

Archivage continu de la boîte de réception pour la conformité GDPR / FINRA
Détection de violations de politiques dans les boîtes aux lettres des employés
Exportation eDiscovery à la demande pour mise sous séquestre légale
Approfondissement du fournisseur

API natives pour la lecture d'e-mails : Gmail, Outlook et IMAP

Chaque fournisseur de messagerie majeur expose sa propre API de lecture avec différents points de terminaison, modèles d'authentification et capacités. Voici à quoi ressemble chacune en pratique.

API Gmail

OAuth 2.0

L'API Gmail est une API REST construite sur l'infrastructure de Google. Elle utilise Utilisateurs.messages.lister pour paginer une boîte aux lettres et utilisateurs.messages.obtenir pour récupérer un message complet. Il prend en charge les notifications push via Google Pub/Sub, rendant ainsi la surveillance de la boîte de réception en temps réel réalisable sans interroger. Limite de débit : 250 unités de quota par utilisateur et par seconde.

gmail_lire.sh
# Récupérer la liste des messages de la boîte de réception (API Gmail) curl -X OBTENIR \ "https://gmail.googleapis.com/gmail/v1/users/me/messages?labelIds=INBOX&maxResults=20" \ -H "Autorisation : Bearer JETON_ACCES" # Récupérer un seul e-mail avec le corps complet curl -X OBTENIR \ "https://gmail.googleapis.com/gmail/v1/users/me/messages/MESSAGE_ID?format=full" \ -H "Autorisation : Bearer JETON_ACCES"
Remarque : Gmail renvoie les messages sous forme de parties MIME encodées en base64. Vous devez décoder chaque partie et analyser vous-même les délimiteurs multipart pour extraire le corps en texte brut, le corps HTML et les pièces jointes.

Microsoft Graph (Outlook et Microsoft 365)

OAuth 2.0

Microsoft Graph est l'API unifiée pour tous les services Microsoft 365, y compris les comptes personnels Outlook, Exchange Online et les boîtes aux lettres professionnelles Microsoft 365. Le /moi/messages le point de terminaison renvoie les messages avec le contenu complet du corps dans une seule requête. La pagination utilise $skip et $au-dessus Paramètres OData. Voir le complet Guide d'intégration de la messagerie Microsoft Graph pour plus de détails.

graph_read.sh
# Répertorier les messages de la boîte de réception (Microsoft Graph) curl -X OBTENIR \ " https://graph.microsoft.com/v1.0/me/messages?\$top=20&\$filter=parentFolderId eq 'inbox' ' \ -H "Autorisation : Bearer JETON_ACCES" \ -H "Content-Type: application/json" # Récupérer un seul message avec son corps curl -X OBTENIR \ " https://graph.microsoft.com/v1.0/me/messages/MESSAGE_ID?\$select=subject,body,from,receivedDateTime " \ -H "Autorisation : Bearer JETON_ACCES"
Remarque : Microsoft Graph limite à 10 000 requêtes par 10 minutes par application et par client. Le contenu du corps est renvoyé sous forme de HTML ou de texte en fonction du $sélectionner et Accepter en-têtes.

IMAP

Protocole Universel

IMAP (Internet Message Access Protocol) est le protocole de messagerie universel pris en charge par pratiquement tous les serveurs de messagerie. Ce n'est pas une API REST mais une connexion TCP stateful sur le port 993 (TLS). Vous émettez des commandes telles que CHERCHER, RECHERCHE, ou encore INACTIF sur la connexion. Pour une analyse plus approfondie, consultez notre Guide d'intégration de l'API IMAP.

imap_read.py
import imaplib, l'email # Connexion et authentification courriel = imaplib.IMAP4_SSL('imap.example.com') courriel.Se connecter('user@example.com', 'mot_de_passe_application') courriel.sélectionner('BOÎTE DE RÉCEPTION') # À la recherche de messages cachés statut, identifiants_message = courriel.recherche(Aucun, 'INVISIBLES') pour identifiant_message en message_ids[0].divisé(): _, données = courriel.fetch(id_message, '(RFC822)') message = courriel.message_des_octets(données[0][1]) print(msg['sujet'], msg['de'])
Remarque : IMAP nécessite le maintien de connexions TCP de longue durée et la gestion de pools de connexions par vos soins. La livraison en temps réel utilise le INACTIF commande, qui maintient une connexion ouverte et attend les notifications du serveur. Cela ne s'adapte pas facilement au-delà de quelques centaines de comptes simultanés.
Qu'en est-il de Yahoo et d’autres fournisseurs ?

Yahoo Mail, ProtonMail, Zoho et d'autres fournisseurs prennent tous en charge IMAP comme solution de repli universelle, ils sont donc couverts par l'approche IMAP ci-dessus. Certains (comme Yahoo) exposent également des API propriétaires limitées, mais aucune ne correspond aux capacités de l'API Gmail ou de Microsoft Graph. Pour la plupart des produits multi-fournisseurs, IMAP est la solution de repli universelle pour toute boîte aux lettres non couverte par Gmail ou Outlook OAuth. A API unifiée pour les e-mails gère cette négociation automatiquement.

Ingénierie de la réalité

La complexité cachée de la lecture d'e-mails à grande échelle

Créer une intégration d'API pour lire les e-mails auprès d'un seul fournisseur pour une démo prend un après-midi. En créer une qui fonctionne de manière fiable sur tous les fournisseurs à l'échelle de la production est un défi tout à fait différent. Voici ce que l'ingénierie implique réellement.

01

Flux OAuth par fournisseur

Chaque fournisseur a sa propre implémentation OAuth 2.0, ses exigences en matière d'écran de consentement, ses scopes et son cycle de vie de token. La prise en charge de Gmail et Outlook implique le maintien de deux applications OAuth distinctes, de deux consoles développeur, de deux stratégies de rafraîchissement de token et de deux ensembles d'exigences de conformité (Google CASA Tier 2, Microsoft Publisher Verification).

Gmail :Application Google Cloud Console, CASA Niveau 2 pour les scopes sensibles, jetons d'accès d'une heure
Outlook :Enregistrement d'application Azure AD, Vérification de l'éditeur, TTL de jeton configurable
IMAP :Mots de passe d'application ou OAuth (IMAP de Gmail utilise le même flux OAuth de Google)
02

Différences de pagination

Chaque fournisseur pagine différemment. Gmail utilise des jetons de page opaques. Microsoft Graph utilise OData $skip et lienSuivant curseurs. IMAP utilise des plages d'UID numériques. L'implémentation d'une abstraction de pagination cohérente pour les trois nécessite un code d'adaptateur non trivial.

Gmail :jeton de page curseur, max 500 résultats par page
Graphique :URL @odata.nextLink, paramètres $top/$skip
IMAP :UID FETCH ranges, CONDSTORE pour synchronisation incrémentielle
03

Analyse MIME

Les e-mails arrivent sous forme de documents MIME bruts avec des délimitations multipart imbriquées, un encodage en base64 ou quoted-printable, plusieurs jeux de caractères et des pièces jointes en ligne. Gmail renvoie des parties encodées en base64url. IMAP renvoie du RFC 822 brut. Aucun des deux ne vous donne un corps texte brut et propre sans analyser l'arborescence MIME complète.

Risque :Les caractères internationaux, les émojis et le texte RTL introduisent des cas limites d'encodage qui corrompent le contenu du corps.
Pièces jointes :Doit parcourir l'arbre MIME pour trouver les parties Content-Disposition : attachment
04

Limites de taux et retrait

Gmail applique 250 unités de quota par utilisateur par seconde (lister un coût 5 unités, récupérer 5 unités). Microsoft Graph limite à 10 000 requêtes par 10 minutes par application par locataire. Les deux renvoient des erreurs 429 qui nécessitent un backoff exponentiel avec jitter. À 1 000 comptes liés, la gestion des limites de débit devient un problème d'ingénierie à part entière.

Gmail :250 unités de quota par seconde par utilisateur. Plafond quotidien : 1 milliard d'unités
Graphique :10 000 req / 10 min / app / locataire. En-tête Retry-After
IMAP :Spécifique au fournisseur, généralement 10-20 connexions simultanées par compte
05

Temps réel : Webhooks vs Interrogation vs IDLE

Recevoir des notifications lors de l'arrivée d'un nouvel e-mail nécessite des mécanismes complètement différents par fournisseur. Gmail utilise les abonnements push de Google Pub/Sub qui doivent être renouvelés tous les 7 jours. Microsoft Graph utilise des abonnements de notification de modification avec une durée de vie maximale de 4 230 minutes. IMAP utilise la commande IDLE, qui maintient une connexion TCP persistante ouverte par compte.

Gmail :Jour de pousser, expiration de 7 jours, cycle de renouvellement requis
Graphique :Abonnement aux notifications, expiration maximale d'environ 3 jours
IMAP :Commande IDLE, 1 connexion TCP persistante par compte
06

Incohérences de fil entre les fournisseurs

Gmail regroupe les messages en fils de discussion de manière native. Microsoft Graph possède un champ conversationId mais les fils de discussion se comportent différemment de Gmail. IMAP n'a pas de fils de discussion natifs - vous reconstruisez les fils de discussion en faisant correspondre manuellement les en-têtes References et In-Reply-To. La construction d'une vue de fil de discussion unifiée inter-fournisseurs nécessite une logique de normalisation importante.

Gmail :threadId natif, messages.list?labelIds=INBOX retourne des groupes de fils
Graphique :conversationId, mais pas équivalent aux fils Gmail
IMAP :Doit analyser manuellement les en-têtes Message-ID / References
de l'architecture

Architecture de l'API de lecture d'e-mails : 3 approches comparées

Il n'y a pas une seule architecture "correcte" pour lire les e-mails. L'approche adéquate dépend du nombre de fournisseurs que vous devez prendre en charge, de vos ressources en ingénierie et de vos exigences d'échelle. Voici une comparaison honnête.

Approche Avantages Consulter Quand utiliser
API de fournisseur direct
API Gmail, Microsoft Graph		 Version gratuite, accès complet aux fonctionnalités, pas de latence intermédiaire Configuration OAuth par fournisseur, analyse MIME, gestion séparée des limites de débit, aucune normalisation inter-fournisseurs Prestataire unique uniquement
Messagerie IMAP auto-hébergée
imaplib, node-imap		 Protocole universel, fonctionne avec n'importe quelle boîte aux lettres, aucune application OAuth requise Connexions TCP avec état, pas de notifications push (polling ou IDLE), gestion de pool de connexions, lent à grande échelle Héritage / sur site uniquement
API unifiée pour la lecture d'e-mails
Unipile		 Un point d'accès unique pour tous les fournisseurs, réponse JSON normalisée, OAuth géré, webhooks unifiés, logique de nouvelle tentative intégrée Coût supplémentaire d'appel API par compte lié, dépendance externe Produits multi-fournisseurs
API de fournisseur direct
API Gmail, Microsoft Graph
Avantages Version gratuite, accès complet aux fonctionnalités, pas de latence intermédiaire
Consulter Configuration OAuth par fournisseur, analyse MIME, gestion séparée des limites de débit, aucune normalisation inter-fournisseurs
Quand utiliser Prestataire unique uniquement
Messagerie IMAP auto-hébergée
imaplib, node-imap
Avantages Protocole universel, fonctionne avec n'importe quelle boîte aux lettres, aucune application OAuth requise
Consulter Connexions TCP avec état, pas de notifications push (polling ou IDLE), gestion de pool de connexions, lent à grande échelle
Quand utiliser Héritage / sur site uniquement
API unifiée pour la lecture d'e-mails
Unipile
Avantages Un point d'accès unique pour tous les fournisseurs, réponse JSON normalisée, OAuth géré, webhooks unifiés, logique de nouvelle tentative intégrée
Consulter Coût supplémentaire d'appel API par compte lié, dépendance externe
Quand utiliser Produits multi-fournisseurs
Le meilleur pour un fournisseur unique
API du Fournisseur Direct

Si chaque utilisateur de votre produit utilise Gmail, développez directement avec l'API Gmail. Vous bénéficiez d'une parité fonctionnelle complète, sans frais supplémentaires et d'un accès aux fonctionnalités spécifiques à Gmail telles que les libellés, les fils de discussion et les notifications Push Pub/Sub.

Idéal pour les systèmes hérités
Messagerie IMAP auto-hébergée

Serveurs de messagerie sur site, déploiements d'Exchange d'entreprise sans accès à l'API Graph, ou tout scénario où OAuth n'est pas disponible. Utilisez IMAP comme solution de repli, et non comme stratégie principale pour les nouveaux produits.

Idéal pour les produits SaaS
API unifiée pour la lecture des e-mails

Lorsque vos utilisateurs ont des boîtes aux lettres Gmail, Outlook et IMAP et que vous avez besoin d'une API de lecture d'e-mails cohérente pour toutes, une couche unifiée comme Unipile élimine entièrement le problème d'intégration N-fournisseurs.

Configuration en 5 minutes

Lire les e-mails avec l'API Unifiée de lecture d'e-mails d'Unipile

Unipile abstrait l'API Gmail, Microsoft Graph et IMAP derrière une seule API de lecture d'e-mails. Un flux OAuth, un point d'accès, une forme JSON normalisée – quel que soit le fournisseur sur lequel se trouve la boîte aux lettres de votre utilisateur. Voici comment lire votre première boîte de réception en moins de 5 minutes.

1
Authentifier un utilisateur avec le lien d'authentification hébergé

Générez une URL d'authentification hébergée depuis votre tableau de bord Unipile. Envoyez ce lien à votre utilisateur — il/elle complète le flux de consentement OAuth pour son fournisseur (identifiants Gmail, Outlook ou IMAP) sur la page hébergée par Unipile. Aucune configuration d'application OAuth ni de configuration d'URI de redirection de votre côté. Voir le guide API de messagerie unifié pour le flux d'authentification complet.

auth_link.sh
# Générer un lien d'authentification hébergé pour votre utilisateur curl -X POST \ "https://api3.unipile.com:PORT/api/v1/hosted/accounts/link" \ -H "X-API-KEY : VOTRE_CLE_API" \ -H "Content-Type: application/json" \ -d '{"type":"EMAIL","name":"user@example.com","success_redirect_url":"https://yourapp.com/connected"}' Réponse # : { "url": "https://auth.unipile.com/..." } # Envoyez cette URL à votre utilisateur : il devra alors effectuer l'authentification OAuth auprès de son fournisseur
2
Lister les e-mails de la boîte de réception - GET /api/v1/emails

Une fois que l'utilisateur aura lié son compte, appelez le point de terminaison des e-mails avec leur account_id. La réponse est identique, que la boîte aux lettres sous-jacente soit Gmail, Outlook ou IMAP.

liste_emails.sh
# : Liste des e-mails de la boîte de réception (fonctionne avec Gmail, Outlook et IMAP) curl -X OBTENIR \ "https://api3.unipile.com:PORT/api/v1/emails?account_id=ACCOUNT_ID&limit=50" \ -H "X-API-KEY : VOTRE_CLE_API" # Trier par dossier curl "...?account_id=ACCOUNT_ID&dossier=INBOX&limite=50" -H "X-API-KEY : VOTRE_CLE_API" Filtre # : messages non lus uniquement curl "...?account_id=ACCOUNT_ID&unread=true" -H "X-API-KEY : VOTRE_CLE_API"
200 OK - JSON normalisé, même structure pour tous les fournisseurs
3
Recevoir un seul e-mail avec le corps et les pièces jointes

Récupérez un e-mail complet par ID. Unipile renvoie un objet décodé et normalisé avec le corps en texte brut, le corps HTML et les métadonnées des pièces jointes - aucun besoin d'analyse MIME de votre côté.

get_email.sh
# Récupérer un seul e-mail avec le corps complet et les pièces jointes curl -X OBTENIR \ "https://api3.unipile.com:PORT/api/v1/emails/EMAIL_ID" \ -H "X-API-KEY : VOTRE_CLE_API" Champs de réponse # (toujours normalisés) : # { "id", "objet", "date", "expéditeur", "destinataires", # " corps ", " corps_simple ", " pièces jointes " : [{ " id ", " nom_fichier ", " taille " }] }
4
Recevez de nouveaux e-mails en temps réel via des webhooks

Enregistrez un point de terminaison de webhook dans votre tableau de bord Unipile. Unipile abstrait les notifications de changement Gmail Pub/Sub, Microsoft Graph et IMAP IDLE en un seul email.reçu Événement. Pas de renouvellement d'abonnement, pas de pool de connexions IDLE à gérer.

webhook_handler.js
// Unipile appelle votre endpoint lorsqu'un nouvel e-mail arrive // Même événement pour les utilisateurs de Gmail, Outlook et IMAP application.poste('/webhooks/email', (req, res) => { const { événement, identifiant_compte, identifiant_email } = req.body; si (événement === 'email.reçu') { // Récupérer les détails complets de l'email traiterNouveauCourriel(identifiant_compte, identifiant_email); } res.étatEnvoyé(200); });
Un événement webhook remplace Gmail Pub/Sub + abonnements Graph + IMAP IDLE
Voulez-vous la référence d'intégration complète ?

Le guide complet de l'API d'e-mail couvre l'authentification, tous les points de terminaison, la pagination, le téléchargement de pièces jointes, la sécurité et la conformité en détail.

Lire le guide de l'API E-mail
Exemples de code

Lecture d'e-mails : exemples de code par langue

Extraits prêts pour la production pour lire les e-mails avec l'API unifiée de lecture d'e-mails d'Unipile. Tous les exemples lisent depuis des comptes Gmail, Outlook et IMAP avec le même code.

Node.js / TypeScript
Python
Allons
readEmails.ts
import fetch from 'node-fetch'; const BASE = 'https://api3.unipile.com:PORT/api/v1'; const CLÉ_API = process.env.CLÉ_API_UNIPILE!; interface Email { id: chaîne; sujet : chaîne; date : chaîne; de_participant : { nom_affiché : chaîne; identifier : chaîne }; body: chaîne; corps_plain chaîne; pièces jointes : { id : chaîne; nom du fichier : chaîne; taille : nombre }[]; } // Lister les e-mails de la boîte de réception - fonctionne pour Gmail, Outlook et IMAP async function listeEmails(accountId: chaîne, limite = 50) { const res = await fetch( `${BASE}/emails?account_id=${accountId}&limit;=${limit}&folder;=INBOX`, { en-têtes : { 'X-API-KEY': CLÉ_API } } ); const données = await res.json(); return articles de données En tant que Email[]; } // Récupérer un seul e-mail avec le corps complet + pièces jointes async function ObtenirEmail(identifiantEmail: chaîne) { const res = await fetch(`${BASE}/emails/${emailId}`, { en-têtes : { 'X-API-KEY': CLÉ_API } } ); return await res.json() en tant que Email; } // Utilisation const courriels = await listeEmails('acc_01abc...'); e-mails.chaque(e => console.log(e.sujet, e.de_participant.identifiant));
Guide complet de l'API d'e-mail pour JavaScript
lire_emails.py
import système d'exploitation import demandes BASE = "https://api3.unipile.com:PORT/api/v1" EN-TÊTES = {"X-API-KEY": os.environ"UNIPILE_API_KEY"]} déf lister_e-mails(account_id: str, limit: int = 50) -> list: "Lister les e-mails de la boîte de réception - fonctionne pour Gmail, Outlook et IMAP." flemme = requêtes.obtenir( f"{BASE}/e-mails", headers=HEADERS, params={ "account_id": identifiant_compte, "limite"limite, "dossier": "BOÎTE DE RÉCEPTION", }, ) resp.lancer_statut() return resp.json()["articles"] déf obtenir_email(identifiant_email: str) -> dict: "Récupérer un seul e-mail avec le corps et les pièces jointes." flemme = requêtes.obtenir(" {BASE}/emails/{email_id} ", en-têtes=EN-TETES) resp.lancer_statut() return resp.json() # Utilisation courriels = lister_e-mails("acc_01abc...") pour l'email en courriels : print(e-mail["sujet"], courriel["de_participant"]["identifier"]) # Récupérer le corps complet du premier e-mail complet = obtenir_email(mails[0]["id"]) print(complet["corps_en_clair"])
Guide complet de l'API E-mail pour Python
read_emails.go
paquet principal import ( "encodage/json" "fmt" "net/http" "os" ) type Email structure { ID chaîne `json:"id"` Objet chaîne `json:"sujet"` CorpsLisse chaîne `json:"corps_texte_brut"` } type ListeRéponse structure { Objets []Email `json:"items"` } fonction listeEmails(accountID string) ([]Email, erreur) { url := "https://api3.unipile.com:PORT/api/v1/emails?account_id=" + identifiant du compte dem, _ := http:.Nouvelle demande("OBTENIR", url, nul) req.Header.Ensemble("X-API-KEY", os.Getenv("UNIPILE_API_KEY")) resp, err := http.DefaultClient.Réalisez(demande) si err != nul { return nul, err } reporter resp.Corps.Fermer() variable résultat ListeRéponse json.NewDecoder(corps de la réponse).Décoder(&résultat) return result.Éléments, nul } fonction principal() { courriels, _ := listeEmails("acc_01abc...") pour _, et := plage courriels { fmt.Println(e.Objet) } }
Temps réel

Lecture d'e-mails en temps réel : Webhooks vs Polling

Savoir quand un nouvel e-mail arrive est aussi important que de pouvoir le lire. Trois mécanismes sont disponibles, chacun avec des caractéristiques opérationnelles très différentes à grande échelle.

Éviter à grande échelle

Sondage

Votre application appelle le point de terminaison lister les e-mails via une minuterie (toutes les 30 secondes, toutes les 5 minutes). Simple à mettre en œuvre mais épuise le quota, introduit de la latence et ne permet pas de gérer plus que quelques comptes.

Simple - aucune configuration côté serveur
Consommation de l'API proportionnelle au nombre de comptes x fréquence
Sondage de 5 minutes = délai de notification de 5 minutes
Ne peut pas évoluer au-delà d'environ 100 comptes actifs
Spécifique au fournisseur

Webhooks du fournisseur natif

Les notifications Pub/Sub de Gmail et de Microsoft Graph envoient les événements à votre serveur immédiatement. Rapide et efficace en termes de quotas, mais chacune nécessite une configuration distincte, une logique de renouvellement distincte et des schémas d'événements différents.

Livraison quasi-instantanée (secondes)
Efficace en termes de quota - déclenché uniquement sur les nouveaux e-mails
Gmail : l'abonnement Pub/Sub expire tous les 7 jours
Graphique : abonnement max ~3 jours, doit être renouvelé
IMAP IDLE : 1 connexion TCP par compte
Recommandé

Webhooks Unifiés Unipile

Unipile abstrait tous les mécanismes de push des fournisseurs derrière un seul email.reçu événement. Un point de terminaison reçoit des notifications pour les comptes Gmail, Outlook et IMAP indifféremment - avec le renouvellement automatique des abonnements géré en interne.

Une URL de webhook pour tous les fournisseurs
Renouvellement automatique des publications/abonnements et des graphes
IMAP IDLE géré en interne par compte
Charge utile normalisée - mêmes champs à chaque fois
Comment Unipile abstrait la distribution d'e-mails en temps réel

Sous le capot, Unipile gère les abonnements Pub/Sub de Gmail, les abonnements de notification de modification de Microsoft Graph et les connexions IMAP IDLE, par compte lié, renouvelés automatiquement. Votre application enregistre une URL de webhook et reçoit un événement normalisé, quel que soit le fournisseur sous-jacent.

Gmail Pub/Sub
+
Souscriptions graphiques
+
IMAP IDLE
->
événement.email.reçu
Sécurité et conformité

Sécurité et conformité lors de la lecture des e-mails des utilisateurs

L'accès aux e-mails des utilisateurs implique d'importantes responsabilités en matière de sécurité et de légalité. Voici les quatre domaines que vous devez aborder avant de mettre en production une intégration d'API de lecture d'e-mails.

Minimisation de la portée OAuth

Toujours demander l'étendue OAuth minimale requise. Pour lire les e-mails, utiliser portées en lecture seule - ne demandez jamais les autorisations d'envoi ou de composition si votre application n'a besoin que d'un accès à la boîte de réception. La portée de lecture seule de Gmail est gmail.lecture seule. Équivalent Microsoft Graph Mail.Read. Les demandes d'autorisations trop larges déclenchent des processus de révision plus stricts de la part de Google et Microsoft, et réduisent la confiance des utilisateurs sur l'écran de consentement.

Meilleures pratiques de stockage de jetons

Les jetons d'accès OAuth et les jetons de rafraîchissement sont des identifiants. Stockez-les chiffré au repos Utiliser AES-256 ou un équivalent, jamais en clair dans votre base de données. Rotation des clés de chiffrement selon un calendrier. Ne jamais enregistrer de jetons dans les journaux d'application. Implémenter la révocation des jetons lorsqu'un utilisateur déconnecte son compte - appeler le point de terminaison de révocation du fournisseur, ne pas simplement supprimer l'enregistrement de la base de données.

RGPD et résidence des données

Les corps d'e-mails contiennent souvent des données personnelles relevant du RGPD. Vous devez documenter dans votre politique de confidentialité exactement quelles données d'e-mails vous collectez, conservez, traitez et pendant combien de temps. Mettez en œuvre un flux de suppression de données qui supprime le contenu des e-mails lorsqu'un utilisateur demande une erasure. Si vous stockez le contenu des e-mails dans votre propre infrastructure, tenez compte des exigences de résidence des données pour les clients de l'UE.

Vérification de Google CASA et Microsoft Publisher

Demandes d'applications pour des scopes Gmail sensibles (y compris gmail.lecture seule) doivent remplir le formulaire de Google CASA Niveau 2 évaluation de sécurité avant d'être autorisé au-delà du plafond de test de 100 utilisateurs. Microsoft exige la vérification de l'éditeur pour les applications demandant certaines étendues Graph. Les deux processus prennent des semaines - planifiez en conséquence avant votre date de lancement. L'utilisation d'Unipile hérite de ces certifications de la couche plateforme.

Certifications de conformité Unipile

Unipile gère la certification Gmail CASA Tier 2, la vérification Microsoft Publisher, l'audit SOC 2 Type II et les accords de traitement des données RGPD au niveau de la plateforme. Les produits construits sur Unipile héritent de ces certifications plutôt que de les compléter indépendamment.

SOC 2 Type II
Google CASA Niveau 2
Conforme au RGPD
OAuth 2.0 Portées en lecture seule
Tarifs

Lire les prix de l'API d'e-mail : Seuils gratuits et modèles de coûts

Les niveaux gratuits des API de fournisseurs natifs sont généreux à petite échelle, mais les coûts cachés apparaissent lorsque vous devez prendre en charge plusieurs fournisseurs, gérer le renouvellement des jetons en volume ou atteindre les limites de taux. Voici une analyse honnête.

Fournisseur Niveau gratuit Modèle de coûts Limite de débit Coûts cachés
API Gmail Gratuit avec quotas Unités de quota par requête. Pas de facturation par compte 250 unités/sec/utilisateur, 1 milliard d'unités/jour Revue CASA de niveau 2, analyse MIME, logique de renouvellement Pub/Sub
Microsoft Graph Gratuit avec limitation Inclus avec le locataire Microsoft 365. Pas de frais par appel 10 000 requêtes / 10 min / application / locataire Processus de vérification de l'éditeur, renouvellement d'abonnement, applications OAuth par locataire
IMAP (auto-hébergé) Protocole libre Pas de coût d'API. Coût d'infrastructure pour les pools de connexion Spécifique au fournisseur, ~10-20 connexions/compte Infrastructure de serveur, gestion des connexions IDLE, pas de support push
Unipile essai gratuit de 7 jours Par compte lié par mois. Voir niveau API e-mail gratuit Géré en interne, logique de nouvelle tentative intégrée Coût des appels API par compte - compensé par l'élimination de l'ingénierie OAuth/MIME
API Gmail
Gratuit avec quotas
Modèle de coûts Unités de quota par requête. Pas de facturation par compte
Limite de débit 250 unités/sec/utilisateur, 1 milliard d'unités/jour
Coûts cachés Revue CASA de niveau 2, analyse MIME, logique de renouvellement Pub/Sub
Microsoft Graph
Gratuit avec limitation
Modèle de coûts Inclus avec le locataire Microsoft 365. Pas de frais par appel
Limite de débit 10 000 requêtes / 10 min / application / locataire
Coûts cachés Processus de vérification de l'éditeur, renouvellement d'abonnement, applications OAuth par locataire
IMAP (auto-hébergé)
Protocole libre
Modèle de coûts Pas de coût d'API. Coût d'infrastructure pour les pools de connexion
Limite de débit Spécifique au fournisseur, ~10-20 connexions/compte
Coûts cachés Infrastructure de serveur, gestion des connexions IDLE, pas de support push
Unipile
essai gratuit de 7 jours
Modèle de coûts Par compte lié par mois. Voir niveau API e-mail gratuit
Limite de débit Géré en interne, logique de nouvelle tentative intégrée
Coûts cachés Coût des appels API par compte - compensé par l'élimination de l'ingénierie OAuth/MIME

Commencer avec une API d'e-mail de lecture gratuite ? L'API Gmail et Microsoft Graph offrent tous deux un accès gratuit dans les limites de quota. Unipile propose un essai de 7 jours sans carte de crédit requise, couvrant les comptes Gmail, Outlook et IMAP.

Commencez l'essai gratuit
Pièges courants

Pièges courants lors de la création d'une intégration de lecture d'e-mails

Voici les erreurs qui provoquent systématiquement des incidents de production pour les équipes qui lancent leur première intégration d'API d'e-mail de lecture. Apprenez-les avant de les rencontrer.

01
Épuisement des quotas sur Gmail à grande échelle

La limite de 250 unités de quota par seconde par utilisateur de Gmail semble généreuse jusqu'à ce que vous ayez 500 comptes et que vous ayez besoin d'une synchronisation initiale de la boîte de réception. Lister 500 messages coûte 2 500 unités ; récupérer chaque message complet coûte encore 2 500 unités. Les synchronisations initiales pour les grandes boîtes aux lettres peuvent épuiser les quotas quotidiens en quelques heures.

Réparer : Implémentez une rétroaction exponentielle sur les réponses 429, donnez la priorité aux messages récents pour la synchronisation initiale et utilisez des requêtes par lots lorsque disponibles pour réduire la surcharge par appel.
02
Échecs silencieux de rafraîchissement de jeton

Les jetons d'actualisation OAuth expirent silencieusement : Google les révoque après 6 mois d'inactivité, après un changement de mot de passe, ou lorsqu'un utilisateur révoque l'accès depuis les paramètres de son compte Google. Si votre logique d'actualisation de jeton ne détecte pas une erreur 401 et ne l'affiche pas à l'utilisateur, votre application cessera simplement de lire les e-mails sans aucune erreur visible.

Réparer : Traitez les réponses 401 comme des événements de déconnexion de compte. Notifiez l'utilisateur et demandez la ré-authentification. Stockez un dernière synchronisation à horodatage et alerte lorsqu'il dépasse votre intervalle de synchronisation attendu.
03
E-mails manquants en raison de filtres de dossier incorrects

Les libellés Gmail et les dossiers IMAP ne sont pas des concepts équivalents. Les libellés de Gmail BOITE DE RECEPTION Le filtre n'inclut pas les messages qui ont été archivés (retirés de la boîte de réception mais non supprimés). Dans Microsoft Graph, le dossier « Boîte de réception » exclut la « Boîte de réception prioritaire » par rapport aux autres divisions de volet, à moins que vous n'interrogiez les deux. Les équipes constatent souvent qu'il leur manque entre 20 et 40% de messages en raison d'hypothèses erronées concernant les dossiers.

Réparer : Testez vos requêtes de dossiers avec de vrais comptes, y compris des messages archivés, filtrés et catégorisés. Pour une synchronisation complète, envisagez les requêtes TOUT messages (pas seulement la boîte de réception) et filtrage par date de votre côté.
04
Bugs d'encodage sur les e-mails internationaux

Les corps d'e-mails arrivent dans une large gamme de codages de caractères : UTF-8, ISO-8859-1, Windows-1252, Shift-JIS. Gmail renvoie des parties encodées en base64url. IMAP renvoie des parties encodées en quoted-printable. Le décodage d'un encodage en un autre produit un corps de texte corrompu qui est invisible dans votre environnement de test local (qui n'envoie probablement que des e-mails ASCII).

Réparer : Toujours décoder les parties MIME selon leur Encodage-Transfert-Contenu et réencoder en UTF-8. Testez spécifiquement avec du contenu d'e-mail japonais, arabe et riche en émojis.
05
Incohérences de threading entre les fournisseurs

Construire une vue de fil de discussion unifiée pour les comptes Gmail, Outlook et IMAP nécessite de normaliser trois modèles de discussion complètement différents. Gmail possède des identifiants de fil natifs. Outlook a des identifiants de conversation qui se comportent différemment. IMAP n'a aucun fil natif – vous reconstruisez les fils à partir de Message-ID, Références, ou encore En réponse à en-têtes, qui ne sont pas toujours présents ou corrects.

Réparer : Une API unifiée de lecture d'e-mails comme Unipile normalise le traitement des fils de discussion dans un modèle cohérent pour tous les fournisseurs, éliminant ainsi le besoin de mettre en œuvre une logique de reconstruction de fils de discussion spécifique à chaque fournisseur.
FAQ

Lire l'API des e-mails - Foire aux questions

Les questions les plus courantes des développeurs qui créent leur première intégration d'API de lecture d'e-mails.

01
Qu'est-ce qu'une API de lecture d'e-mails ?
Une lire l'API des e-mails est une interface HTTP qui permet à votre application de s'authentifier auprès de la boîte aux lettres d'un utilisateur (via OAuth 2.0 ou des identifiants IMAP) et de récupérer des messages électroniques par programme. Elle est distincte des API d'e-mails transactionnels comme SendGrid ou Mailgun, qui envoient des e-mails sortants à partir d'un domaine que vous contrôlez. Les API de lecture d'e-mails fonctionnent sur le compte Gmail, Outlook ou IMAP de l'utilisateur. Voir le Comparaison complète des fournisseurs d'API d'e-mail pour le contexte sur l'écosystème plus large.
02
Puis-je lire les e-mails de quelqu'un avec une API ?
Vous ne pouvez lire que les e-mails provenant de comptes dont le propriétaire de la boîte aux lettres a explicitement accordé à votre application l'accès via le consentement OAuth 2.0. L'utilisateur doit autoriser votre application sur l'écran de consentement de Google ou de Microsoft. Vous ne pouvez pas accéder aux e-mails sans le consentement du propriétaire du compte - tenter de le faire viole les conditions d'utilisation du fournisseur et la loi en vigueur dans la plupart des juridictions.
03
Comment lire des emails en utilisant l'API Gmail ?
Pour lire les e-mails avec l'API Gmail : créez un projet Google Cloud, activez l'API Gmail, configurez un client OAuth 2.0, demandez le gmail.lecture seule portée, obtenir un jeton d'accès via le consentement OAuth, puis appeler GET /gmail/v1/users/me/messages pour lister les messages et GET /utilisateurs/moi/messages/{id}?format=full pour récupérer des e-mails individuels. Les messages sont retournés sous forme de parties MIME encodées en base64url que vous devez décoder.
04
Quelle est la différence entre IMAP et l'API Gmail ?
L'API Gmail est une API REST moderne avec OAuth 2.0, des notifications push via Google Pub/Sub et des réponses JSON. IMAP est un protocole TCP universel pris en charge par tous les fournisseurs de messagerie, utilisant des connexions stateful et des commandes textuelles. L'API Gmail est plus performante pour les cas d'utilisation spécifiques à Gmail (push en temps réel, accès aux fils de discussion, gestion des libellés). IMAP offre une couverture universelle sur tous les fournisseurs mais nécessite des connexions par interrogation (polling) ou IDLE et n'a pas d'interface REST native. Lisez notre Guide d'intégration de l'API IMAP pour une comparaison plus approfondie.
05
Existe-t-il une API gratuite pour lire les e-mails ?
Oui. L'API Gmail est gratuite dans les limites de quota de Google (250 unités/sec/utilisateur, 1 milliard d'unités/jour). Microsoft Graph pour Outlook est gratuit avec des limites de limitation. IMAP est un protocole ouvert gratuit. Pour le support multi-fournisseurs, Unipile propose un essai gratuit de 7 jours couvrant les comptes Gmail, Outlook et IMAP connectés. Voir notre guide de l'API d'e-mail gratuite pour une comparaison complète des niveaux gratuits et de leurs limites réelles.
06
Comment lire les e-mails de plusieurs fournisseurs avec une seule API ?
Utilisez une API unifiée pour lire les e-mails comme Unipile. Unipile expose un seul point d'accès (GET /api/v1/emails) qui renvoie du JSON normalisé pour les comptes Gmail, Outlook et IMAP. Vous authentifiez les utilisateurs une seule fois via un lien OAuth hébergé, et Unipile gère les flux OAuth spécifiques au fournisseur, l'analyse MIME et l'abstraction des webhooks en temps réel derrière une interface unique et cohérente. Voir notre Guide de l'API Email pour la référence complète.
07
Puis-je lire les pièces jointes d'e-mails via une API ?
Oui. L'API Gmail renvoie les métadonnées des pièces jointes dans la charge utile du message et fournit un point de terminaison distinct pour télécharger les données des pièces jointes par ID. Microsoft Graph renvoie les pièces jointes via /messages/{id}/pièces jointes. IMAP nécessite l'analyse de l'arborescence MIME pour identifier les pièces jointes. Avec Unipile, les métadonnées des pièces jointes (nom de fichier, taille, type MIME) sont incluses dans la réponse de l'e-mail et le contenu des pièces jointes est disponible via un point de terminaison dédié – aucune analyse MIME n'est requise.
08
Comment être averti de l'arrivée d'un nouvel e-mail ?
Chaque fournisseur utilise un mécanisme différent : Gmail utilise les abonnements push de Google Pub/Sub (expirent tous les 7 jours, nécessitent un renouvellement). Microsoft Graph utilise les abonnements de notification de modification (expirent après environ 3 jours). IMAP utilise la commande IDLE sur une connexion TCP persistante. Alternativement, Unipile abstrait ces trois éléments en un seul email.reçu événement webhook qui se déclenche pour les comptes Gmail, Outlook et IMAP avec gestion automatique des abonnements gérée en interne.
09
Quelles sont les limites de débit pour la lecture d'e-mails sur Gmail et Outlook ?
API Gmail : 250 unités de quota par utilisateur par seconde. La liste des messages coûte 5 unités, la récupération d'un message complet coûte 5 unités. Le plafond quotidien est de 1 milliard d'unités de quota. Microsoft Graph : 10 000 requêtes par 10 minutes par application et par locataire. Les deux renvoient un HTTP 429 en cas de limitation, avec un Réessayer après En-tête. Implémenter une extinction exponentielle avec gigue pour la fiabilité de la production. Les limites IMAP sont spécifiques au fournisseur, généralement 10 à 20 connexions simultanées par compte.
10
La lecture des e-mails des utilisateurs via une API est-elle conforme au RGPD ?
La lecture des e-mails des utilisateurs via une API peut être conforme au RGPD lorsqu'elle est correctement mise en œuvre. Les exigences comprennent : le consentement explicite de l'utilisateur via OAuth (l'écran de consentement remplit le critère de base légale), une politique de confidentialité documentant quelles données d'e-mail vous collectez et conservez, un mécanisme de suppression des données pour les demandes d'effacement, et un accord de traitement des données avec tout fournisseur tiers de couche API que vous utilisez. Unipile est certifié SOC 2 Type II et conforme au RGPD, simplifiant la documentation de conformité pour les produits construits sur la plateforme.

Vous avez encore des questions ? Parlez à un développeur qui a intégré avec succès des API de lecture d'e-mails pour Gmail, Outlook et IMAP, à grande échelle.

Parler à un expert
fr_FRFR
en_USEN es_ESES de_DEDE it_ITIT pt_BRBR nl_NLNL pl_PLPL tr_TRTR fr_FRFR