1 \input texinfo @c -*-texinfo-*-
4 @settitle Emacs Sieve Manual
10 * Sieve: (sieve). Managing Sieve scripts in Emacs.
15 @setchapternewpage odd
19 This file documents the Emacs Sieve package.
21 Copyright (C) 2001 Free Software Foundation, Inc.
23 Permission is granted to copy, distribute and/or modify this document
24 under the terms of the GNU Free Documentation License, Version 1.1 or
25 any later version published by the Free Software Foundation; with no
26 Invariant Sections, with the Front-Cover texts being ``A GNU
27 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
28 license is included in the section entitled ``GNU Free Documentation
29 License'' in the Emacs manual.
31 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
32 this GNU Manual, like GNU software. Copies published by the Free
33 Software Foundation raise funds for GNU development.''
35 This document is part of a collection distributed under the GNU Free
36 Documentation License. If you want to distribute this document
37 separately from the collection, you can do so by adding a copy of the
38 license to the document, as described in section 6 of the license.
44 @title Emacs Sieve Manual
46 @author by Simon Josefsson
49 @vskip 0pt plus 1filll
50 Copyright @copyright{} 2001 Free Software Foundation, Inc.
52 Permission is granted to copy, distribute and/or modify this document
53 under the terms of the GNU Free Documentation License, Version 1.1 or
54 any later version published by the Free Software Foundation; with the
55 Invariant Sections being none, with the Front-Cover texts being ``A GNU
56 Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
57 license is included in the section entitled ``GNU Free Documentation
58 License'' in the Emacs manual.
60 (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
61 this GNU Manual, like GNU software. Copies published by the Free
62 Software Foundation raise funds for GNU development.''
64 This document is part of a collection distributed under the GNU Free
65 Documentation License. If you want to distribute this document
66 separately from the collection, you can do so by adding a copy of the
67 license to the document, as described in section 6 of the license.
74 @top Sieve Support for Emacs
76 This manual documents the Emacs Sieve package.
78 It is intended as a users manual for Sieve Mode and Manage Sieve, and
79 as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
82 Sieve is a language for server-side filtering of mail. The language
83 is documented in RFC 3028. This manual does not attempt to document
84 the language, so keep RFC 3028 around.
86 A good online Sieve resources is @uref{http://www.cyrusoft.com/sieve/}.
89 * Installation:: Getting ready to use the package.
90 * Sieve Mode:: Editing Sieve scripts.
91 * Managing Sieve:: Managing Sieve scripts on a remote server.
92 * Examples :: A few Sieve code snippets.
93 * Manage Sieve API :: Interfacing to the Manage Sieve Protocol API.
94 * Standards:: A summary of RFCs and working documents used.
95 * Index:: Function and variable index.
100 @chapter Installation
104 The Sieve package should come with your Emacs version, and should be
105 ready for use directly.
107 However, to manually set up the package you can put the following
108 commands in your @code{~/.emacs}:
111 (autoload 'sieve-mode "sieve-mode")
114 (setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
122 Sieve mode provides syntax-based indentation, font-locking support and
123 other handy functions to make editing Sieve scripts easier.
125 Use @samp{M-x sieve-mode} to switch to this major mode. This command
126 runs the hook @code{sieve-mode-hook}.
128 @vindex sieve-mode-map
129 @vindex sieve-mode-syntax-table
130 Sieve mode is derived from @code{c-mode}, and is very similar except
131 for the syntax of comments. The keymap (@code{sieve-mode-map}) is
132 inherited from @code{c-mode}, as are the variables for customizing
133 indentation. Sieve mode has its own abbrev table
134 (@code{sieve-mode-abbrev-table}) and syntax table
135 (@code{sieve-mode-syntax-table}).
137 In addition to the editing utility functions, Sieve mode also contains
138 bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
145 @cindex manage remote sieve script
146 Open a connection to a remote server using the Managesieve protocol.
151 @cindex upload sieve script
152 Upload the Sieve script to the currently open server.
158 @chapter Managing Sieve
160 Manage Sieve is a special mode used to display Sieve scripts available
161 on a remote server. It can be invoked with @kbd{M-x sieve-manage
162 RET}, which queries the user for a server and if necessary, user
165 When a server has been successfully contacted, the Manage Sieve buffer
166 looks something like:
169 Server : mailserver:2000
171 2 scripts on server, press RET on a script name edits it, or
172 press RET on <new script> to create a new script.
178 One of the scripts are highlighted, and standard point navigation
179 commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
182 The following commands are available in the Manage Sieve buffer:
188 @findex sieve-activate
189 Activates the currently highlighted script.
193 @findex sieve-deactivate
194 Deactivates the currently highlighted script.
198 @findex sieve-deactivate-all
199 Deactivates all scripts.
204 Remove currently highlighted script.
212 @findex sieve-edit-script
213 Bury the server buffer and download the currently highlighted script
214 into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
218 @findex sieve-edit-script-other-window
219 Create a new buffer in another window containing the currently
220 highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
224 @findex sieve-bury-buffer
225 Bury the Manage Sieve buffer without closing the connection.
232 Displays help in the minibuffer.
239 If you are not familiar with Sieve, this chapter contains a few simple
240 code snippets that you can cut'n'paste and modify at will, until you
241 feel more comfortable with the Sieve language to write the rules from
244 The following complete Sieve script places all messages with a matching
245 @samp{Sender:} header into the given mailbox. Many mailing lists uses
246 this format. The first line makes sure your Sieve server understands
247 the @code{fileinto} command.
252 if address "sender" "owner-w3-beta@@xemacs.org" @{
253 fileinto "INBOX.w3-beta";
257 A few mailing lists do not use the @samp{Sender:} header, but does
258 contain some unique identifier in some other header. The following is
259 not a complete script, it assumes that @code{fileinto} has already been
263 if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
264 fileinto "INBOX.auc-tex";
268 At last, we have the hopeless mailing lists that does not have any
269 unique identifier and you are forced to match on the @samp{To:} and
270 @samp{Cc} headers. As before, this snippet assumes that @code{fileinto}
274 if address ["to", "cc"] "kerberos@@mit.edu" @{
275 fileinto "INBOX.kerberos";
279 @node Manage Sieve API
280 @chapter Manage Sieve API
282 The @file{sieve-manage.el} library contains low-level functionality
283 for talking to a server with the @sc{managesieve} protocol.
285 A number of user-visible variables exist, which all can be customized
286 in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
290 @item sieve-manage-default-user
291 @vindex sieve-manage-default-user
292 Sets the default username.
294 @item sieve-manage-default-port
295 @vindex sieve-manage-default-port
296 Sets the default port to use, the suggested port number is @code{2000}.
298 @item sieve-manage-log
299 @vindex sieve-manage-log
300 If non-@code{nil}, should be a string naming a buffer where a protocol trace
301 is dumped (for debugging purposes).
305 The API functions include:
309 @item sieve-manage-open
310 @findex sieve-manage-open
311 Open connection to managesieve server, returning a buffer to be used
312 by all other API functions.
314 @item sieve-manage-opened
315 @findex sieve-manage-opened
316 Check if a server is open or not.
318 @item sieve-manage-close
319 @findex sieve-manage-close
320 Close a server connection.
322 @item sieve-manage-authenticate
323 @findex sieve-manage-authenticate
324 Authenticate to the server.
326 @item sieve-manage-capability
327 @findex sieve-manage-capability
328 Return a list of capabilities the server support.
330 @item sieve-manage-listscripts
331 @findex sieve-manage-listscripts
332 List scripts on the server.
334 @item sieve-manage-havespace
335 @findex sieve-manage-havespace
336 Returns non-@code{nil} iff server have roam for a script of given
339 @item sieve-manage-getscript
340 @findex sieve-manage-getscript
341 Download script from server.
343 @item sieve-manage-putscript
344 @findex sieve-manage-putscript
345 Upload script to server.
347 @item sieve-manage-setactive
348 @findex sieve-manage-setactive
349 Indicate which script on the server should be active.
356 The Emacs Sieve package implements all or parts of a small but
357 hopefully growing number of RFCs and drafts documents. This chapter
358 lists the relevant ones. They can all be fetched from
359 @uref{http://quimby.gnus.org/notes/}.
364 Sieve: A Mail Filtering Language.
366 @item draft-martin-managesieve-03
367 A Protocol for Remotely Managing Sieve Scripts