Migrar da API Email Settings

Este documento aborda as principais diferenças entre a API Email Settings e a API Gmail. Use este guia para ajudar a migrar seu app para a API Gmail.

Como autorizar solicitações

Assim como a API Email Settings, a API Gmail usa o protocolo OAuth 2.0 para autorizar solicitações. Uma diferença importante é que as permissões da API do Gmail são atribuídas a um usuário individual, e não a todo o domínio. Isso significa que a autorização de uma conta de administrador de domínio não permite migrar e-mails para outros usuários no domínio. Em vez disso, use contas de serviço padrão com autoridade em todo o domínio que estejam na lista de permissões do Admin Console para gerar o token de autenticação adequado.

A API Email Settings usava o escopo:

https://apps-apis.google.com/a/feeds/emailsettings/2.0/

Os escopos equivalentes na API Gmail são:

https://www.googleapis.com/auth/gmail.settings.basic
https://www.googleapis.com/auth/gmail.settings.sharing

Mudanças de protocolo

A API Email Settings usa o protocolo GDATA baseado em XML. A API Gmail usa JSON. Como as configurações são compostas principalmente de pares de chave-valor, os payloads são conceitualizados de forma semelhante entre as versões.

Exemplo de criação de um rótulo:

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>

POST https://www.googleapis.com/gmail/v1/users/{username}/labels
{
   "name": "status updates"
}

Use as bibliotecas de cliente fornecidas em vez de implementar o protocolo diretamente.

Como gerenciar rótulos

Para gerenciar marcadores na API Gmail, use o recurso Labels.

Outras mudanças:

• Ao atualizar ou excluir rótulos, a API do Gmail faz referência a eles por ID em vez de por nome.

Gerenciar filtros

Para gerenciar filtros na API Gmail, use o recurso Filters.

Outras mudanças:

• Se a adição de um rótulo de usuário ainda não existir, ele precisará ser criado explicitamente usando o método labels.create.

Gerenciar aliases de envio em nome de outra pessoa

Para gerenciar os aliases de envio na API Gmail, use o recurso SendAs.

Gerenciar clipes da Web

As configurações do Web Clip não estão mais disponíveis pela API.

Gerenciar as configurações de encaminhamento automático

Para gerenciar o encaminhamento automático na API Gmail, use o recurso Configurações.

Outras mudanças:

• Os endereços de encaminhamento precisam ser criados e verificados antes do uso
• Os endereços de encaminhamento podem ser gerenciados pelo recurso ForwardingAddresses.

Como gerenciar as configurações de POP

Para gerenciar o acesso POP na API Gmail, use o recurso Settings.

Gerenciar configurações do IMAP

Para gerenciar o acesso IMAP na API Gmail, use o recurso Settings.

Gerenciar as configurações de resposta automática de férias

Para gerenciar a resposta automática de férias na API Gmail, use o recurso Configurações.

Como gerenciar as configurações de assinatura

Para gerenciar assinaturas de e-mail na API Gmail, use o recurso SendAs.

Outras mudanças:

• As assinaturas agora são gerenciadas por alias.

Gerenciar as configurações de idioma

Para gerenciar as configurações de idioma na API Gmail, use o recurso Settings.

Consulte o guia de gerenciamento de configurações de idioma para mais informações.

Como gerenciar as configurações de delegação

Para gerenciar a delegação na API Gmail, use o recurso Delegates.

Outras mudanças:

• Geral
  • Para usar qualquer um dos métodos de delegação (incluindo delegates.create), o usuário que delegou precisa ter o Gmail ativado. Isso significa, por exemplo, que o usuário que delegou não pode ser suspenso em Google Workspace.
  • Um alias de e-mail não pode ser usado como entrada de e-mail delegado para nenhum dos novos métodos. O usuário delegado precisa ser identificado pelo endereço de e-mail principal.
• delegates.create
  • Agora, esse método pode ser usado para criar relações de delegação em vários domínios pertencentes à mesma organização Google Workspace.
  • Agora, esse método pode ser usado para usuários que precisam de uma alteração de senha no próximo login.
  • Se bem-sucedido, esse método retornará um recurso Users.settings.delegates no corpo da resposta, em vez de um corpo da resposta vazio.
  • Se um dos usuários delegados ou do delegante estiver desativado (por exemplo, suspenso em Google Workspace), esse método vai falhar com um erro HTTP 4XX em vez de um erro HTTP 500.
• delegates.delete
  • Agora esse método pode ser usado para excluir delegados com qualquer verificationStatus, em vez de apenas delegados que são accepted ou expired.
• delegates.get
  • Esse é um novo método, que pode ser preferido ao método delegates.list, dependendo da necessidade.

Como gerenciar as configurações gerais

As configurações gerais não estão mais disponíveis pela API.