Questo documento illustra le principali differenze tra l'API Email Settings e l'API Gmail. Puoi utilizzare questa guida per facilitare la migrazione della tua app all'API Gmail.
Autorizzazione delle richieste
Analogamente all'API Email Settings, l'API Gmail utilizza il protocollo OAuth 2.0 per autorizzare le richieste. Una differenza fondamentale è che l'ambito delle autorizzazioni dell'API Gmail è un singolo utente, piuttosto che l'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 utilizzare invece account di servizio standard con autorità a livello di dominio autorizzati nella Console di amministrazione per generare il token di autenticazione appropriato.
L'API Email Settings ha utilizzato 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 usa JSON. Poiché le impostazioni sono composte per lo più 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 Labels.
Impostazione precedente | Nuova impostazione | Note |
---|---|---|
labelId | id | |
etichetta | nome | |
unreadCount | messagesUnread | |
visibilità | labelListVisibility | SHOW è ora labelShow HIDE è ora labelHide |
Altre modifiche:
- Durante l'aggiornamento o l'eliminazione delle etichette, l'API Gmail fa riferimento alle etichette per ID anziché per nome.
Gestione dei filtri
Per gestire i filtri nell'API Gmail, utilizza la risorsa Filtri.
Impostazione precedente | Nuova impostazione | Note |
---|---|---|
da | criteria.from | |
a una | criteria.to | |
oggetto | criteria.subject | |
hasTheWord | criteria.query | |
doesNotHaveTheWord | criteria.negatedQuery | |
hasAttachment | criteria.hasAttachment | |
shouldArchive | action.removeLabelIds | Usa INBOX come ID etichetta |
shouldMarkAsRead | action.removeLabelIds | Usa UNREAD come ID etichetta |
shouldStar | action.addLabelIds | Usa STARRED come ID etichetta |
etichetta | action.addLabelIds | Utilizza l'ID dell'etichetta da aggiungere |
forwardTo | action.forward | |
shouldTrash | action.addLabelIds | Usa TRASH come ID etichetta |
neverSpam | action.removeLabelIds | Usa SPAM come ID etichetta |
Altre modifiche:
- Se l'aggiunta di un'etichetta utente non esiste già, deve essere creata esplicitamente utilizzando il metodo labels.create.
Gestione degli alias di invio come
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 |
Gestione dei web clip
Le impostazioni dei clip web non sono più disponibili tramite l'API.
Gestione delle impostazioni di inoltro automatico
Per gestire l'inoltro automatico nell'API Gmail, utilizza la risorsa Impostazioni.
Impostazione precedente | Nuova impostazione | Note |
---|---|---|
enable | abilitata | |
forwardTo | emailAddress | |
azione | disposizione | KEEP è ora leaveInInbox ARCHIVE è ora archive DELETE è ora trash MARK_READ è ora markRead |
Altre modifiche:
- Gli indirizzi di inoltro devono essere creati e verificati prima di essere utilizzati
- Gli indirizzi di forwarding 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 |
---|---|---|
enable | accessWindow | Disabilitata se impostata su disabled |
enableFor | accessWindow | ALL_MAIL è ora allMail MAIL_FROM_NOW_ON è ora fromNowOn |
azione | disposizione | KEEP è ora leaveInInbox ARCHIVE è ora archive DELETE è ora trash MARK_READ è ora markRead |
Gestione delle impostazioni IMAP
Per gestire l'accesso IMAP nell'API Gmail, utilizza la risorsa Impostazioni.
Impostazione precedente | Nuova impostazione |
---|---|
enable | abilitata |
Gestione delle impostazioni delle risposte automatiche per le ferie
Per gestire la risposta automatica durante le vacanze nell'API Gmail, utilizza la risorsa Impostazioni.
Impostazione precedente | Nuova impostazione |
---|---|
contactsOnly | restrictToContacts |
domainOnly | restrictToDomain |
enable | enableAutoReply |
endDate | endTime |
messaggio | rispostaBodyHTML responseBodyPlainText |
startDate | startTime |
oggetto | responseSubject |
Gestione delle impostazioni della firma
Per gestire le firme email nell'API Gmail, utilizza la risorsa SendAs.
Impostazione precedente | Nuova impostazione |
---|---|
firma | firma |
Altre modifiche:
- Ora le firme sono gestite per alias.
Gestione delle 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 Delegati.
Impostazione precedente | Nuova impostazione |
---|---|
indirizzo | delegateEmail |
status | verificationStatus |
Altre modifiche:
- Generale
- Per utilizzare uno qualsiasi dei metodi di delega (incluso delegates.create), l'utente delegante deve essere abilitato per Gmail. Ciò significa, ad esempio, che l'utente del delegante non può essere sospeso in Google Workspace.
- Non è possibile utilizzare un alias email come input email del delegato per nessuno dei nuovi metodi. Un utente delegato deve fare riferimento al proprio indirizzo email principale.
- delegates.create
- Questo metodo ora può essere utilizzato per creare relazioni di delega tra più domini appartenenti alla stessa Google Workspace organizzazione.
- Questo metodo ora può essere utilizzato per gli utenti che richiedono una modifica della password all'accesso successivo.
- Se l'esito è positivo, questo metodo restituisce una risorsaUsers.settings.delegates nel corpo della risposta, anziché un corpo della risposta vuoto.
- Se uno degli utenti del delegante o del delegato è disattivato (ad esempio, è sospeso in Google Workspace), questo metodo non riesce e genera un errore HTTP 4XX anziché un errore HTTP 500.
- delegates.delete
- Questo metodo ora può essere utilizzato per eliminare i delegati con qualsiasi verificationStatus, anziché solo dei delegati
accepted
oexpired
.
- Questo metodo ora può essere utilizzato per eliminare i delegati con qualsiasi verificationStatus, anziché solo dei delegati
- delegates.get
- Questo è un nuovo metodo, che potrebbe essere preferibile rispetto al metodo delegates.list, a seconda delle esigenze.
Gestione delle impostazioni generali
Le impostazioni generali non sono più disponibili tramite l'API.