API d'e-mail : guide complet pour les développeurs (2026)

Intégration API de messagerie : d'OAuth à la synchronisation en temps réel

Une intégration d'API d'e-mail réelle suit quatre phases, quel que soit le fournisseur que vous ciblez. Lisez cette section comme une liste de contrôle avant de commencer votre mise en œuvre : ignorer une étape ici est la raison la plus courante pour laquelle les intégrations fonctionnent en développement et échouent en production.

Authentification OAuth 2.0

Gmail et Microsoft Graph utilisent le standard Flux de code d'autorisation OAuth 2.0. Les mécanismes sont identiques : rediriger l'utilisateur vers le fournisseur, recevoir un code unique sur votre URL de rappel, l'échanger contre un jeton d'actualisation à longue durée de vie côté serveur, puis utiliser ce jeton d'actualisation pour générer des jetons d'accès à courte durée de vie pour chaque appel API ultérieur.

• Redirigez l'utilisateur vers le point de terminaison d'autorisation du fournisseur avec votre client_id, uri_de_redirection, et le demandé portée.
• L'utilisateur accorde les autorisations, le fournisseur redirige vers votre URL de rappel avec un code unique code paramètre.
• Votre serveur échange ça code pour un access_token (durée de vie d’une heure) et un token_rafraîchissement via un canal secondaire POST.
• Stocker les token_rafraîchissement serveur sécurisé, chiffré au repos. C'est l'identique à longue durée de vie que vous utilisez pour générer automatiquement de nouveaux jetons d'accès.

Envoyer et recevoir des e-mails

Une fois authentifiées, les deux opérations suivantes couvrent 80% de l'utilisation typique de l'API d'e-mail : récupération de la boîte de réception et envoyer un message. Avec l'API unifiée d'Unipile, les deux fonctionnent de manière identique sur Gmail, Outlook et IMAP via un ensemble unique de points de terminaison.

# Récupérer les 50 derniers e-mails d'une boîte de réception connectée
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: VOTRE_CLE_API'

# Envoyer un e-mail en texte brut
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: VOTRE_CLE_API' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "VOTRE_ID_COMPTE",
    "subject": "Bonjour depuis Unipile",
    "body": "Bonjour, ceci est un e-mail en texte brut",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

Unipile prend également en charge les fonctionnalités d'envoi avancées typiques attendues par les développeurs : pièces jointes (multipart form-data avec plusieurs fichiers), en-têtes personnalisés (passage de tableaux de X- en-têtes préfixés), répondre dans le fil (en utilisant le message original) provider_id), surnom, alias d'expéditeur autorisés, et suivi des ouvertures / des liens avec des événements webhook en temps réel. Chacun d'eux correspond à un seul champ dans le corps de la requête, sans négociation de protocole requise.

# Envoyer avec pièces jointes + en-têtes personnalisés + suivi
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: VOTRE_CLÉ_API' \
  --form 'account_id=VOTRE_ID_COMPTE' \
  --form 'subject=Ébauche de contrat' \
  --form 'body=Veuillez trouver la v3 ci-jointe.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/chemin/vers/contract.pdf' \
  --form 'attachments=@/chemin/vers/appendix.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Pour une référence complète de développeur couvrant toutes les options d'envoi et le comportement spécifique au fournisseur, consultez notre guide API d'envoi d'e-mails.

Synchronisation des emails en temps réel

La synchronisation de la boîte de réception est la partie la plus complexe de toute intégration d'e-mails, et la plus souvent mal comprise. Une solution robuste synchronisation des e-mails la mise en œuvre comporte trois phases distinctes : synchronisation initiale, synchronisation incrémentale et notifications webhook en temps réel. Le fait d'en négliger un produit une intégration qui fonctionne dès le premier jour et qui échoue à grande échelle.

Planifiez les renouvellements dès le premier jour : les abonnements de réception Gmail Pub/Sub expirent après 7 jours et doivent être renouvelés. Les abonnements Microsoft Graph sur les ressources de messagerie expirent après un maximum d'environ 3 jours. Intégrez le renouvellement des abonnements à votre infrastructure de tâches en arrière-plan. avant aller en production, sinon votre intégration cessera silencieusement de recevoir des événements.

Webhooks et événements

Les webhooks sont la façon dont une API de messagerie moderne informe votre backend que quelque chose s'est produit, en temps réel, sans que vous ayez à demander. Au lieu de sonder /messages toutes les 30 secondes (coûteux et lent), vous vous abonnez une fois, et le fournisseur envoie une charge utile JSON à votre point de terminaison à chaque fois qu'un nouvel e-mail arrive, est lu, auquel on répond, ou est supprimé.

Les événements auxquels vous vous abonnez généralement sont mail_received (un nouveau message est arrivé dans la boîte de réception), mail_sent (un message sortant a été livré avec succès), mail_ouvert (le destinataire l'a ouvert, si le suivi est activé), lien_mail_cliqué (le destinataire a cliqué sur un lien suivi), et statut_du_compte (la boîte aux lettres connectée a besoin d'une réauthentification, par exemple après un changement de mot de passe). Chaque événement contient suffisamment de contexte pour que vos systèmes en aval réagissent sans effectuer d'appels d'API supplémentaires.