gids · gmail api

Hoe implementeert een productteam de Gmail API op een veilige manier?

Implementeer de Gmail API als gedelegeerde toegang tot een specifieke Gmail-mailbox, niet als algemene credential voor e-mailbezorging. Kies de kleinste OAuth-scope die de functie ondersteunt, bescherm de autorisatiestatus en refresh tokens, en koppel elke mailbox aan één tenant. Stel berichten op met een volwassen bibliotheek voor internetberichten, leg de teruggegeven Gmail-bericht-ID vast en synchroniseer wijzigingen via Pub/Sub plus history-records. Behandel impersonatie via een serviceaccount als een beslissing van de Workspace-beheerder. Houd ten slotte acceptatie door de API, bezorging bij de ontvangende server en inboxplaatsing als afzonderlijke uitkomsten.

Kies het mailboxmodel voordat je code schrijft

De Gmail API werkt op de Gmail-mailbox van een gebruiker. Hij is geschikt wanneer een product die mailbox moet lezen, de labels en threads ervan moet ordenen, concepten moet maken, als de geautoriseerde gebruiker moet verzenden of wijzigingen in de mailbox moet synchroniseren. Die bevoegdheid is wezenlijk breder dan het aanroepen van een e-mail-API voor applicaties vanaf een geverifieerd productdomein. Begin met het benoemen van de exacte taak in de mailbox en van wie de toegang verleent. Een product voor eindgebruikers gebruikt normaal gesproken OAuth-toestemming voor elk gekoppeld Google-account. Een interne automatisering in Google Workspace kan in plaats daarvan domeinbrede delegatie gebruiken die door een beheerder is goedgekeurd. Als de enige eis het verzenden van ontvangstbewijzen, verificatielinks, meldingen of andere door het product getriggerde berichten is vanaf een domein dat het bedrijf beheert, vermijd dan mailboxtoegang volledig en beoordeel een transactionele e-mail-API. Deze architectuurbeslissing beperkt onnodige toegang voordat een beveiligingsmaatregel of toestemmingsscherm dat hoeft te compenseren.

Autoriseer de smalst mogelijke praktische scope

Configureer een OAuth-client voor het juiste applicatietype, gebruik een exact geregistreerde redirect-URI en koppel de autorisatierespons aan de browsersessie die de flow startte met een onvoorspelbare state-waarde. Vraag toegang aan in context, wanneer de gebruiker de functie inschakelt die de toegang nodig heeft. Voor een integratie die alleen verzendt is `https://www.googleapis.com/auth/gmail.send` smaller dan scopes die de mailbox lezen of wijzigen. Google classificeert `gmail.send` als gevoelig, terwijl scopes zoals `gmail.readonly`, `gmail.compose` en `gmail.modify` beperkt zijn. Een openbare app met gevoelige of beperkte toegang kan OAuth-verificatie vereisen, en server-side opslag of verzending van gegevens uit een beperkte scope kan aanvullende eisen voor een beveiligingsbeoordeling opleveren. Vraag alleen offline toegang aan wanneer werk op de achtergrond echt nodig is. Versleutel refresh tokens, koppel elk token aan één interne tenant en één Google-subject, stel het nooit bloot aan browsercode of logs, en bied een geteste manier om los te koppelen die lokale credentials verwijdert en verwerking op de achtergrond stopt.

Begrijp serviceaccounts en domeinbrede delegatie

