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 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 são limitadas a um usuário individual, e não a 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 que estão 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 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 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 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.
o 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 a adição de um marcador de usuário ainda não existir, ela precisará ser criada 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 SendAs.

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

Como gerenciar clipes da Web

As configurações de 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.

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 Configurações.

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 SendAs.

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

Outras mudanças:

  • Agora as assinaturas são gerenciadas 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

Consulte o guia de gerenciamento das 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 delegador precisa estar ativado para o Gmail. Isso significa, por exemplo, que o usuário delegante não pode ser suspenso no.
    • 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 indicado 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 da mesma organização .
    • Agora, esse método pode ser usado para usuários que precisam mudar a senha no próximo login.
    • Se for bem-sucedido, esse método vai retornar um recurso Users.settings.delegates 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 ), 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, e não apenas delegados que são accepted ou expired.
  • delegates.get
    • Esse é um novo método que pode ser preferível 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.