Eseguire la migrazione dall'API Email Settings

Questo documento ti aiuta a eseguire la migrazione della tua app dall'API Email Settings API 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 del dominio non 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 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 al 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 risorsa labels.

Vecchia impostazione Nuova impostazione Note
labelId id
etichetta nome
unreadCount messagesUnread
visibilità labelListVisibility SHOW ora costa labelShow
HIDE ora costa labelHide

Altre modifiche:

  • Quando aggiorni o elimini 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 risorsa settings.filters.

Vecchia impostazione 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 Utilizzare 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 un'etichetta utente che vuoi aggiungere non esiste già, devi crearla esplicitamente utilizzando il metodo labels.create.

Gestire gli alias Invia come

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

Vecchia impostazione Nuova impostazione
nome displayName
indirizzo sendAsEmail
replyTo replyToAddress
makeDefault isDefault

Gestire i web clip

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

Gestire l'inoltro automatico

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

Vecchia impostazione Nuova impostazione Note
attiva attivato
forwardTo emailAddress
azione disposizione KEEP ora costa leaveInInbox
ARCHIVE ora costa archive
DELETE ora costa trash
MARK_READ ora costa markRead

Altre modifiche:

  • Devi creare e verificare gli indirizzi di inoltro prima di poterli utilizzare.
  • Per gestire gli indirizzi di inoltro, utilizza la risorsa settings.forwardingAddresses.

Gestire le impostazioni POP

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

Vecchia impostazione Nuova impostazione Note
attiva accessWindow Disattivato se impostato su disabled
enableFor accessWindow ALL_MAIL ora costa allMail
MAIL_FROM_NOW_ON ora costa fromNowOn
azione disposizione KEEP ora costa leaveInInbox
ARCHIVE ora costa archive
DELETE ora costa trash
MARK_READ ora costa markRead

Gestire le impostazioni IMAP

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

Vecchia impostazione Nuova impostazione
attiva attivato

Gestire le impostazioni della risposta automatica per le ferie

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

Vecchia impostazione Nuova impostazione
contactsOnly restrictToContacts
domainOnly restrictToDomain
attiva enableAutoReply
endDate endTime
messaggio responseBodyHtml
responseBodyPlainText
startDate startTime
oggetto responseSubject

Gestire le impostazioni della firma

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

Vecchia impostazione Nuova impostazione
firma firma

Altre modifiche:

  • Ora gestisci le firme per alias.

Gestire le impostazioni della lingua

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

Vecchia impostazione Nuova impostazione
language displayLanguage

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

Gestisci le impostazioni relative alle deleghe

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

Vecchia impostazione Nuova impostazione
indirizzo delegateEmail
stato verificationStatus

Altre modifiche:

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

Gestisci le impostazioni generali

Le impostazioni generali non sono disponibili nell'API Gmail.