Eseguire la migrazione dall'API Email Settings

Questo documento può aiutarti a eseguire la migrazione della tua app dall'API Email Settings che è stata ritirata, all'API Gmail.

Autorizza 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 sono limitate 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 gli account di servizio standard con autorità a livello di dominio aggiunti a una lista consentita nella Console di amministrazione Google 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 del protocollo

L'API Email Settings utilizza il protocollo GDATA basato su XML. L'API Gmail utilizza 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.

Gestisci etichette

Per gestire le etichette nell'API Gmail, utilizza la labels risorsa.

Vecchia impostazione Nuova impostazione Note
labelId id
label name
unreadCount messagesUnread
visibility labelListVisibility SHOW è ora labelShow
è ora HIDElabelHide

Altre modifiche:

  • Quando aggiorna o elimina le etichette, l'API Gmail fa riferimento alle etichette per ID anziché per nome.

Gestisci filtri

Per gestire i filtri nell'API Gmail, utilizza la settings.filters risorsa.

Vecchia impostazione Nuova impostazione Note
from criteria.from
to criteria.to
subject 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
label 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'aggiunta di un'etichetta utente non esiste già, deve essere creata esplicitamente utilizzando il labels.create metodo.

Gestisci gli alias di invio come

Per gestire gli alias di invio come nell'API Gmail, utilizza la settings.sendAs risorsa.

Vecchia impostazione Nuova impostazione
name displayName
address sendAsEmail
replyTo replyToAddress
makeDefault isDefault

Gestisci i clip web

Le impostazioni dei clip web non sono disponibili nell'API Gmail.

Gestisci l'inoltro automatico

Per gestire l'inoltro automatico nell'API Gmail, utilizza la settings risorsa.

Vecchia impostazione Nuova impostazione Note
enable enabled
forwardTo emailAddress
action disposition 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 dell'uso.
  • Gli indirizzi di inoltro possono essere gestiti utilizzando la settings.forwardingAddresses risorsa.

Gestisci le impostazioni POP

Per gestire l'accesso POP nell'API Gmail, utilizza la settings risorsa.

Vecchia impostazione Nuova impostazione Note
enable accessWindow Disattivato se impostato su disabled
enableFor accessWindow ALL_MAIL è ora allMail
MAIL_FROM_NOW_ON è ora fromNowOn
action disposition KEEP è ora leaveInInbox
ARCHIVE è ora archive
DELETE è ora trash
MARK_READ è ora markRead

Gestisci le impostazioni IMAP

Per gestire l'accesso IMAP nell'API Gmail, utilizza la settings risorsa.

Vecchia impostazione Nuova impostazione
enable enabled

Gestisci le impostazioni di risposta automatica per le vacanze

Per gestire la risposta automatica per le vacanze nell'API Gmail, utilizza la settings risorsa.

Vecchia impostazione Nuova impostazione
contactsOnly restrictToContacts
domainOnly restrictToDomain
enable enableAutoReply
endDate endTime
message responseBodyHtml
responseBodyPlainText
startDate startTime
subject responseSubject

Gestisci le impostazioni della firma

Per gestire le firme email nell'API Gmail, utilizza la settings.sendAs risorsa.

Vecchia impostazione Nuova impostazione
signature signature

Altre modifiche:

  • Le firme vengono ora gestite per alias.

Gestisci le impostazioni della lingua

Per gestire le impostazioni della lingua nell'API Gmail, utilizza la settings risorsa.

Vecchia impostazione Nuova impostazione
language displayLanguage

Per saperne di più, consulta Gestire le impostazioni della lingua.

Gestisci le impostazioni relative alle deleghe

Per gestire le deleghe nell'API Gmail, utilizza la settings.delegates risorsa.

Vecchia impostazione Nuova impostazione
address delegateEmail
status verificationStatus

Altre modifiche:

  • Generali
    • Per utilizzare uno dei metodi di delega (incluso settings.delegates.create) l'utente delegante deve essere abilitato per Gmail. Ciò significa, ad esempio, che l'utente delegante non può essere sospeso in Google Workspace.
    • Un alias email non può essere utilizzato come input email del delegato per nessuno dei nuovi metodi. Un utente delegato deve essere indicato con il suo indirizzo email principale.
  • settings.delegates.create
    • Questo metodo può ora essere utilizzato per creare relazioni di delega in più domini appartenenti alla stessa organizzazione Google Workspace.
    • Questo metodo può ora essere utilizzato per gli utenti che richiedono una modifica della password al successivo accesso.
    • In caso di esito positivo, questo metodo restituisce una settings.delegates risorsa nel corpo della risposta, anziché un corpo della risposta vuoto.
    • Se uno degli utenti delegante o delegato è disattivato (ad esempio, sospeso in Google Workspace), questo metodo non riesce a generare un errore HTTP 4XX anziché un errore HTTP 500.
  • settings.delegates.delete
    • Questo metodo può ora essere utilizzato per eliminare i delegati con qualsiasi VerificationStatus, anziché solo i delegati accepted o expired.
  • settings.delegates.get
    • Questo è un nuovo metodo, che potrebbe essere preferibile al settings.delegates.list metodo a seconda delle esigenze.

Gestisci le impostazioni generali

Le impostazioni generali non sono disponibili nell'API Gmail.