Een serviceaccount is een applicatie-identiteit, geen kant-en-klare Gmail-inbox. Op zichzelf krijgt het geen toegang tot de berichten van medewerkers. Voor gebruikersgegevens in Google Workspace moet een superbeheerder de numerieke client-ID van het serviceaccount en een exacte lijst OAuth-scopes expliciet autoriseren via domeinbrede delegatie. De applicatie vraagt daarna gedelegeerde credentials aan voor een bij naam genoemde gebruiker, en elke API-call handelt met de rechten van die gebruiker binnen de geautoriseerde scopes. Houd het geïmpersoneerde subject expliciet in jobgegevens en auditlogs, zodat een worker op de achtergrond niet stilzwijgend van mailbox kan wisselen. Gebruik aparte serviceaccounts voor wezenlijk verschillende workloads, vermijd downloadbare private keys wanneer de runtime beheerde credentials kan gebruiken, en beoordeel domeinbrede machtigingen volgens een vast schema. Consumentenaccounts van Gmail hebben geen Workspace-beheerder die deze organisatiebrede delegatie kan verlenen; gebruik voor die accounts daarom OAuth-toestemming van de gebruiker.

Verzend berichten zonder controle of controleerbaarheid te verliezen

Gmail accepteert via `users.messages.send` een volledig internet-e-mailbericht in het veld `raw`, gecodeerd met base64url; een product kan ook een concept maken en dat later verzenden. Gebruik een onderhouden berichtenbibliotheek om de structuur van From, To, Cc, Bcc, Subject, Date, Message-ID, tekst, HTML en bijlagen te genereren in plaats van headerregels handmatig samen te voegen. Valideer ontvangers en inhoud vóór het coderen, weiger header-injectie en stel expliciete groottelimieten in. Maak de productactie idempotent voordat je Gmail aanroept: sla een stabiele event-sleutel van de applicatie, het bedoelde mailboxsubject en een status voor de verzendpoging op. Sla na een geslaagde respons de teruggegeven bericht-ID en thread-ID van Gmail op bij dat event. Als de client een timeout krijgt nadat de request is verzonden, reconcilieer dan de mailboxstatus voordat je opnieuw probeert, want het bericht is mogelijk al geaccepteerd. Een blinde retry kan een dubbele e-mail opleveren, zelfs wanneer de oorspronkelijke respons verloren is gegaan. Gebruik het maken van een concept plus menselijke review wanneer de inhoud of de ontvangers goedkeuring vereisen.

Synchroniseer mailboxwijzigingen met history-records

Voor een server-side mailboxintegratie publiceert een Gmail-watch wijzigingssignalen via Google Cloud Pub/Sub. De notificatie is een aanleiding om te synchroniseren, geen volledige e-mailpayload. Sla de huidige history-ID en de vervaldatum uit de watch-respons op, bevestig notificaties snel en roep `users.history.list` aan vanaf de laatst succesvol vastgelegde history-ID om wijzigingen in berichten en labels te vinden. Haal alleen de berichten op die de functie nodig heeft en verschuif het checkpoint pas nadat de lokale schrijfacties zijn gelukt. Notificaties kunnen vertraagd of dubbel aankomen; maak de verwerking van berichten en history daarom idempotent. Gmail vereist dat een mailbox-watch ten minste elke zeven dagen wordt vernieuwd en raadt dagelijkse vernieuwing aan; plan de vernieuwing ruim vóór de vervaldatum en geef een melding bij fouten. Als een opgeslagen history-ID buiten het beschikbare bereik van Gmail valt, geeft de API HTTP 404 terug. Behandel dat als een gedefinieerd herstelpad: voer een gecontroleerde volledige synchronisatie uit, stel een nieuw checkpoint vast en hervat de incrementele verwerking, in plaats van de ongeldige history-ID eindeloos opnieuw te proberen.

Gebruik een gefaseerde workflow voor implementatie en verificatie

