File: imap.el.html
imap.el is an elisp library providing an interface for talking to IMAP servers.
imap.el is roughly divided in two parts, one that parses IMAP responses from the server and storing data into buffer-local variables, and one for utility functions which send commands to server, waits for an answer, and return information. The latter part is layered on top of the previous.
The imap.el API consist of the following functions, other functions in this file should not be called directly and the result of doing so are at best undefined.
Global commands:
imap-open, imap-opened, imap-authenticate, imap-close,
imap-capability, imap-namespace, imap-error-text
Mailbox commands:
imap-mailbox-get, imap-mailbox-map, imap-current-mailbox,
imap-current-mailbox-p, imap-search, imap-mailbox-select,
imap-mailbox-examine, imap-mailbox-unselect, imap-mailbox-expunge
imap-mailbox-close, imap-mailbox-create, imap-mailbox-delete
imap-mailbox-rename, imap-mailbox-lsub, imap-mailbox-list
imap-mailbox-subscribe, imap-mailbox-unsubscribe, imap-mailbox-status
imap-mailbox-acl-get, imap-mailbox-acl-set, imap-mailbox-acl-delete
Message commands:
imap-fetch-asynch, imap-fetch,
imap-current-message, imap-list-to-message-set,
imap-message-get, imap-message-map
imap-message-envelope-date, imap-message-envelope-subject,
imap-message-envelope-from, imap-message-envelope-sender,
imap-message-envelope-reply-to, imap-message-envelope-to,
imap-message-envelope-cc, imap-message-envelope-bcc
imap-message-envelope-in-reply-to, imap-message-envelope-message-id
imap-message-body, imap-message-flag-permanent-p
imap-message-flags-set, imap-message-flags-del
imap-message-flags-add, imap-message-copyuid
imap-message-copy, imap-message-appenduid
imap-message-append, imap-envelope-from
imap-body-lines
It is my hope that these commands should be pretty self explanatory for someone who knows IMAP. All functions have additional documentation on how to invoke them.
imap.el supports RFC1730/2060/RFC3501 (IMAP4/IMAP4rev1). The implemented
IMAP extensions are RFC2195 (CRAM-MD5), RFC2086 (ACL), RFC2342
(NAMESPACE), RFC2359 (UIDPLUS), the IMAP-part of RFC2595 (STARTTLS,
LOGINDISABLED), and the GSSAPI / Kerberos V4 sections of RFC1731
(with use of external program imtest), and RFC2971 (ID). It also
takes advantage of the UNSELECT extension in Cyrus IMAPD.
Without the work of John McClary Prevost and Jim Radford this library would not have seen the light of day. Many thanks.
This is a transcript of a short interactive session for demonstration purposes.
(imap-open "my.mail.server")
=> " *imap* my.mail.server:0"
The rest are invoked with current buffer as the buffer returned by
imap-open. It is possible to do it all without this, but it would
look ugly here since buffer is always the last argument for all
imap.el API functions.
(imap-authenticate "myusername" "mypassword")
=> auth
(imap-mailbox-lsub "*")
=> ("INBOX.sentmail" "INBOX.private" "INBOX.draft" "INBOX.spam")
(imap-mailbox-list "INBOX.n%")
=> ("INBOX.namedroppers" "INBOX.nnimap" "INBOX.ntbugtraq")
(imap-mailbox-select "INBOX.nnimap")
=> "INBOX.nnimap"
(imap-mailbox-get 'exists)
=> 166
(imap-mailbox-get 'uidvalidity)
=> "908992622"
(imap-search "FLAGGED SINCE 18-DEC-98")
=> (235 236)
(imap-fetch 235 "RFC822.PEEK" 'RFC822)
=> "X-Sieve: cmu-sieve 1.3^M\\nX-Username: <jas@pdc.kth.se>^M\\r...."
Todo:
o Parse UIDs as strings? We need to overcome the 28 bit limit somehow.
Use IEEE floats (which are effectively exact)? -- fx
o Don't use read at all (important places already fixed)
o Accept list of articles instead of message set string in most
imap-message-* functions.
o Send strings as literal if they contain, e.g., ".
Revision history:
- 19991218 added starttls/digest-md5 patch,
by Daiki Ueno <ueno@ueda.info.waseda.ac.jp>
NB! you need SLIM for starttls.el and digest-md5.el
- 19991023 committed to pgnus
Defined variables (39)
imap-authenticator-alist | Definition of authenticators. |
imap-authenticators | Priority of authenticators to consider when authenticating to server. |
imap-callbacks | List of response tags and callbacks, on the form ‘(number . function)’. |
imap-capability | Capability for server. |
imap-client-eol | The EOL string we send to the server. |
imap-continuation | Non-nil indicates that the server emitted a continuation request. |
imap-current-mailbox | Current mailbox name. |
imap-current-message | Current message number. |
imap-current-target-mailbox | Current target mailbox for COPY and APPEND commands. |
imap-debug | If non-nil, trace imap- functions into ‘imap-debug-buffer’. |
imap-default-user | Default username to use. |
imap-enable-exchange-bug-workaround | Send FETCH UID commands as *:* instead of *. |
imap-error | Error codes from the last command. |
imap-failed-tags | Alist of tags that failed. |
imap-fetch-data-hook | Hooks called after receiving each FETCH response. |
imap-gssapi-program | List of strings containing commands for GSSAPI (krb5) authentication. |
imap-id | Identity of server. |
imap-kerberos4-program | List of strings containing commands for Kerberos 4 authentication. |
imap-log | If non-nil, an imap session trace is placed in ‘imap-log-buffer’. |
imap-logout-timeout | Close server immediately if it can’t logout in this number of seconds. |
imap-mailbox-data | Obarray with mailbox data. |
imap-mailbox-prime | Length of ‘imap-mailbox-data’. |
imap-message-data | Obarray with message data. |
imap-message-prime | Length of ‘imap-message-data’. |
imap-namespace | Namespace for current server. |
imap-ping-server | If non-nil, check if IMAP is open. |
imap-process | Process. |
imap-process-connection-type | Value for ‘process-connection-type’ to use for Kerberos4, GSSAPI, shell and SSL. |
imap-reached-tag | Lower limit on command tags that have been parsed. |
imap-read-timeout | How long to wait between checking for the end of output. |
imap-server-eol | The EOL string sent from the server. |
imap-shell-host | Hostname of rlogin proxy. |
imap-shell-program | A list of strings, containing commands for IMAP connection. |
imap-state | IMAP state. |
imap-store-password | If non-nil, store session password without prompting. |
imap-stream-alist | Definition of network streams. |
imap-streams | Priority of streams to consider when opening connection to server. |
imap-tag | Command tag number. |
imap-use-utf7 | If non-nil, do utf7 encoding/decoding of mailbox names. |
Defined functions (119)
imap-add-callback | (TAG FUNC) |
imap-anonymous-auth | (BUFFER) |
imap-anonymous-p | (BUFFER) |
imap-arrival-filter | (PROC STRING) |
imap-authenticate | (&optional USER PASSWD BUFFER) |
imap-body-lines | (BODY) |
imap-capability | (&optional IDENTIFIER BUFFER) |
imap-close | (&optional BUFFER) |
imap-cram-md5-auth | (BUFFER) |
imap-cram-md5-p | (BUFFER) |
imap-current-mailbox | (&optional BUFFER) |
imap-current-mailbox-p | (MAILBOX &optional EXAMINE BUFFER) |
imap-current-mailbox-p-1 | (MAILBOX &optional EXAMINE) |
imap-current-message | (&optional BUFFER) |
imap-digest-md5-auth | (BUFFER) |
imap-digest-md5-p | (BUFFER) |
imap-disable-multibyte | () |
imap-envelope-from | (FROM) |
imap-error-text | (&optional BUFFER) |
imap-fetch | (UIDS PROPS &optional RECEIVE NOUIDFETCH BUFFER) |
imap-fetch-asynch | (UIDS PROPS &optional NOUIDFETCH BUFFER) |
imap-fetch-safe | (UIDS PROPS &optional RECEIVE NOUIDFETCH BUFFER) |
imap-find-next-line | () |
imap-gssapi-auth | (BUFFER) |
imap-gssapi-auth-p | (BUFFER) |
imap-gssapi-open | (NAME BUFFER SERVER PORT) |
imap-gssapi-stream-p | (BUFFER) |
imap-id | (&optional LIST-OF-VALUES BUFFER) |
imap-interactive-login | (BUFFER LOGINFUNC) |
imap-kerberos4-auth | (BUFFER) |
imap-kerberos4-auth-p | (BUFFER) |
imap-kerberos4-open | (NAME BUFFER SERVER PORT) |
imap-kerberos4-stream-p | (BUFFER) |
imap-list-to-message-set | (LIST) |
imap-log | (STRING-OR-BUFFER) |
imap-login-auth | (BUFFER) |
imap-login-p | (BUFFER) |
imap-logout | (&optional BUFFER) |
imap-logout-wait | (&optional BUFFER) |
imap-mailbox-acl-delete | (IDENTIFIER &optional MAILBOX BUFFER) |
imap-mailbox-acl-get | (&optional MAILBOX BUFFER) |
imap-mailbox-acl-set | (IDENTIFIER RIGHTS &optional MAILBOX BUFFER) |
imap-mailbox-close | (&optional ASYNCH BUFFER) |
imap-mailbox-create | (MAILBOX &optional BUFFER) |
imap-mailbox-create-1 | (MAILBOX) |
imap-mailbox-delete | (MAILBOX &optional BUFFER) |
imap-mailbox-examine | (MAILBOX &optional BUFFER) |
imap-mailbox-examine-1 | (MAILBOX &optional BUFFER) |
imap-mailbox-expunge | (&optional ASYNCH BUFFER) |
imap-mailbox-get | (PROPNAME &optional MAILBOX BUFFER) |
imap-mailbox-get-1 | (PROPNAME &optional MAILBOX) |
imap-mailbox-list | (ROOT &optional REFERENCE ADD-DELIMITER BUFFER) |
imap-mailbox-lsub | (&optional ROOT REFERENCE ADD-DELIMITER BUFFER) |
imap-mailbox-map | (FUNC &optional BUFFER) |
imap-mailbox-map-1 | (FUNC &optional MAILBOX-DECODER BUFFER) |
imap-mailbox-put | (PROPNAME VALUE &optional MAILBOX BUFFER) |
imap-mailbox-rename | (OLDNAME NEWNAME &optional BUFFER) |
imap-mailbox-select | (MAILBOX &optional EXAMINE BUFFER) |
imap-mailbox-select-1 | (MAILBOX &optional EXAMINE) |
imap-mailbox-status | (MAILBOX ITEMS &optional BUFFER) |
imap-mailbox-status-asynch | (MAILBOX ITEMS &optional BUFFER) |
imap-mailbox-subscribe | (MAILBOX &optional BUFFER) |
imap-mailbox-unselect | (&optional BUFFER) |
imap-mailbox-unsubscribe | (MAILBOX &optional BUFFER) |
imap-message-append | (MAILBOX ARTICLE &optional FLAGS DATE-TIME BUFFER) |
imap-message-appenduid | (MAILBOX &optional BUFFER) |
imap-message-appenduid-1 | (MAILBOX) |
imap-message-body | (UID &optional BUFFER) |
imap-message-copy | (ARTICLES MAILBOX &optional DONT-CREATE NO-COPYUID BUFFER) |
imap-message-copyuid | (MAILBOX &optional BUFFER) |
imap-message-copyuid-1 | (MAILBOX) |
imap-message-envelope-bcc | (UID &optional BUFFER) |
imap-message-envelope-cc | (UID &optional BUFFER) |
imap-message-envelope-date | (UID &optional BUFFER) |
imap-message-envelope-from | (UID &optional BUFFER) |
imap-message-envelope-in-reply-to | (UID &optional BUFFER) |
imap-message-envelope-message-id | (UID &optional BUFFER) |
imap-message-envelope-reply-to | (UID &optional BUFFER) |
imap-message-envelope-sender | (UID &optional BUFFER) |
imap-message-envelope-subject | (UID &optional BUFFER) |
imap-message-envelope-to | (UID &optional BUFFER) |
imap-message-flag-permanent-p | (FLAG &optional MAILBOX BUFFER) |
imap-message-flags-add | (ARTICLES FLAGS &optional SILENT BUFFER) |
imap-message-flags-del | (ARTICLES FLAGS &optional SILENT BUFFER) |
imap-message-flags-set | (ARTICLES FLAGS &optional SILENT BUFFER) |
imap-message-get | (UID PROPNAME &optional BUFFER) |
imap-message-map | (FUNC PROPNAME &optional BUFFER) |
imap-message-put | (UID PROPNAME VALUE &optional BUFFER) |
imap-namespace | (&optional BUFFER) |
imap-network-open | (NAME BUFFER SERVER PORT) |
imap-network-p | (BUFFER) |
imap-ok-p | (STATUS) |
imap-open | (SERVER &optional PORT STREAM AUTH BUFFER) |
imap-open-1 | (BUFFER) |
imap-opened | (&optional BUFFER) |
imap-parse-data-list | (TYPE) |
imap-parse-greeting | () |
imap-parse-response | () |
imap-ping-server | (&optional BUFFER) |
imap-quote-specials | (STRING) |
imap-range-to-message-set | (RANGE) |
imap-remassoc | (KEY ALIST) |
imap-sasl-auth | (BUFFER) |
imap-sasl-auth-p | (BUFFER) |
imap-sasl-make-mechanisms | (BUFFER) |
imap-search | (PREDICATE &optional BUFFER) |
imap-send-command | (COMMAND &optional BUFFER) |
imap-send-command-1 | (CMDSTR) |
imap-send-command-wait | (COMMAND &optional BUFFER) |
imap-sentinel | (PROCESS STRING) |
imap-shell-open | (NAME BUFFER SERVER PORT) |
imap-shell-p | (BUFFER) |
imap-starttls-open | (NAME BUFFER SERVER PORT) |
imap-starttls-p | (BUFFER) |
imap-tls-open | (NAME BUFFER SERVER PORT) |
imap-tls-p | (BUFFER) |
imap-utf7-decode | (STRING) |
imap-utf7-encode | (STRING) |
imap-wait-for-tag | (TAG &optional BUFFER) |