Gmail (OAuth)

L’intégration Gmail envoie vos modèles Frontmail depuis votre propre boîte Gmail ou Google Workspace via l’API Gmail. Les messages envoyés apparaissent dans votre dossier Messages envoyés, les réponses arrivent dans votre boîte de réception, et les destinataires voient un e-mail normal venant de vous.

Choisissez Gmail si vous gérez un site personnel, un portfolio ou une petite entreprise et que vous voulez que les envois de formulaires et les notifications partent de l’adresse que vous utilisez déjà – sans aucune configuration DNS si vous utilisez @gmail.com. Ce n’est pas fait pour le volume : Google plafonne l’envoi quotidien (voir Limites) et il n’y a pas de webhooks de livraison. Pour un volume transactionnel, utilisez Mailgun, Postmark, Amazon SES ou Resend. Voir la présentation des services d’envoi.

OAuth plutôt que mots de passe d’application

Vous pouvez aussi connecter Gmail via SMTP avec un mot de passe d’application, mais OAuth est plus sûr : Frontmail ne voit jamais votre mot de passe, l’autorisation est limitée à l’envoi et vous pouvez la révoquer à tout moment dans votre compte Google.

Prérequis

• Un compte Gmail (@gmail.com) ou un utilisateur Google Workspace avec Gmail activé.
• Pour Workspace : votre administrateur doit autoriser les applications tierces à accéder aux données Google, ou approuver explicitement Frontmail dans Console d’administration → Sécurité → Accès et contrôle des données → Commandes des API → Contrôle des accès des applications.
• Rien d’autre – ni clé API, ni projet Google Cloud.

Connexion dans Frontmail

1. Ouvrez Services d’envoi → Ajouter un service → Gmail.
2. Cliquez sur Connecter Gmail. Vous êtes redirigé vers Google.
3. Choisissez le compte et examinez l’écran de consentement. Frontmail demande :
   • https://www.googleapis.com/auth/gmail.send – envoyer des e-mails en votre nom. Ce scope est limité à l’envoi : Frontmail ne peut ni lire, ni rechercher, ni supprimer, ni modifier le moindre e-mail de votre boîte.
   • openid email – votre adresse e-mail, pour que le tableau de bord puisse afficher le compte connecté et l’utiliser comme adresse d’expéditeur par défaut.
4. Cliquez sur Autoriser. Google vous redirige vers Frontmail et le service est enregistré avec l’adresse connectée affichée.
5. Réglez éventuellement E-mails par seconde (max.) (2/s par défaut) et cliquez sur Tester la connexion, qui actualise le jeton d’accès et vérifie que l’autorisation gmail.send a bien été accordée.

Ce qui est stocké : Frontmail stocke le jeton d’actualisation OAuth (et un jeton d’accès de courte durée), chiffrés avec le chiffrement d’enveloppe d’AWS KMS. Le jeton d’accès expire au bout d’une heure environ ; Frontmail l’actualise automatiquement avant l’envoi. Le flux utilise PKCE et demande toujours l’accès hors ligne, si bien qu’une reconnexion émet un nouveau jeton d’actualisation.

Validation de l’application

L’application OAuth de production de Frontmail est validée par Google pour le scope gmail.send : vous voyez le nom de Frontmail et aucun avertissement « application non validée ».

Quand le jeton cesse de fonctionner

Google invalide un jeton d’actualisation lorsque vous :

• révoquez l’accès dans Compte Google → Sécurité → Applications et services tiers → Frontmail,
• changez le mot de passe du compte Google (pour les scopes Gmail, Google révoque les jetons existants),
• n’utilisez pas le jeton pendant 6 mois,
• ou lorsqu’un administrateur Workspace retire l’accès de l’application.

L’envoi ou la vérification d’état suivants échouent alors avec invalid_grant. Frontmail le traite comme une erreur auth : le service est marqué unhealthy, vous recevez un e-mail et une bannière dans le tableau de bord, et les messages sont retenus (ou envoyés via le service de secours) jusqu’à ce que vous cliquiez sur Reconnecter sur la page du service. La reconnexion crée un nouveau jeton d’actualisation et libère automatiquement les messages retenus.

Applications OAuth auto-hébergées / « En test »

Si vous faites tourner Frontmail avec votre propre client OAuth Google Cloud dont l’état de publication est En test (Testing), Google fait expirer les jetons d’actualisation au bout de 7 jours – le service passera en unhealthy chaque semaine. Publiez l’application (et terminez la validation pour le scope sensible gmail.send) pour obtenir des jetons durables. Cela ne concerne pas l’application hébergée frontmail.dev.

DNS : SPF, DKIM et DMARC

• Adresses @gmail.com : rien à faire – Google signe et authentifie les e-mails.
• Google Workspace sur votre propre domaine : publiez les enregistrements de Google si ce n’est pas déjà fait :

; SPF
example.com.                    TXT  "v=spf1 include:_spf.google.com ~all"

