Este documento descreve as extensões IMAP fornecidas pelo Gmail e como elas podem ser usadas pelos desenvolvedores. Este documento pressupõe familiaridade com o protocolo IMAP.
Informações gerais
O Gmail fornece um conjunto de extensões IMAP para permitir que os autores de clientes IMAP proporcionem uma experiência mais similar ao Gmail através do IMAP. Os desenvolvedores que integram recursos do Gmail aos apps da Web ou para dispositivos móveis podem usar a API Gmail RESTful.
As extensões podem ser usadas ao acessar o Gmail pelo protocolo IMAP padrão ou ao se conectar via OAuth.
Verificar a presença de extensões
O Gmail anuncia o suporte à extensão na resposta ao comando CAPABILITY
. O suporte às extensões neste documento é indicado pela presença de X-GM-EXT-1
na lista de recursos compatíveis.
É altamente recomendável que os clientes se anunciem com o comando de ID IMAP (RFC 2971) e incluam um endereço de contato como substituto caso seja necessário fazer alterações nessas extensões.
Confira a seguir um exemplo de handshake e uso do comando CAPABILITY
no endpoint IMAP do Gmail:
* OK Gimap ready for requests from 127.0.0.1 k2if6111336rvb.0
a001 LOGIN username@gmail.com password
a001 OK username@gmail.com authenticated (Success)
a001 OK Login successful
a002 CAPABILITY
* CAPABILITY IMAP4rev1 UNSELECT LITERAL+ IDLE NAMESPACE QUOTA ID XLIST CHILDREN X-GM-EXT-1
a002 OK Success
a003 ID ("name" "clientname" "version" "1.2.3" "vendor" "companyname" "contact" "foo@example.com")
* ID ("name" "GImap" "vendor" "Google, Inc." "support-url" "http://mail.google.com/support" "remote-host" "127.0.0.1")
a003 OK Success
Extensão de uso especial do comando LIST
O Gmail é compatível com a Extensão IMAP LIST para caixas de e-mails de uso especial, que fornece novos atributos para pastas especiais. Esses atributos permitem que o cliente saiba quais pastas são especiais (por exemplo, \All
). A lista atual de pastas especiais consiste em: "Com estrela", "Importante", "Itens Enviados", "Rascunhos", "Spam", "Todos os e-mails" e "Lixeira". Todas as respostas de LIST
contêm esses atributos de uso especial. Ele não é um novo CAPABILITY
ou algo que precisa ser ENABLEd
pelos clientes.
Confira a seguir um exemplo de transcrição de uma chamada para LIST
:
a004 LIST "" "*"
* LIST (\HasNoChildren) "/" "INBOX"
* LIST (\Noselect \HasChildren) "/" "[Gmail]"
* LIST (\HasNoChildren \All) "/" "[Gmail]/All Mail"
* LIST (\HasNoChildren \Drafts) "/" "[Gmail]/Drafts"
* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important"
* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail"
* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam"
* LIST (\HasNoChildren \Flagged) "/" "[Gmail]/Starred"
* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash"
a004 OK Success
A resposta segue o padrão de Uso Especial com um atributo \Important
adicional na Caixa prioritária do Gmail (por exemplo, "[Gmail]/Important"
).
O uso de XLIST foi descontinuado.
O comando XLIST
específico do Gmail foi descontinuado em 2013 e substituído pelo Padrão de lista de uso especial do IMAP. Recomendamos que os clientes migrem do XLIST
para o padrão do setor de uso especial assim que possível. Os nomes dos atributos padrão de uso especial são semelhantes, mas não idênticos, aos nomes dos atributos XLIST
legados.
Extensão do comando SEARCH: X-GM-RAW
Para ter acesso à sintaxe de pesquisa completa do Gmail, o Gmail fornece o atributo de pesquisa X-GM-RAW
. Os argumentos transmitidos com o atributo X-GM-RAW
ao executar os comandos SEARCH
ou UID SEARCH
serão interpretados da mesma maneira que na interface da Web do Gmail.
Confira a seguir um exemplo de transcrição de uma chamada para SEARCH
usando o atributo X-GM-RAW
:
a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)
Acesso ao ID exclusivo da mensagem do Gmail: X-GM-MSGID
O Gmail fornece um ID de mensagem exclusivo para cada e-mail, de modo que uma mensagem exclusiva possa ser identificada em várias pastas. É possível recuperar esse ID de mensagem por meio do atributo X-GM-MSGID
no comando FETCH
. O ID da mensagem é um número inteiro não assinado de 64 bits e é o equivalente decimal da string hexadecimal de ID usada na interface da Web e na API Gmail.
Confira a seguir um exemplo de transcrição de uma chamada para recuperar o X-GM-MSGID
de uma mensagem com o comando FETCH
:
a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)
O atributo X-GM-MSGID
também pode ser usado nos comandos SEARCH
ou UID SEARCH
para encontrar os números de sequência ou o UID
de uma mensagem com o ID de mensagem do Gmail. Confira a seguir um exemplo de transcrição de uma chamada para recuperar o UID
de uma mensagem usando o comando UID SEARCH
:
a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)
Acesso ao ID da conversa do Gmail: X-GM-THRID
O Gmail fornece um ID de conversa para associar grupos de mensagens da mesma forma que na interface da Web do Gmail. É possível recuperar esse ID da linha de execução por meio do atributo X-GM-THRID
no comando FETCH
. O ID da conversa é um número inteiro não assinado de 64 bits e é o equivalente decimal da string hexadecimal do ID usada na interface da Web e na API Gmail.
Confira a seguir um exemplo de transcrição de uma chamada para recuperar o X-GM-THRID
de várias mensagens (em duas linhas de execução) com o comando FETCH
:
a008 FETCH 1:4 (X-GM-THRID)
* 1 FETCH (X-GM-THRID 1278455344230334865)
* 2 FETCH (X-GM-THRID 1266894439832287888)
* 3 FETCH (X-GM-THRID 1266894439832287888)
* 4 FETCH (X-GM-THRID 1266894439832287888)
a008 OK FETCH (Success)
O atributo X-GM-THRID
também pode ser usado nos comandos SEARCH
ou UID SEARCH
para encontrar os números de sequência ou UID
s de mensagens em uma determinada linha de execução. Confira a seguir um exemplo de transcrição de uma chamada para recuperar as UID
s de várias mensagens usando o comando UID SEARCH
:
a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)
Acesso aos marcadores do Gmail: X-GM-LABELS
O Gmail trata os marcadores como pastas para uso no IMAP. Dessa forma, os marcadores podem ser modificados usando os comandos IMAP padrão, CREATE
, RENAME
e DELETE
, que atuam nas pastas. Marcadores do sistema, que são marcadores criados pelo Gmail, são reservados e têm o prefixo "[Gmail]" ou "[GoogleMail]" na lista de marcadores. Use o comando XLIST
para ver a lista completa de marcadores de uma caixa de e-mails.
Os rótulos de uma determinada mensagem podem ser recuperados usando o atributo X-GM-LABELS
com o comando FETCH
. O atributo é retornado como uma lista de ASTRING
s, codificada em UTF-7 conforme necessário. Um ASTRING
é um atom ou uma string, conforme definido pelo RFC.
Confira a seguir um exemplo de transcrição de uma chamada para recuperar o X-GM-LABELS
de várias mensagens com o comando FETCH
:
a010 FETCH 1:4 (X-GM-LABELS)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante"))
* 2 FETCH (X-GM-LABELS (foo))
* 3 FETCH (X-GM-LABELS ())
* 4 FETCH (X-GM-LABELS (\Drafts))
a010 OK FETCH (Success)
Os rótulos podem ser adicionados a uma mensagem usando o comando STORE
com o atributo X-GM-LABELS
. Confira a seguir um exemplo de transcrição que demonstra a adição de um marcador a uma mensagem:
a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)
O atributo X-GM-LABELS
também pode ser usado nos comandos SEARCH
ou UID SEARCH
para encontrar os números de sequência ou UID
s de todas as mensagens na pasta com um determinado marcador. Confira a seguir um exemplo de transcrição de uma chamada para recuperar os números de sequência de várias mensagens usando o comando SEARCH
:
a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)
Referências
- IMAP: RFC 3501: PROTOCOLO DE ACESSO À MENSAGEM INTERNET - VERSÃO 4rev1
- ID IMAP: RFC 2971: EXTENSÃO DE ID IMAP4
- Uso especial de IMAP: RFC 6154: extensão LISTA IMAP para caixas de e-mails de uso especial