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 UID
s das mensagens em uma determinada linha de execução. Confira a seguir um exemplo de transcrição de uma chamada para recuperar os UID
s 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 ASTRING
s, 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 UID
s 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
- IMAP: RFC 3501: PROTOCOLO DE ACESSO A MENSAGENS DE INTERNET - VERSÃO 4rev1
- ID do IMAP: RFC 2971: IMAP4 ID EXTENSION
- Uso especial do IMAP: RFC 6154: extensão LIST do IMAP para caixas de correio de uso especial