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
ouexpired
.
- Agora, esse método pode ser usado para excluir delegados com qualquer
verificationStatus,
em vez de apenas delegados que são
- 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.