Extensões IMAP

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 UIDs de mensagens em uma determinada linha de execução. Confira a seguir um exemplo de transcrição de uma chamada para recuperar as 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 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 ASTRINGs, 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 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