Documenteer eerst of de functie mail verzendt, leest, wijzigt of bewaakt, en koppel elke bewerking aan de minimale OAuth-scope. Maak ten tweede aparte Google Cloud-projecten of OAuth-clients voor ontwikkeling en productie, met exacte redirect-URI's en benoemde eigenaren van credentials. Implementeer ten derde autorisatie met validatie van de state, offline toegang alleen waar nodig, versleutelde opslag van tokens, intrekking van tokens en toegangscontroles op tenantniveau. Test ten vierde met gecontroleerde mailboxen: koppelen, een verlopen access token vernieuwen, toestemming intrekken, opnieuw koppelen, één keer verzenden, een onduidelijke timeout simuleren en bevestigen dat duplicaten worden voorkomen. Als je wijzigingen ontvangt, richt dan ten vijfde de Pub/Sub-rechten in, start een watch, verwerk de history incrementeel, forceer herstel na een verouderd checkpoint en verifieer de vernieuwing van de watch. Voeg ten zesde werkqueues per gebruiker toe, begrensde exponential backoff, gestructureerde foutclassificatie en auditlogs die standaard geen berichtinhoud en tokens bevatten. Rond vóór de lancering de vereiste verificatie en beveiligingsreview van Google af, publiceer nauwkeurige informatie over gegevensgebruik en oefen het roteren van credentials en het verwijderen van gebruikersgegevens.

Plan voor quota, retries en gedeeltelijke fouten

Gmail meet API-gebruik in quotumeenheden, niet alleen in het aantal requests. De quotumpagina van Google vermeldt 1.200.000 eenheden per minuut per project en 6.000 eenheden per minuut per gebruiker per project. Daarop staan `messages.send`, `drafts.send` en `watch` elk op 100 eenheden, en een limiet van 500 ontvangers per bericht. De afzonderlijke limieten van Gmail voor gebruikersverzending gelden nog steeds voor API-, web- en SMTP-clients. Behandel de Cloud Console en actuele documentatie als invoer voor runtimeconfiguratie in plaats van gepubliceerde limieten hard te coderen in bedrijfslogica. Serialiseer werk per mailbox of plaats het eerlijk in de wachtrij, beperk concurrency en probeer alleen tijdelijke responses opnieuw met jittered exponential backoff en een eindige deadline. Probeer autorisatie-, beleids-, fouten voor ongeldige ontvangers of fouten voor onjuist gevormde berichten niet opnieuw alsof het capaciteitsproblemen zijn. Een multipartbatch vermindert connection overhead, maar elke binnenste aanroep verbruikt nog steeds quotum en kan onafhankelijk mislukken.

Houd acceptatie, bezorging en inboxplaatsing gescheiden

Een geslaagde `messages.send`-call betekent dat Gmail de geautoriseerde API-request heeft geaccepteerd en een Gmail Message-resource heeft teruggegeven. Het bewijst niet dat de mailserver van elke ontvanger het bericht heeft geaccepteerd, en het kan niet vaststellen hoe een ontvangend systeem het bericht heeft geclassificeerd. Bezorging bij de server van de ontvanger betekent dat het bestemmingssysteem de SMTP-verantwoordelijkheid heeft aanvaard. Inboxplaatsing is een latere filteruitkomst, zoals de primaire inbox, promoties, quarantaine of spam. De mailbox-API van Gmail is daarom geen vervanging voor een eventstream van een provider wanneer een product telemetrie over bezorging, bounces of klachten nodig heeft voor transactionele mail. Bewaar de Gmail-bericht-ID voor reconciliatie, maar beschrijf de status die de gebruiker ziet precies als verzonden of door Gmail geaccepteerd, tenzij afzonderlijk bewijs bezorging ondersteunt. Authenticatie, verwachte ontvangers, kwaliteit van de inhoud, verzendgedrag en het beleid van de bestemming beïnvloeden allemaal de verdere afhandeling. Een API-respons kan de uiteindelijke mailboxmap van de ontvanger niet bepalen of beloven.

Weet wanneer een transactionele e-mail-API bij een andere taak past

