Questo documento descrive le estensioni IMAP fornite da Gmail e il modo in cui possono essere utilizzate dagli sviluppatori. Questo documento presuppone la conoscenza del protocollo IMAP.
Panoramica
Gmail fornisce un insieme di estensioni IMAP per consentire agli autori dei client IMAP di offrire un'esperienza più simile a quella di Gmail tramite IMAP. Gli sviluppatori che integrano le funzionalità di Gmail nelle loro app web o mobile possono utilizzare l'API Gmail RESTful.
Le estensioni possono essere utilizzate per accedere a Gmail mediante il protocollo IMAP standard o per la connessione tramite OAuth.
Verifica della presenza di estensioni
Gmail pubblicizza il supporto delle proprie estensioni nella risposta al comando CAPABILITY
. Il supporto delle estensioni in questo documento è indicato dalla presenza di X-GM-EXT-1
nell'elenco delle funzionalità supportate.
Consigliamo vivamente ai client di annunciare il comando ID IMAP (RFC 2971) e di includere un indirizzo di contatto come riserva nel caso in cui siano necessarie modifiche a queste estensioni.
Di seguito è riportato un esempio di handshake e di utilizzo del comando CAPABILITY
sull'endpoint IMAP di 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
Estensione per uso speciale del comando LIST
Gmail supporta l'estensione IMAP LIST per caselle di posta a uso speciale, che fornisce nuovi attributi per cartelle speciali. Questi attributi consentono al client di sapere quali cartelle sono speciali (ad es. \All
). L'elenco attuale di cartelle speciali è composto da: Speciali, Importanti, Posta inviata, Bozze, Spam, Tutti i messaggi e Cestino. Tutte le risposte LIST
contengono questi attributi per uso speciale; questa non è una nuova CAPABILITY
o un elemento che deve essere ENABLEd
dai clienti.
Di seguito è riportata una trascrizione di esempio di una chiamata a 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
La risposta è conforme allo standard per l'uso speciale, con l'aggiunta di un attributo \Important
aggiuntivo per la Posta prioritaria di Gmail (ad esempio, "[Gmail]/Important"
).
XLIST è deprecato
Il comando XLIST
specifico per Gmail è stato ritirato nel 2013 in favore di IMAP Special-Use List Standard. Consigliamo vivamente ai clienti di passare da XLIST
allo standard di settore per l'uso speciale il prima possibile. Tieni presente che i nomi degli attributi standard per uso speciale sono simili, ma non identici, ai nomi degli attributi XLIST
precedenti.
Estensione del comando SEARCH: X-GM-RAW
Per consentire l'accesso alla sintassi di ricerca completa, Gmail fornisce l'attributo di ricerca X-GM-RAW
. Gli argomenti passati con l'attributo X-GM-RAW
durante l'esecuzione dei comandi SEARCH
o UID SEARCH
verranno interpretati come nell'interfaccia web di Gmail.
Di seguito è riportata una trascrizione di esempio di una chiamata a SEARCH
mediante l'attributo X-GM-RAW
:
a005 SEARCH X-GM-RAW "has:attachment in:unread"
* SEARCH 123 12344 5992
a005 OK SEARCH (Success)
Accesso all'ID messaggio univoco di Gmail: X-GM-MSGID
Gmail fornisce un ID messaggio univoco per ogni email, in modo che un messaggio univoco possa essere identificato in più cartelle. Il recupero di questo ID messaggio è supportato tramite l'attributo X-GM-MSGID
nel comando FETCH
. L'ID messaggio è un numero intero senza segno a 64 bit ed è l'equivalente decimale per la stringa esadecimale dell'ID utilizzata nell'interfaccia web e nell'API Gmail.
Di seguito è riportata una trascrizione di esempio di una chiamata per recuperare il X-GM-MSGID
di un messaggio con il comando FETCH
:
a006 FETCH 1 (X-GM-MSGID)
* 1 FETCH (X-GM-MSGID 1278455344230334865)
a006 OK FETCH (Success)
L'attributo X-GM-MSGID
può essere utilizzato anche nei comandi SEARCH
o UID SEARCH
per trovare i numeri di sequenza o UID
di un messaggio specificato nell'ID messaggio di Gmail. Di seguito è riportata una trascrizione di esempio di una chiamata per recuperare il UID
di un messaggio utilizzando il comando UID SEARCH
:
a007 UID SEARCH X-GM-MSGID 1278455344230334865
* SEARCH 1
a007 OK SEARCH (Success)
Accesso all'ID thread di Gmail: X-GM-THRID
Gmail fornisce un ID thread per associare gruppi di messaggi come nell'interfaccia web di Gmail. Il recupero di questo ID thread è supportato tramite l'attributo X-GM-THRID
nel comando FETCH
. L'ID thread è un numero intero senza segno a 64 bit ed è l'equivalente decimale per la stringa esadecimale ID utilizzata nell'interfaccia web e nell'API Gmail.
Di seguito è riportata una trascrizione di esempio di una chiamata per recuperare il X-GM-THRID
di diversi messaggi (in due thread) con il 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)
L'attributo X-GM-THRID
può essere utilizzato anche nei comandi SEARCH
o UID SEARCH
per trovare i numeri di sequenza o i UID
dei messaggi in un determinato thread. Di seguito è riportata una trascrizione di esempio di una chiamata per recuperare i UID
di diversi messaggi utilizzando il comando UID SEARCH
:
a009 UID SEARCH X-GM-THRID 1266894439832287888
* SEARCH 2 3 4
a009 OK Search (Success)
Accesso alle etichette di Gmail: X-GM-LABELS
Ai fini di IMAP, Gmail considera le etichette come cartelle. Di conseguenza, le etichette possono essere modificate utilizzando i comandi IMAP standard, CREATE
, RENAME
e DELETE
, che agiscono sulle cartelle. Le etichette di sistema, che sono etichette create da Gmail, sono riservate e precedute da "[Gmail]" o "[GoogleMail]" nell'elenco di etichette. Utilizza il comando XLIST
per ottenere l'elenco completo delle etichette di una casella di posta.
Le etichette di un determinato messaggio possono essere recuperate utilizzando l'attributo X-GM-LABELS
con il comando FETCH
. L'attributo viene restituito sotto forma di elenco di ASTRING
, codificato in modo appropriato in UTF-7. Un ASTRING
è un atom o una stringa come definito dalla RFC.
Di seguito è riportata una trascrizione di esempio di una chiamata per recuperare il X-GM-LABELS
di diversi messaggi con il 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)
È possibile aggiungere etichette a un messaggio utilizzando il comando STORE
in combinazione con l'attributo X-GM-LABELS
. Di seguito è riportata una trascrizione di esempio che mostra l'aggiunta di un'etichetta a un messaggio:
a011 STORE 1 +X-GM-LABELS (foo)
* 1 FETCH (X-GM-LABELS (\Inbox \Sent Important "Muy Importante" foo))
a011 OK STORE (Success)
L'attributo X-GM-LABELS
può essere utilizzato anche nei comandi SEARCH
o UID SEARCH
per trovare i numeri di sequenza o i UID
di tutti i messaggi nella cartella con una determinata etichetta. Di seguito è riportata una trascrizione di esempio di una chiamata per recuperare i numeri di sequenza di diversi messaggi utilizzando il comando SEARCH
:
a012 SEARCH X-GM-LABELS foo
* SEARCH 1 2
a012 OK SEARCH (Success)
Riferimenti
- IMAP: RFC 3501: PROTOCOLLO DI ACCESSO AI MESSAGGI INTERNET - VERSIONE 4rev1
- ID IMAP: RFC 2971: ESTENSIONE ID IMAP4
- IMAP Uso speciale: RFC 6154: Estensione IMAP LIST per cassette di posta ad uso speciale