Migrar da API Email Settings

Este documento ajuda você a migrar seu app da API Email Settings descontinuada para a API Gmail.

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 são definidas para um usuário individual, e não para todo o domínio. Isso significa que autorizar uma conta de administrador de domínio não permite migrar e-mails de outros usuários no domínio. Em vez disso, use contas de serviço padrão com autoridade em todo o domínio adicionadas a uma lista de permissões no Google 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 consistem principalmente em 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.

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 Gmail faz referência a eles por ID em vez de por nome.

Gerenciar filtros

Para gerenciar filtros na API Gmail, use o recurso settings.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 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.
o rótulo. action.addLabelIds Use o ID do rótulo a ser adicionado
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 um marcador de usuário que você quer adicionar ainda não existir, crie-o explicitamente usando o método labels.create.

Gerenciar aliases de envio como

Para gerenciar os aliases de envio como na API Gmail, use o recurso settings.sendAs.

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

Gerenciar clipes da Web

As configurações de recorte da Web não estão disponíveis na API Gmail.

Gerenciar o encaminhamento automático

Para gerenciar o encaminhamento automático na API Gmail, use o recurso settings.

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:

  • É preciso criar e verificar os endereços de encaminhamento antes de usá-los.
  • Para gerenciar endereços de encaminhamento, use o recurso settings.forwardingAddresses.

Gerenciar 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 settings.

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

Gerenciar configurações de assinatura

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

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

Outras mudanças:

  • Agora você gerencia as assinaturas por alias.

Gerenciar 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

Para mais informações, consulte Gerenciar configurações de idioma.

Gerenciar configurações de delegação

Para gerenciar a delegação na API Gmail, use o recurso settings.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 settings.delegates.create), o usuário delegador precisa estar com o Gmail ativado. Por exemplo, o usuário delegante não pode ser suspenso no Google Workspace.
    • Não é possível usar um alias de e-mail como entrada de e-mail delegado para nenhum dos novos métodos. Você precisa se referir a um usuário delegado pelo endereço de e-mail principal.
  • settings.delegates.create
    • Agora você pode usar esse método para criar relações de delegação em vários domínios pertencentes à mesma organização do Google Workspace.
    • Agora você pode usar esse método para usuários que precisam mudar a senha no próximo login.
    • Se for bem-sucedido, esse método retornará um settings.delegates no corpo da resposta, em vez de um corpo de resposta vazio.
    • Se o usuário delegador ou delegado estiver desativado (por exemplo, suspenso no Google Workspace), esse método vai falhar com um erro HTTP 4XX em vez de um erro HTTP 500.
  • settings.delegates.delete
    • Agora é possível usar esse método para excluir delegados com qualquer VerificationStatus, em vez de apenas delegados que sejam accepted ou expired.
  • settings.delegates.get

Gerenciar configurações gerais

As configurações gerais não estão disponíveis na API Gmail.