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ê já conhece o protocolo IMAP.

Visão geral

O Gmail fornece um conjunto de extensões do IMAP para permitir que os autores de clientes IMAP proporcionem uma experiência semelhante à do Gmail por meio do IMAP. 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.

Veja a seguir um exemplo de handshake e do uso do comando CAPABILITY no endpoint de 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 fornece 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 (ou seja, "[Gmail]/Important").

O 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 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 de pesquisa completa 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 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 linha de execução do Gmail: X-GM-THRID

O Gmail fornece um ID de linha de conversa para associar grupos de mensagens da mesma forma que na interface da Web. A recuperação desse ID de linha de execução é compatível com o 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 para a 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 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 abaixo um exemplo de transcrição de uma chamada para extrair 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