Gebruik Gmail API wanneer het product geautoriseerde toegang nodig heeft tot de Gmail-mailbox van een persoon of organisatie, inclusief threads, labels, concepten of mailboxsynchronisatie. Een transactionele e-mail-API past bij een andere architectuur: door de applicatie geactiveerde berichten die worden verzonden vanaf domeinen die de organisatie beheert, zonder gedelegeerde bevoegdheid om de Gmail-mailbox van een gebruiker te lezen. Een product kan beide typen systemen gebruiken wanneer de grenzen expliciet zijn, bijvoorbeeld Gmail OAuth om de gekoppelde mailbox van een supportagent te lezen en een afzonderlijk geverifieerde transactionele provider om productontvangstbewijzen te versturen. Houd credentials, toestemming, berichtopslag, retrybeleid en auditrecords gescheiden, zodat mailboxbevoegdheid niet kan lekken naar applicatiebrede verzending en een transactionele credential de Gmail van een gebruiker niet kan lezen.

Veelgestelde vragen

Kan een serviceaccount elke Gmail-mailbox openen?

Nee. Een serviceaccount krijgt niet automatisch toegang tot Gmail-gebruikersgegevens. Een superbeheerder van Google Workspace moet domeinbrede delegatie verlenen aan de numerieke client-ID en de goedgekeurde scopes, waarna de applicatie expliciet een gebruiker in die organisatie impersoneert. Gebruik voor consumentenaccounts van Gmail in plaats daarvan OAuth-toestemming van de gebruiker.

Welke OAuth-scope moet een Gmail-integratie aanvragen die alleen verzendt?

Begin met het beoordelen van `https://www.googleapis.com/auth/gmail.send`, waarmee je namens de gebruiker kunt verzenden zonder algemene leestoegang tot de mailbox te krijgen. Bevestig dat geen enkele producteis echt concepten, het lezen van berichten, labels of wijzigingen nodig heeft voordat je een bredere scope aanvraagt, en houd rekening met de verificatieregels van Google voor gevoelige scopes.

Betekent een geslaagde verzending via de Gmail API dat het bericht is afgeleverd?

Nee. Het bevestigt dat Gmail de geautoriseerde API-bewerking heeft geaccepteerd en een berichtrecord heeft teruggegeven. Acceptatie door de ontvangende server en inboxplaatsing zijn afzonderlijke latere toestanden. Label het bericht niet als afgeleverd en beloof geen inboxplaatsing, tenzij een ander betrouwbaar signaal die conclusie ondersteunt.

Bevatten pushnotificaties van Gmail het volledige nieuwe bericht?

Nee. Een Pub/Sub-notificatie geeft aan dat de mailboxstatus is veranderd en bevat informatie om de synchronisatie voort te zetten. De applicatie moet de Gmail-history opvragen vanaf de opgeslagen history-ID, de benodigde berichtgegevens ophalen, idempotent verwerken en daarna het checkpoint verschuiven.

Hoe vaak moet een Gmail-mailbox-watch worden vernieuwd?

Google vereist dat je `watch` ten minste eens per zeven dagen aanroept en raadt dagelijkse vernieuwing aan. Sla de teruggegeven vervaldatum op, vernieuw ruim daarvoor, monitor fouten en houd een fallback-synchronisatiejob achter de hand, zodat een gemiste vernieuwing niet stilzwijgend tot een onbegrensd gat in de gegevens leidt.

Wanneer moet een team een transactionele e-mail-API gebruiken in plaats van de Gmail API?

Gebruik een transactionele e-mail-API wanneer het gaat om e-mail die door de applicatie wordt getriggerd vanaf domeinen die de organisatie beheert, en geen enkele functie toegang nodig heeft tot iemands Gmail-mailbox. Gebruik de Gmail API wanneer het product specifiek gedelegeerde toegang nodig heeft tot berichten, threads, labels, concepten of instellingen van een mailbox, of de bevoegdheid om als iemand anders te verzenden.

Bronnen

Verder leren

Implementatiegids voor e-mail-API's voor productteamsOntwerp een veilige integratie met een e-mail-API met geverifieerde domeinen, verzending via een queue, stabiele identifiers, gecontroleerde retries, bezorgevents, suppressie en tenantisolatie.