Migrazione dall'API Email Settings

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 o expired.
  • 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.