Migrar da API Email Settings

Este documento aborda as principais diferenças entre a API Email Settings e a API Gmail. Use este guia se precisar de ajuda para 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 Gmail têm escopo para um usuário individual e não para todo o domínio. Isso significa que autorizar uma conta de administrador do domínio não permite que você migre 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 no Admin Console para gerar o token de autenticação apropriado.

A API Email Settings usou 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

Alterações no protocolo

A API de configurações de e-mail usa o protocolo GDATA baseado em XML. A API Gmail usa JSON. Como as configurações são compostas principalmente por pares de chave-valor, os payloads são conceitualmente semelhantes 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 rótulos na API Gmail, use o recurso Rótulos.

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

Outras mudanças:

  • Ao atualizar ou excluir marcadores, a API Gmail faz referência a eles pelo código, e não pelo nome.

Como gerenciar filtros

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

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 Use INBOX como o ID do rótulo.
shouldMarkAsRead action.removeLabelIds Use UNREAD como o ID do rótulo.
shouldStar action.addLabelIds Use STARRED como o ID do rótulo.
Rótulo action.addLabelIds Use o ID do rótulo para adicionar
forwardTo action.forward
shouldTrash action.addLabelIds Use TRASH como o ID do rótulo.
neverSpam action.removeLabelIds Use SPAM como o ID do rótulo.

Outras mudanças:

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

Como gerenciar aliases de enviar como

Para gerenciar aliases de enviar como na API Gmail, use o recurso SendAs.

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

Como gerenciar clipes da Web

As configurações de clipes da Web não estão mais disponíveis por meio da API.

Como gerenciar 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
enable 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 por meio do recurso ForwardingAddresses.

Gerenciamento de configurações POP

Para gerenciar o acesso POP na API Gmail, use o recurso Configurações.

Configuração antiga Nova configuração Observações
enable accessWindow Desativada quando definida 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

Gerenciamento de configurações IMAP

Para gerenciar o acesso IMAP na API Gmail, use o recurso Configurações.

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

Gerenciar as configurações da 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
enable enableAutoReply
endDate endTime
mensagem responseBodyHTML
responseBodyPlainText
startDate startTime
assunto responseSubject

Como gerenciar 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:

  • Agora as assinaturas são gerenciadas por alias.

Como gerenciar configurações de idioma

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

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

Para mais informações, consulte o guia Como gerenciar configurações de idioma.

Gerenciar 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 delega acesso precisa estar ativado para o Gmail. Isso significa, por exemplo, que o usuário delegado não pode ser suspenso em Google Workspace.
    • Um alias de e-mail não pode ser usado como a entrada de e-mail delegado para nenhum dos novos métodos. Um usuário delegado precisa ser indicado pelo endereço de e-mail principal.
  • delegates.create
    • Agora, esse método pode ser usado para criar relacionamentos delegados em vários domínios pertencentes à mesma Google Workspace organização.
    • Esse método agora pode ser usado para usuários que exigem uma alteração de senha no próximo login.
    • Se for bem-sucedido, esse método retornará um recurso Users.settings.delegates no corpo da resposta, em vez de um corpo vazio.
    • Se um dos usuários delegados ou delegados estiver desativado (por exemplo, suspenso em Google Workspace), esse método 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
      (link em inglês)
    • Esse é um método novo, que pode ser preferível em relação ao método delegates.list, dependendo da necessidade.

Como gerenciar configurações gerais

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