Articles /

Gmail API Overview

De Gmail API is een RESTful API die kan worden gebruikt om toegang te krijgen tot Gmail mailboxen en mail te versturen. Voor de meeste webapplicaties (inclusief mobiele apps) is de Gmail API de beste keuze voor geautoriseerde toegang tot de Gmail-gegevens van een gebruiker.

De Gmail API geeft u flexibele, RESTful toegang tot de inbox van de gebruiker, met een natuurlijke interface naarThreads,Messages,Labels,Drafts,History, en.Settings.Vanuit de moderne taal van uw keuze, kan uw app gebruik maken van de API omGmail functies toe te voegen zoals:

  • Berichten lezen van Gmail
  • E-mailberichten verzenden
  • De labels wijzigen die zijn toegepast op berichten en threads
  • Zoeken naar specifieke berichten en threads
  • Filters maken om automatisch labels te maken, berichten door te sturen of te archiveren

Alles wat u nodig heeft om de Gmail API te gebruiken is de client library voor de taal van uw keuze en een app die zich kan authenticeren als een Gmail gebruiker.

Typische use-cases

De Gmail API kan worden gebruikt in een verscheidenheid van verschillende toepassingen, waaronder, typisch:

  • Read-only mailextractie, indexering en back-up
  • Labelbeheer (labels toevoegen/verwijderen)
  • Geautomatiseerde of programmatische verzending van berichten
  • Migreren van e-mailaccounts van andere providers
  • Instellen van gestandaardiseerde e-mailhandtekeningen voor gebruikers in een domein

Hoe kan ik meer te weten komen?

Gebruik deze documentatie om vandaag nog te beginnen met het bouwen van een Gmail app:

  • De client libraries zijn beschikbaar voor download in verschillende talen en vereenvoudigen het doen van API requests.
  • De developer guide topics helpen u beter te begrijpen hoe u specifieke use cases kunt implementeren.
  • De API-referentie geeft u details over elke resource en methode in de Gmail API.

API-overzicht

De Gmail API is een webservice: het maakt gebruik van een RESTful API met een JSON payload.Dit gedeelte geeft een algemeen overzicht van de API-functies en hun gebruik. Raadpleeg de GmailAPI-referentie voor gedetailleerde informatie over de API-bronnen en -methoden.

Key resource types

De Gmail API biedt verschillende resource types:

  • Berichten
  • Labels
  • Drafts
  • Geschiedenis
  • Threads
  • Instellingen

Berichten en labels zijn de basiseenheden van een mailbox. Concepten, geschiedenis en threads bevatten alle een of meer berichten met aanvullende metagegevens.

Berichten zijn onveranderlijk: ze kunnen alleen worden aangemaakt en verwijderd. Geen enkele eigenschap van een bericht kan worden gewijzigd, behalve de labels die aan het bericht zijn toegekend.

Labels dienen als het primaire middel om berichten en threads te categoriseren en te organiseren. Een label heeft een veel-op-veel relatie met berichten en threads: een enkel bericht kan meerdere labels hebben en een enkel label kan worden toegepast op meerdere berichten of threads. Er zijn twee soorten labels: system en user. Systeemlabels, zoals INBOX, TRASH, of SPAM, worden intern aangemaakt en kunnen niet worden aangemaakt, verwijderd of gewijzigd. Sommige systeemlabels, zoals INBOX, kunnen echter wel worden toegepast op of verwijderd uit berichten en threads. Gebruikerslabels kunnen worden toegevoegd, verwijderd of gewijzigd door de gebruiker of een applicatie.

Opslorpingen vertegenwoordigen niet-verzonden berichten. De berichten zelf kunnen niet worden gewijzigd zodra ze zijn gemaakt, maar het bericht in het concept kan worden vervangen. Het verzenden van een concept verwijdert automatisch het concept en creëert een bericht met het SENT systeem label.

Historie is een verzameling van recent gewijzigde berichten in chronologische volgorde. Hoewel de geschiedenis is bedoeld als een lichtgewicht methode voor het synchroniseren van een client, bevat het meestal alleen records van wijzigingen in de afgelopen 30 dagen. In sommige gevallen, zoals wanneer een client te verouderd raakt, zou de client handmatig moeten synchroniseren.

Threads zijn verzamelingen van berichten die een conversatie vertegenwoordigen. Net als berichten kunnen ook threads worden voorzien van labels. In tegenstelling tot berichten kunnen threads echter niet worden aangemaakt, alleen verwijderd. Berichten kunnen echter wel in een thread worden ingevoegd.

