Estensioni IMAP

Questo documento descrive le estensioni IMAP fornite da Gmail e come gli sviluppatori possono utilizzarle. Questo documento presuppone la conoscenza del protocollo IMAP.

Panoramica

Gmail fornisce un insieme di estensioni IMAP per consentire agli autori di client IMAP di offrire un'esperienza più simile a Gmail tramite IMAP. Gli sviluppatori che integrano le funzionalità di Gmail nelle proprie app web o mobile potrebbero invece voler utilizzare l'API Gmail RESTful.

Puoi utilizzare le estensioni quando accedi a Gmail tramite il protocollo IMAP standard o quando ti connetti con OAuth.

Controllo della presenza di estensioni

Gmail pubblicizza il supporto delle estensioni nella sua risposta al comando CAPABILITY. La presenza di X-GM-EXT-1 nell'elenco delle funzionalità supportate indica il supporto delle estensioni descritte in questo documento.

Consigliamo vivamente ai client di annunciarsi con il comando IMAP ID (RFC 2971) e di includere un indirizzo di contatto di riserva nel caso in cui siano necessarie modifiche a queste estensioni.

Di seguito è riportato un esempio di handshake e 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 usi speciali del comando LIST

Gmail supporta l'estensione IMAP LIST per le caselle di posta per uso speciale, che fornisce nuovi attributi per le cartelle speciali. Questi attributi consentono al client di sapere quali cartelle sono speciali, ad esempio \All. L'elenco attuale delle cartelle speciali è composto da: Speciali, Importanti, Posta inviata, Bozze, Spam, Tutti i messaggi e Cestino. Tutte le risposte LIST contengono questi attributi di uso speciale; non si tratta di un nuovo CAPABILITY o di qualcosa che i client devono attivare.

Di seguito è riportata la 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 segue lo standard Special-Use con un attributo \Important aggiuntivo aggiunto per la Posta prioritaria di Gmail (ovvero "[Gmail]/Important").

XLIST è deprecato

Il comando XLIST specifico di Gmail è stato ritirato nel 2013 a favore dello standard per l'elenco di cartelle IMAP con uso speciale. Invitiamo vivamente i clienti a eseguire la migrazione da XLIST allo standard di settore Special-Use il prima possibile. Tieni presente che i nomi degli attributi standard per usi speciali sono simili, ma non identici, ai nomi degli attributi legacy XLIST.

Estensione del comando SEARCH: X-GM-RAW

Per fornire l'accesso alla sintassi completa della ricerca di Gmail, 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 vengono interpretati nello stesso modo dell'interfaccia web di Gmail.

Di seguito è riportata la trascrizione di esempio di una chiamata a SEARCH utilizzando 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 tu possa identificare un messaggio univoco in più cartelle. Puoi recuperare questo ID messaggio utilizzando l'attributo X-GM-MSGID nel comando FETCH. L'ID messaggio è un intero senza segno a 64 bit ed è l'equivalente decimale della 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)

Puoi anche utilizzare l'attributo X-GM-MSGID nei comandi SEARCH o UID SEARCH per trovare i numeri di sequenza o UID di un messaggio dato l'ID messaggio di Gmail. Di seguito è riportata la trascrizione di esempio di una chiamata per recuperare l'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 nello stesso modo dell'interfaccia web di Gmail. Puoi recuperare questo ID thread utilizzando l'attributo X-GM-THRID nel comando FETCH. L'ID thread è un numero intero senza segno a 64 bit ed è l'equivalente decimale della stringa esadecimale dell'ID utilizzata nell'interfaccia web e nell'API Gmail.

Di seguito è riportata la trascrizione di esempio di una chiamata per recuperare 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)

Puoi anche utilizzare l'attributo X-GM-THRID nei comandi SEARCH o UID SEARCH per trovare i numeri di sequenza o gli UID dei messaggi in un determinato thread. Di seguito è riportata la trascrizione di esempio di una chiamata per recuperare gli 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 Gmail: X-GM-LABELS

Ai fini di IMAP, Gmail considera le etichette come cartelle. Pertanto, puoi modificare le etichette utilizzando i comandi IMAP standard che agiscono sulle cartelle: CREATE, RENAME e DELETE. Le etichette di sistema, create da Gmail, sono riservate e hanno come prefisso "[Gmail]" o "[GoogleMail]" nell'elenco delle etichette. Utilizza il comando LIST per ottenere l'intero elenco delle etichette per una casella di posta.

Puoi recuperare le etichette per un determinato messaggio utilizzando l'attributo X-GM-LABELS con il comando FETCH. L'attributo viene restituito come elenco di ASTRING, codificati in UTF-7, se necessario. Un ASTRING è un atomo o una stringa come definito dalla RFC.

Di seguito è riportata la trascrizione di esempio di una chiamata per recuperare 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)

Puoi 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 come aggiungere 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)

Puoi anche utilizzare l'attributo X-GM-LABELS nei comandi SEARCH o UID SEARCH per trovare i numeri di sequenza o gli UID di tutti i messaggi nella cartella con una determinata etichetta. Di seguito è riportata la 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