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:

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"
}

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.

Configuração antiga Nova configuração Observações
labelId id
o rótulo. nome
unreadCount messagesUnread
visibilidade labelListVisibility SHOW agora é labelShow
HIDE agora é labelHide

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.

Configuração antiga Nova configuração Observações
de criteria.from
a criteria.to
assunto criteria.subject
hasTheWord criteria.query
doesNotHaveTheWord criteria.negatedQuery
hasAttachment criteria.hasAttachment
shouldArchive action.removeLabelIds Usar INBOX como o ID do rótulo
shouldMarkAsRead action.removeLabelIds Usar UNREAD como o ID do rótulo
shouldStar action.addLabelIds Usar STARRED como o ID do rótulo
o rótulo. action.addLabelIds Use o ID do rótulo para adicionar
forwardTo action.forward
shouldTrash action.addLabelIds Usar TRASH como o ID do rótulo
neverSpam action.removeLabelIds Usar SPAM como o ID do rótulo

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.

Configuração antiga Nova configuração
nome displayName
endereço sendAsEmail
replyTo replyToAddress
makeDefault isDefault

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.

Configuração antiga Nova configuração Observações
ativar ativado
forwardTo emailAddress
ação disposition KEEP agora é leaveInInbox
ARCHIVE agora é archive
DELETE agora é trash
MARK_READ agora é markRead

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.

Configuração antiga Nova configuração Observações
ativar accessWindow Desativado quando definido como disabled
enableFor accessWindow ALL_MAIL agora é allMail
MAIL_FROM_NOW_ON agora é fromNowOn
ação disposition KEEP agora é leaveInInbox
ARCHIVE agora é archive
DELETE agora é trash
MARK_READ agora é markRead

Gerenciar configurações do IMAP

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

Configuração antiga Nova configuração
ativar ativado

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.

Configuração antiga Nova configuração
contactsOnly restrictToContacts
domainOnly restrictToDomain
ativar enableAutoReply
endDate endTime
mensagem responseBodyHtml
responseBodyPlainText
startDate startTime
assunto responseSubject

Como gerenciar as configurações de assinatura

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

Configuração antiga Nova configuração
assinatura assinatura

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.

Configuração antiga Nova configuração
language displayLanguage

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.

Configuração antiga Nova configuração
endereço delegateEmail
status verificationStatus

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.