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 que você conheça o protocolo IMAP.

Visão geral

O Gmail oferece um conjunto de extensões IMAP para que os autores de clientes IMAP ofereçam uma experiência mais semelhante ao Gmail. Os desenvolvedores que integram os recursos do Gmail aos apps da Web ou para dispositivos móveis podem usar a API RESTful do Gmail.

As extensões podem ser usadas ao acessar o Gmail pelo protocolo IMAP padrão ou ao se conectar pelo 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.

É altamente recomendável que os clientes se anunciem com o comando de ID do 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 oferece suporte à Extensão LIST do IMAP 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", "Enviados", "Rascunhos", "Spam", "Todos os e-mails" e "Lixeira". Todas as respostas LIST contêm esses atributos de uso especial. 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 ("[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 o mais rápido 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 fornecer 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 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 de mensagem exclusivo do Gmail: X-GM-MSGID

O Gmail fornece um ID exclusivo para cada e-mail, para que uma mensagem única possa ser identificada em várias pastas. A recuperação desse ID de mensagem é aceita pelo 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 UID de uma mensagem, considerando o ID da 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 linha de transmissão para associar grupos de mensagens da mesma maneira que na interface da Web do Gmail. A recuperação desse ID de linha de execução é aceita pelo atributo X-GM-THRID no comando FETCH. O ID da linha de execução é 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-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 das mensagens em uma determinada linha de execução. 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 IMAP padrão CREATE, RENAME e DELETE, que atuam em pastas. Os rótulos do sistema, que são criados pelo Gmail, são reservados e prefixados por "[Gmail]" ou "[GoogleMail]" na lista de rótulos. Use o comando XLIST para acessar a lista completa de rótulos 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 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)

É possível adicionar rótulos 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 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 rótulo. 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