Extensões IMAP

Este documento descreve as extensões IMAP fornecidas pelo Gmail e como elas podem ser usadas por desenvolvedores. Este documento pressupõe que você esteja familiarizado com o protocolo IMAP.

Visão geral

O Gmail oferece um conjunto de extensões IMAP para que os criadores de clientes IMAP ofereçam uma experiência mais parecida com o Gmail usando o IMAP. Os desenvolvedores que integram recursos do Gmail aos apps para Web ou 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 a extensões na resposta ao comando CAPABILITY. O suporte a extensões neste documento é indicado pela presença de X-GM-EXT-1 na lista de recursos compatíveis.

Recomendamos que os clientes se anunciem com o comando IMAP ID (RFC 2971) e incluam um endereço de contato como alternativa caso sejam necessárias mudanças 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 oferece novos atributos para pastas especiais. Esses atributos informam ao cliente 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 LIST contêm esses atributos de uso especial. Isso não é um novo CAPABILITY nem algo que precisa ser ENABLEd pelos clientes.

Confira abaixo 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 adicionado à Caixa Prioritária do Gmail (ou seja, "[Gmail]/Important").

O XLIST foi descontinuado

O comando XLIST específico do Gmail foi descontinuado em 2013 em favor do padrão de lista de uso especial do IMAP. Recomendamos que os clientes migrem de XLIST para o padrão do setor de uso especial assim que possível. Os nomes de atributos padrão de uso especial são semelhantes, mas não idênticos aos nomes de atributos legados XLIST.

Extensão do comando SEARCH: X-GM-RAW

Para dar acesso à sintaxe completa de pesquisa do Gmail, o Gmail oferece 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 forma 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 exclusivo para cada e-mail, assim é possível identificar uma mensagem em várias pastas. A recuperação desse ID de mensagem é compatível com o atributo X-GM-MSGID no comando FETCH. O ID da mensagem é um número inteiro sem sinal 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-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 UID de uma mensagem usando o ID dela no 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. A recuperação desse ID de encadeamento é compatível com o atributo X-GM-THRID no comando FETCH. O ID da conversa é um número inteiro sem sinal 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 conversas) 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 UIDs de mensagens em uma determinada conversa. Confira a seguir um exemplo de transcrição de uma chamada para recuperar os UIDs 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 fins de IMAP. Assim, os marcadores podem ser modificados usando os comandos padrão do IMAP, CREATE, RENAME e DELETE, que atuam nas pastas. Os marcadores do sistema, que são criados pelo Gmail, são reservados e prefixados por "[Gmail]" ou "[GoogleMail]" na lista de marcadores. Use o comando XLIST para receber a lista completa de marcadores de uma caixa de correio.

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 ASTRINGs, codificados em UTF-7 conforme apropriado. Um ASTRING é um átomo ou uma string, conforme definido pela 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)

É possível adicionar rótulos a uma mensagem usando o comando STORE em conjunto com o atributo X-GM-LABELS. Confira a seguir um exemplo de transcrição que demonstra a adição de um rótulo 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 UIDs 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