Migrar da API Email Settings

Este documento pode ajudar 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, você precisa usar contas de serviço padrão com autoridade em todo o domínio que são adicionadas a uma lista de permissões no Google Admin Console para gerar o token de autenticação apropriado.

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 conceitualmente semelhantes entre as versões.

Exemplo de como criar 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 rótulos na API Gmail, use o labels recurso.

Configuração antiga Nova configuração Observações
labelId id
label name
unreadCount messagesUnread
visibility labelListVisibility SHOW agora é labelShow
agora é HIDElabelHide

Outras mudanças:

  • Ao atualizar ou excluir rótulos, a API Gmail faz referência a eles pelo ID, e não pelo nome.

Gerenciar filtros

Para gerenciar filtros na API Gmail, use o settings.filters recurso.

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 a adição de um rótulo de usuário ainda não existir, ele precisará ser criado explicitamente usando o labels.create método.

Gerenciar aliases de envio como

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

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

Gerenciar clipes da Web

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

Gerenciar encaminhamento automático

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

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 usando o settings.forwardingAddresses recurso.

Gerenciar configurações de POP

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

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

Gerenciar configurações de IMAP

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

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

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

Para gerenciar a resposta automática de férias na API Gmail, use o settings recurso.

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 settings.sendAs recurso.

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

Outras mudanças:

  • As assinaturas agora são gerenciadas por alias.

Gerenciar configurações de idioma

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

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 settings.delegates recurso.

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 ativado para o Gmail. Isso significa, por exemplo, que o usuário delegador não pode ser suspenso no Google Workspace.
    • Um alias de e-mail não pode ser usado como entrada de e-mail delegado para nenhum dos novos métodos. Um usuário delegado precisa ser referenciado pelo endereço de e-mail principal.
  • settings.delegates.create
    • Esse método agora pode ser usado para criar relações de delegação em vários domínios pertencentes à mesma organização do Google Workspace.
    • Esse método agora pode ser usado para usuários que exigem uma mudança de senha no próximo login.
    • Se for bem-sucedido, esse método retornará um settings.delegates recurso no corpo da resposta, em vez de um corpo de resposta vazio.
    • Se um dos usuários delegador ou delegado estiver desativado (por exemplo, suspenso no Google Workspace), esse método falhará com um erro HTTP 4XX em vez de um erro HTTP 500.
  • settings.delegates.delete
    • Esse método agora pode ser usado para excluir delegados com qualquer VerificationStatus, e não apenas delegados que são accepted ou expired.
  • settings.delegates.get

Gerenciar configurações gerais

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