Articles /

Gmail API Overview

La Gmail API è una API RESTful che può essere usata per accedere alle caselle di posta Gmail e per inviare posta. Per la maggior parte delle applicazioni web (comprese le applicazioni mobili), la Gmail API è la scelta migliore per l’accesso autorizzato ai dati Gmail di un utente.

La Gmail API ti dà un accesso flessibile e RESTful alla casella di posta dell’utente, con un’interfaccia naturale aThreads,Messages,Labels,Drafts,History, e Settings.Dal linguaggio moderno di vostra scelta, la vostra app può utilizzare l’API per aggiungere funzioni di Gmail come:

  • Leggere messaggi da Gmail
  • Inviare messaggi email
  • Modificare le etichette applicate ai messaggi e alle discussioni
  • Cercare messaggi e discussioni specifiche
  • Creare filtri per etichettare automaticamente, inoltrare o archiviare automaticamente i messaggi

Tutto ciò di cui hai bisogno per usare l’API di Gmail è la libreria client per la tua scelta di lingua e un’applicazione che possa autenticarsi come utente Gmail.

Casi d’uso tipici

L’API di Gmail può essere usata in una varietà di applicazioni diverse, tra cui, tipicamente:

  • Estrazione della posta in sola lettura, indicizzazione e backup
  • Gestione delle etichette (aggiungere/rimuovere le etichette)
  • Invio automatizzato o programmatico di messaggi
  • Migrazione di account di posta elettronica da altri provider
  • Impostazione di firme email standardizzate per gli utenti in un dominio

Come posso saperne di più?

Utilizza questa documentazione per iniziare a costruire un’applicazione Gmail oggi stesso:

  • Le librerie client sono disponibili per il download in diverse lingue e semplificano le richieste API.
  • Gli argomenti della guida per sviluppatori ti aiutano a capire meglio come implementare casi d’uso particolari.
  • Il riferimento all’API ti fornisce dettagli su ogni risorsa e metodo dell’API di Gmail.

Panoramica dell’API

L’API di Gmail è un servizio web: usa un’API RESTful con un payload JSON.Questa sezione fornisce una panoramica generale delle caratteristiche dell’API e del loro utilizzo. Per informazioni dettagliate sulle risorse e i metodi dell’API, fare riferimento al riferimento GmailAPI.

Tipi di risorse chiave

L’API di Gmail fornisce diversi tipi di risorse:

  • Messaggi
  • Etichette
  • Drafts
  • History
  • Threads
  • Impostazioni

Messaggi ed etichette sono le unità di base di una casella di posta. Bozze, cronologia e threads contengono tutti uno o più messaggi con metadati aggiuntivi.

I messaggi sono immutabili: possono solo essere creati e cancellati. Nessuna proprietà dei messaggi può essere cambiata a parte le etichette applicate ad un dato messaggio.

Le etichette servono come mezzo principale per categorizzare e organizzare i messaggi e i thread. Un’etichetta ha una relazione molti-a-molti con i messaggi e le discussioni: un singolo messaggio può avere più etichette applicate ad esso e una singola etichetta può essere applicata a più messaggi o discussioni. Le etichette sono anche di due tipi: system e user. Le etichette di sistema, come INBOX, TRASH, o SPAM, sono create internamente e non possono essere create, cancellate o modificate. Tuttavia, alcune etichette di sistema, come INBOX, possono essere applicate o rimosse da messaggi e thread. Le etichette utente possono essere aggiunte, cancellate o modificate dall’utente o da un’applicazione.

Le bozze rappresentano messaggi non inviati. I messaggi stessi non possono essere modificati una volta creati, ma il messaggio contenuto nella bozza può essere sostituito.L’invio di una bozza cancella automaticamente la bozza e crea un messaggio con l’etichetta di sistema SENT.

La cronologia è una collezione di messaggi modificati di recente in ordine cronologico.Mentre la cronologia è intesa come un metodo leggero di sincronizzazione di un client, tipicamente contiene solo record di modifiche negli ultimi 30 giorni. In alcuni casi, come quando un client diventa troppo datato, il client dovrebbe sincronizzarsi manualmente.

I thread sono collezioni di messaggi che rappresentano una conversazione. Come i messaggi, i thread possono anche avere etichette applicate ad essi. Tuttavia, a differenza dei messaggi, i thread non possono essere creati, solo cancellati. I messaggi possono, comunque, essere inseriti in un thread.