Instellingen bepalen hoe functies van Gmail zich gedragen voor een gebruiker. Instellingen zijn beschikbaar voor POP en IMAP toegang, e-mail doorsturen, filters, vakantie auto-respons, send-as aliassen, handtekeningen, delegaties, en taal.

Auth en de Gmail API

Net als andere Google REST API’s, de Gmail API gebruiktOAuth 2.0 om authenticatie en autorisatie af te handelen. Uw app specificeert een of meer scopes: strings die bronnen identificeren waartoe het toegang moet krijgen. Deze scopes worden samen met een set tokens gebruikt om de toegang van een gebruiker tot bronnen te beveiligen.Een scope vertegenwoordigt een bepaalde vorm van toegang tot een enkele bron of tot een groep van bronnen, bijvoorbeeld:

  • Leest een bericht uit Gmail (https://www.googleapis.com/auth/gmail.readonly)
  • Wijzig labels die zijn toegepast op een thread of bericht(https://www.googleapis.com/auth/gmail.modify)
  • Verstuur een bericht namens een gebruiker(https://www.googleapis.com/auth/gmail.compose)

Hoewel u de webservice-autorisatieaanroepen expliciet kunt coderen, moet u uw app normaal gesproken vereenvoudigen door gebruik te maken van de Google API-clientbibliotheken die beschikbaar zijn voor veel programmeertalen.

Voor meer over het gebruik van auth met de Gmail API, zie Uw app autoriseren met Gmail.

Scopes

De Gmail API ondersteunt een aantal fijnkorrelige autorisatiescopes om alleen het vereiste toegangsniveau toe te staan. Door de minimaal vereiste toegang te vragen, voelen gebruikers zich zekerder bij het verlenen van toegang tot hun mailbox.

Voorbeeld use case

Neem de volgende use case in overweging: het afdrukken van een pagina met threads voor de huidige geauthenticeerde gebruiker (bijvoorbeeld in een recente berichten paneel).Om dit te bereiken, zou uw app de volgende stappen uitvoeren:

  1. Authenticeer als de gebruiker, gebruikmakend van hethttps://www.googleapis.com/auth/gmail.readonly bereik.
  2. Roep de API-methode op.GET https://www.googleapis.com/gmail/v1/users/<userId>/threads
  3. Verwerk de geretourneerde lijst van threads in uw app.

Voor actuele voorbeeldcode, raadpleeg de Quickstart voor de taal van uw keuze.

Common uses

Deze sectie geeft een zeer high-level beeld van hoe sommige veelvoorkomende use-cases kunnen worden geïmplementeerd. Voor meer details, raadpleeg de gidsen voor ontwikkelaars.

Versturen van Gmail berichten

Emails worden verzonden als base64url gecodeerde strings binnen de raweigenschap van een bericht. Om een bericht te maken en te verzenden:

  1. Maak de inhoud van de e-mail op een handige manier, die kan afhangen van de programmeertaal die u gebruikt.
  2. Maak een base64url gecodeerde string representatie van die inhoud.
  3. Maak een nieuwe messageresource en stel de raw property daarvan in op de base64url string die u zojuist hebt gemaakt.
  4. Roep messages.send op om het bericht te verzenden.

Ontvangen e-mails ophalen

Gegeven de ID van een e-mail, kunt u de inhoud ophalen met deget methode van de Users.messages resource.

Wanneer u een bericht ophaalt, kunt u het payload formaat voor de respons opgeven.FULL (het standaard) formaat retourneert het gehele bericht in het payload veld.MINIMAL formaat retourneert alleen de metadata zoals identifiers en labels.RAW formaat retourneert de data als een base64url gecodeerde string binnen de raw eigenschap.

Mail wijzigingsgeschiedenis

Berichtwijzigingen worden weergegeven doorHistory objects. Met destart_history_id eigenschap kunt u instellen vanaf welk punt u de wijzigingen terug wilt zien. Sommige wijzigingen kunnen meer dan één bericht betreffen en dan zal de geschiedenis die deze wijziging weergeeft meerdere berichten bevatten.

Labelbeheer

Labels die worden toegepast op een draad worden ook toegepast op alle berichten binnen de draad.Als een label wordt verwijderd, wordt het verwijderd van alle draden en berichten waarop het werd toegepast. De messageListVisibility eigenschap wordt gebruikt om te bepalen of berichten met dit label in de berichtenlijst verschijnen. Op dezelfde manier wordt delabelListVisibility eigenschap gebruikt om te bepalen of het label in de label lijst verschijnt. U kunt de methodemessages.modify ofthreads.modify gebruiken om de labels te veranderen die worden toegepast op berichten of threads, respectievelijk.

Leave a Reply