Questo documento illustra le principali differenze tra l'API Email Settings e l'API Gmail. Puoi utilizzare questa guida per eseguire la migrazione della tua app all'API Gmail.
Autorizzazione delle richieste
Come l'API Email Settings, l'API Gmail utilizza il protocollo OAuth 2.0 per autorizzare le richieste. Una differenza fondamentale è che le autorizzazioni dell'API Gmail si applicano a un singolo utente anziché all'intero dominio. Ciò significa che l'autorizzazione di un account amministratore di dominio non ti consente di eseguire la migrazione della posta per altri utenti del dominio. Devi invece utilizzare account di servizio standard con autorità a livello di dominio che sono inseriti nella lista consentita nella Console di amministrazione per generare il token di autenticazione appropriato.
L'API Email Settings utilizzava l'ambito:
https://apps-apis.google.com/a/feeds/emailsettings/2.0/
Gli ambiti equivalenti nell'API Gmail sono:
https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing
Modifiche al protocollo
L'API Email Settings utilizza il protocollo GDATA basato su XML. L'API Gmail utilizza il formato JSON. Poiché le impostazioni sono costituite principalmente da coppie chiave/valore, i payload sono concettualmente simili tra le versioni.
Esempio di creazione di un'etichetta:
API Email Settings
POST https://apps-apis.google.com/a/feeds/emailsettings/2.0/{domain name}/{username}/label
<?xml version="1.0" encoding="utf-8"?>
<atom:entry xmlns:atom="http://www.w3.org/2005/Atom" xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name="label" value="status updates" />
</atom:entry>
API Gmail
POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
"name": "status updates"
}
Utilizza le librerie client fornite anziché implementare direttamente il protocollo.
Gestione delle etichette
Per gestire le etichette nell'API Gmail, utilizza la risorsa Etichette.
| Impostazione precedente | Nuova impostazione | Note |
|---|---|---|
| labelId | id | |
| etichetta | nome | |
| unreadCount | messagesUnread | |
| visibilità | labelListVisibility | SHOW è diventato labelShowHIDE è diventato labelHide |
Altre modifiche:
- Quando aggiorna o elimina le etichette, l'API Gmail fa riferimento alle etichette per ID instead of per nome.
Gestione dei filtri
Per gestire i filtri nell'API Gmail, utilizza la risorsa Filters.
| Impostazione precedente | Nuova impostazione | Note |
|---|---|---|
| da | criteria.from | |
| a | criteria.to | |
| oggetto | criteria.subject | |
| hasTheWord | criteria.query | |
| doesNotHaveTheWord | criteria.negatedQuery | |
| hasAttachment | criteria.hasAttachment | |
| shouldArchive | action.removeLabelIds | Utilizza INBOX come ID etichetta |
| shouldMarkAsRead | action.removeLabelIds | Utilizza UNREAD come ID etichetta |
| shouldStar | action.addLabelIds | Utilizza STARRED come ID etichetta |
| etichetta | action.addLabelIds | Utilizza l'ID dell'etichetta da aggiungere |
| forwardTo | action.forward | |
| shouldTrash | action.addLabelIds | Utilizza TRASH come ID etichetta |
| neverSpam | action.removeLabelIds | Utilizza SPAM come ID etichetta |
Altre modifiche:
- Se l'etichetta utente da aggiungere non esiste già, deve essere creata esplicitamente utilizzando il metodo labels.create.
Gestire gli alias di invio
Per gestire gli alias di invio come nell'API Gmail, utilizza la risorsa SendAs.
| Impostazione precedente | Nuova impostazione |
|---|---|
| nome | displayName |
| indirizzo | sendAsEmail |
| replyTo | replyToAddress |
| makeDefault | isDefault |
Gestire i clip web
Le impostazioni dei clip web non sono più disponibili tramite l'API.
Gestione delle impostazioni di inoltro automatico
Per gestire il recapito automatico nell'API Gmail, utilizza la risorsa Impostazioni.
| Impostazione precedente | Nuova impostazione | Note |
|---|---|---|
| attiva | abilitata | |
| forwardTo | emailAddress | |
| azione | disposizione | KEEP è diventato leaveInInboxARCHIVE è diventato archiveDELETE è diventato trashMARK_READ è diventato markRead |
Altre modifiche:
- Gli indirizzi di inoltro devono essere creati e verificati prima dell'utilizzo
- Gli indirizzi di inoltro possono essere gestiti tramite la risorsa ForwardingAddresses.
Gestione delle impostazioni POP
Per gestire l'accesso POP nell'API Gmail, utilizza la risorsa Impostazioni.
| Impostazione precedente | Nuova impostazione | Note |
|---|---|---|
| attiva | accessWindow | Disattivato se impostato su disabled |
| enableFor | accessWindow | ALL_MAIL è diventato allMailMAIL_FROM_NOW_ON è diventato fromNowOn |
| azione | disposizione | KEEP è diventato leaveInInboxARCHIVE è diventato archiveDELETE è diventato trashMARK_READ è diventato markRead |
Gestione delle impostazioni IMAP
Per gestire l'accesso IMAP nell'API Gmail, utilizza la risorsa Impostazioni.
| Impostazione precedente | Nuova impostazione |
|---|---|
| attiva | abilitata |
Gestione delle impostazioni di risposta automatica per le assenze
Per gestire la risposta automatica per le ferie nell'API Gmail, utilizza la risorsa Impostazioni.
| Impostazione precedente | Nuova impostazione |
|---|---|
| contactsOnly | restrictToContacts |
| domainOnly | restrictToDomain |
| attiva | enableAutoReply |
| endDate | endTime |
| messaggio | responseBodyHtml responseBodyPlainText |
| startDate | startTime |
| oggetto | responseSubject |
Gestione delle impostazioni della firma
Per gestire le firme delle email nell'API Gmail, utilizza la risorsa SendAs.
| Impostazione precedente | Nuova impostazione |
|---|---|
| firma | firma |
Altre modifiche:
- Le firme ora vengono gestite per alias.
Gestire le impostazioni della lingua
Per gestire le impostazioni della lingua nell'API Gmail, utilizza la risorsa Impostazioni.
| Impostazione precedente | Nuova impostazione |
|---|---|
| language | displayLanguage |
Per ulteriori informazioni, consulta la guida alla gestione delle impostazioni della lingua.
Gestione delle impostazioni di delega
Per gestire la delega nell'API Gmail, utilizza la risorsa Delegates.
| Impostazione precedente | Nuova impostazione |
|---|---|
| indirizzo | delegateEmail |
| stato | verificationStatus |
Altre modifiche:
- Generale
- Per utilizzare uno dei metodi di delega (incluso delegates.create), l'utente delegante deve essere attivato per Gmail. Ciò significa, ad esempio, che l'utente del delegante non può essere sospeso in Google Workspace.
- Un alias email non può essere utilizzato come input email del rappresentante per nessuno dei nuovi metodi. Un utente delegato deve essere indicato tramite il suo indirizzo email principale.
- delegates.create
- Ora questo metodo può essere utilizzato per creare relazioni di delega in più Google Workspace domini appartenenti alla stessa organizzazione.
- Ora questo metodo può essere utilizzato per gli utenti che richiedono una modifica della password al successivo accesso.
- In caso di esito positivo, questo metodo restituisce una risorsa Users.settings.delegates nel corpo della risposta anziché un corpo della risposta vuoto.
- Se uno degli utenti del delegante o del delegato è disattivato (ad esempio, è stato sospeso in Google Workspace), questo metodo non va a buon fine con un errore HTTP 4XX anziché con un errore HTTP 500.
- delegates.delete
- Ora questo metodo può essere utilizzato per eliminare i delegati con qualsiasi valore di verificationStatus, anziché solo i delegati con valore
acceptedoexpired.
- Ora questo metodo può essere utilizzato per eliminare i delegati con qualsiasi valore di verificationStatus, anziché solo i delegati con valore
- delegates.get
- Si tratta di un nuovo metodo, che potrebbe essere preferibile al metodo delegates.list a seconda delle esigenze.
Gestione delle impostazioni generali
Le impostazioni generali non sono più disponibili tramite l'API.