Le impostazioni controllano come le caratteristiche di Gmail si comportano per un utente. Le impostazioni sono disponibili per l’accesso POP e IMAP, l’inoltro delle email, i filtri, la risposta automatica alle vacanze, gli alias di invio, le firme, i delegati e la lingua.

Auth e l’API di Gmail

Come altre API REST di Google, l’API di Gmail usaOAuth 2.0 per gestire autenticazione e autorizzazione. La vostra applicazione specificherà uno o più ambiti: stringhe che identificano le risorse a cui deve accedere. Questi ambiti sono usati insieme ad un insieme di token per assicurare l’accesso di un utente alle risorse.Un ambito rappresenta una forma particolare di accesso a una singola risorsa o a un gruppo di risorse, per esempio:

  • Leggere un messaggio da Gmail (https://www.googleapis.com/auth/gmail.readonly)
  • Modificare le etichette applicate a un thread o a un messaggio (https://www.googleapis.com/auth/gmail.modify)
  • Inviare un messaggio per conto di un utente (https://www.googleapis.com/auth/gmail.compose)

Anche se è possibile codificare esplicitamente le chiamate di autorizzazione del servizio web, normalmente si dovrebbe semplificare la propria applicazione utilizzando le librerie client API di Google disponibili per molti linguaggi di programmazione.

Per saperne di più sull’uso dell’autorizzazione con l’API di Gmail, vedi Autorizzare la tua app con Gmail.

Scopi

L’API di Gmail supporta un certo numero di scopi di autorizzazione a grana fine per permettere solo il livello di accesso richiesto. Richiedendo il livello minimo di accesso richiesto, gli utenti si sentono più sicuri nel concedere l’accesso alla loro casella di posta.

Caso d’uso esemplificativo

Considera il seguente caso d’uso: stampare una pagina di discussioni per l’utente attualmente autenticato (per esempio, in un pannello dei messaggi recenti).Per ottenere questo, la tua applicazione dovrebbe eseguire i seguenti passi:

  1. Autenticati come utente, usando l’ambitohttps://www.googleapis.com/auth/gmail.readonly.
  2. Chiamate il metodo API.GET https://www.googleapis.com/gmail/v1/users/<userId>/threads
  3. Elaborate la lista di thread restituita nella vostra app.

Per il codice di esempio reale, fate riferimento al Quickstart per il linguaggio che avete scelto.

Usi comuni

Questa sezione fornisce una visione di alto livello di come possono essere implementati alcuni casi comuni. Per maggiori dettagli, fai riferimento alle guide per gli sviluppatori.

Invio di messaggi Gmail

Le e-mail sono inviate come stringhe codificate con base64url all’interno della rawproprietà di un messaggio. Per creare e inviare un messaggio:

  1. Crea il contenuto dell’email in qualche modo conveniente, che può dipendere dal linguaggio di programmazione che stai usando.
  2. Crea una rappresentazione di stringa codificata con base64url di quel contenuto.
  3. Crea una nuova messageresource e imposta la sua proprietà raw alla stringa base64url che hai appena creato.
  4. Chiama messages.sendper inviare il messaggio.

Ricerca delle email ricevute

Dato l’ID di una email, puoi recuperare il contenuto usando il metodoget della risorsa Users.messages.

Quando vai a prendere un messaggio, puoi specificare il formato del payload per la risposta.Il formato FULL (quello predefinito) restituisce l’intero messaggio analizzato nel campo payload.Il formato MINIMAL restituisce solo i metadati come gli identificatori e le etichette.Il formato RAW restituisce i dati come una stringa codificata in base64url nella proprietà raw.

Storia delle modifiche delle e-mail

Le modifiche dei messaggi sono rappresentate daHistory objects. La proprietàstart_history_id ti permette di impostare da quale punto vuoi che vengano restituiti i cambiamenti. Alcuni cambiamenti possono influenzare più di un messaggio e quindi la storia che rappresenta quel cambiamento conterrà più messaggi.

Gestione delle etichette

Le etichette applicate ad un thread sono anche applicate a tutti i messaggi all’interno del thread.Se un’etichetta viene cancellata, viene rimossa da tutti i thread e messaggi a cui era applicata. La proprietà messageListVisibility è usata per determinare se i messaggi con questa etichetta appaiono nella lista dei messaggi. Allo stesso modo, la proprietàlabelListVisibility è usata per determinare se l’etichetta appare nella lista delle etichette. Puoi usare il metodomessages.modify othreads.modify per cambiare le etichette applicate ai messaggi o ai thread, rispettivamente.

Leave a Reply