; DKIM – à générer dans Console d’administration → Applications → Google Workspace → Gmail → Authentifier les e-mails
google._domainkey.example.com.  TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A…"

; DMARC
_dmarc.example.com.             TXT  "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

Après avoir publié l’enregistrement DKIM, cliquez sur Démarrer l’authentification dans la console d’administration. Durcissez DMARC en p=quarantine / p=reject une fois que les rapports sont propres.

Note

Les exigences de Google de 2024 pour les expéditeurs en masse s’appliquent aux e-mails envoyés vers des utilisateurs Gmail depuis n’importe où – y compris Workspace. Un formulaire de contact n’atteindra pas le seuil de 5 000 par jour, mais SPF + DKIM + DMARC restent recommandés sur votre domaine Workspace.

Adresse d’expéditeur : Gmail envoie au nom du compte connecté. Vous ne pouvez utiliser une autre adresse que si elle est configurée comme alias Envoyer des e-mails en tant que dans les paramètres Gmail ; sinon Gmail remplace l’expéditeur par l’adresse du compte.

Régions

Il n’y a pas de régions – l’API Gmail est mondiale.

Limites d’envoi

Google impose des limites quotidiennes par utilisateur. Les dépasser bloque l’envoi pendant jusqu’à 24 heures.

Compte	Limite approximative
Gmail personnel (@gmail.com)	~500 destinataires par jour
Google Workspace	~2 000 messages par jour (moins pendant l’essai)
API Gmail	250 unités de quota par utilisateur et par seconde ; un envoi = 100 unités

Frontmail envoie donc au maximum 2 messages par seconde via Gmail. Quand Google répond dailyLimitExceeded, Frontmail attend une heure entre les tentatives ; si la limite persiste, le message se termine en failed et le crédit est remboursé.

Suivi de livraison (webhooks)

Gmail n’a aucun webhook de livraison : il n’y a donc rien à configurer et pas d’URL de webhook sur la page du service. Frontmail sait seulement si Google a accepté le message (sent) ou l’a refusé (failed). Les rebonds arrivent sous forme d’e-mails « Delivery Status Notification » normaux dans votre boîte Gmail et ne sont pas ajoutés automatiquement à la liste de suppression de Frontmail. Les ouvertures et les clics ne sont pas suivis.

Erreurs courantes

• auth – le service est cassé (jeton révoqué ou expiré, invalid_grant, 401/403, Gmail non activé pour l’utilisateur Workspace). Le service est marqué unhealthy ; le propriétaire reçoit un e-mail et une bannière dans le tableau de bord. Un service de secours défini sur le modèle prend le relais ; sinon le crédit est remboursé et le message attend dans la file d’attente des e-mails retenus en held_service_error, puis part automatiquement après la reconnexion (revérifié à l’enregistrement et lors de la vérification d’état quotidienne).
• permanent – ce message ne peut pas être envoyé (destinataire invalide, message trop volumineux, erreur de validation 400). Service de secours s’il est configuré, sinon failed et remboursé.
• transient – 5xx, limites de débit ou quotidiennes, délais dépassés. Relancé avec un délai exponentiel ; après la dernière tentative, failed et remboursé.

Réponse de Google	Catégorie	Que faire
invalid_grant – Token has been expired or revoked	auth	Cliquez sur Reconnecter sur la page du service et accordez de nouveau l’accès.
401 – Invalid Credentials	auth	Généralement corrigé par l’actualisation automatique du jeton ; si le problème persiste, reconnectez-vous.
403 – Insufficient Permission / insufficient_scope	auth	La case gmail.send a été décochée sur l’écran de consentement – reconnectez-vous et autorisez l’envoi.
403 – accès bloqué par l’administrateur Workspace	auth	Demandez à votre administrateur d’approuver Frontmail dans les Commandes des API.
400 failedPrecondition – Mail service not enabled	auth	L’utilisateur Workspace n’a pas de licence Gmail ; activez Gmail ou connectez un autre compte.
400 invalidArgument – Invalid To header	permanent	Voir destinataire invalide.
413 / 400 – message trop volumineux	permanent	Réduisez la taille des pièces jointes (la limite de Gmail est de 25 Mo).
429 / 403 rateLimitExceeded, userRateLimitExceeded, dailyLimitExceeded	transient	Ralentissez ou attendez la réinitialisation de la limite quotidienne ; envisagez un fournisseur transactionnel.
500 / 503 backendError	transient	Panne chez Google – Frontmail relance.

Liste de contrôle

• Connecté avec Connecter Gmail ; consentement accordé pour l’envoi d’e-mails
• Workspace : Frontmail autorisé dans les commandes des API (en cas de restriction)
• Workspace sur votre propre domaine : SPF include:_spf.google.com, DKIM google._domainkey, DMARC
• Expéditeur du modèle = l’adresse connectée ou un alias Envoyer des e-mails en tant que configuré
• Tester la connexion réussit
• Volume quotidien bien en dessous des limites de Google
• Service de secours configuré sur les modèles importants au cas où le jeton serait révoqué