Extensões IMAP

Este documento descreve as extensões IMAP fornecidas pelo Gmail e como elas podem ser usadas por desenvolvedores. Neste documento, presumimos que você já conhece o protocolo IMAP.

Visão geral

O Gmail oferece um conjunto de extensões IMAP para permitir 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 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 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 precise 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 o mais rápido 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