1 \input texinfo @c -*-texinfo-*-
4 @settitle Emacs Sieve Manual
10 This file documents the Emacs Sieve package, for server-side mail filtering.
12 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
13 2009, 2010 Free Software Foundation, Inc.
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
20 and with the Back-Cover Texts as in (a) below. A copy of the license
21 is included in the section entitled ``GNU Free Documentation License''.
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual. Buying copies from the FSF supports it in
25 developing GNU and promoting software freedom.''
31 * Sieve: (sieve). Managing Sieve scripts in Emacs.
36 @setchapternewpage odd
39 @title Emacs Sieve Manual
41 @author by Simon Josefsson
43 @vskip 0pt plus 1filll
51 @top Sieve Support for Emacs
53 This is intended as a users manual for Sieve Mode and Manage Sieve, and
54 as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
57 Sieve is a language for server-side filtering of mail. The language
58 is documented in RFC 3028. This manual does not attempt to document
59 the language, so keep RFC 3028 around.
66 * Installation:: Getting ready to use the package.
67 * Sieve Mode:: Editing Sieve scripts.
68 * Managing Sieve:: Managing Sieve scripts on a remote server.
69 * Examples :: A few Sieve code snippets.
70 * Manage Sieve API :: Interfacing to the Manage Sieve Protocol API.
71 * Standards:: A summary of RFCs and working documents used.
72 * GNU Free Documentation License:: The license for this documentation.
73 * Index:: Function and variable index.
82 The Sieve package should come with your Emacs version, and should be
83 ready for use directly.
85 However, to manually set up the package you can put the following
86 commands in your @code{~/.emacs}:
89 (autoload 'sieve-mode "sieve-mode")
92 (setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
100 Sieve mode provides syntax-based indentation, font-locking support and
101 other handy functions to make editing Sieve scripts easier.
103 Use @samp{M-x sieve-mode} to switch to this major mode. This command
104 runs the hook @code{sieve-mode-hook}.
106 @vindex sieve-mode-map
107 @vindex sieve-mode-syntax-table
108 Sieve mode is derived from @code{c-mode}, and is very similar except
109 for the syntax of comments. The keymap (@code{sieve-mode-map}) is
110 inherited from @code{c-mode}, as are the variables for customizing
111 indentation. Sieve mode has its own abbrev table
112 (@code{sieve-mode-abbrev-table}) and syntax table
113 (@code{sieve-mode-syntax-table}).
115 In addition to the editing utility functions, Sieve mode also contains
116 bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
123 @cindex manage remote sieve script
124 Open a connection to a remote server using the Managesieve protocol.
129 @cindex upload sieve script
130 Upload the Sieve script to the currently open server.
136 @chapter Managing Sieve
138 Manage Sieve is a special mode used to display Sieve scripts available
139 on a remote server. It can be invoked with @kbd{M-x sieve-manage
140 RET}, which queries the user for a server and if necessary, user
143 When a server has been successfully contacted, the Manage Sieve buffer
144 looks something like:
147 Server : mailserver:2000
149 2 scripts on server, press RET on a script name edits it, or
150 press RET on <new script> to create a new script.
156 One of the scripts are highlighted, and standard point navigation
157 commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
160 The following commands are available in the Manage Sieve buffer:
166 @findex sieve-activate
167 Activates the currently highlighted script.
171 @findex sieve-deactivate
172 Deactivates the currently highlighted script.
176 @findex sieve-deactivate-all
177 Deactivates all scripts.
182 Remove currently highlighted script.
190 @findex sieve-edit-script
191 Bury the server buffer and download the currently highlighted script
192 into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
196 @findex sieve-edit-script-other-window
197 Create a new buffer in another window containing the currently
198 highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
202 @findex sieve-bury-buffer
203 Bury the Manage Sieve buffer without closing the connection.
210 Displays help in the minibuffer.
217 If you are not familiar with Sieve, this chapter contains a few simple
218 code snippets that you can cut'n'paste and modify at will, until you
219 feel more comfortable with the Sieve language to write the rules from
222 The following complete Sieve script places all messages with a matching
223 @samp{Sender:} header into the given mailbox. Many mailing lists uses
224 this format. The first line makes sure your Sieve server understands
225 the @code{fileinto} command.
230 if address "sender" "owner-w3-beta@@xemacs.org" @{
231 fileinto "INBOX.w3-beta";
235 A few mailing lists do not use the @samp{Sender:} header, but has a
236 unique identifier in some other header. The following is not a
237 complete script, it assumes that @code{fileinto} has already been
241 if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
242 fileinto "INBOX.auc-tex";
246 At last, we have the hopeless mailing lists that does not have any
247 unique identifier and you are forced to match on the @samp{To:} and
248 @samp{Cc} headers. As before, this snippet assumes that @code{fileinto}
252 if address ["to", "cc"] "kerberos@@mit.edu" @{
253 fileinto "INBOX.kerberos";
257 @node Manage Sieve API
258 @chapter Manage Sieve API
260 The @file{sieve-manage.el} library contains low-level functionality
261 for talking to a server with the @sc{managesieve} protocol.
263 A number of user-visible variables exist, which all can be customized
264 in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
268 @item sieve-manage-default-port
269 @vindex sieve-manage-default-port
270 Sets the default port to use, the suggested port number is @code{2000}.
272 @item sieve-manage-log
273 @vindex sieve-manage-log
274 If non-@code{nil}, should be a string naming a buffer where a protocol trace
275 is dumped (for debugging purposes).
279 The API functions include:
283 @item sieve-manage-open
284 @findex sieve-manage-open
285 Open connection to managesieve server, returning a buffer to be used
286 by all other API functions.
288 @item sieve-manage-opened
289 @findex sieve-manage-opened
290 Check if a server is open or not.
292 @item sieve-manage-close
293 @findex sieve-manage-close
294 Close a server connection.
296 @item sieve-manage-authenticate
297 @findex sieve-manage-authenticate
298 Authenticate to the server.
300 @item sieve-manage-capability
301 @findex sieve-manage-capability
302 Return a list of capabilities the server supports.
304 @item sieve-manage-listscripts
305 @findex sieve-manage-listscripts
306 List scripts on the server.
308 @item sieve-manage-havespace
309 @findex sieve-manage-havespace
310 Return non-@code{nil} if the server has room for a script of given
313 @item sieve-manage-getscript
314 @findex sieve-manage-getscript
315 Download script from server.
317 @item sieve-manage-putscript
318 @findex sieve-manage-putscript
319 Upload script to server.
321 @item sieve-manage-setactive
322 @findex sieve-manage-setactive
323 Indicate which script on the server should be active.
330 The Emacs Sieve package implements all or parts of a small but
331 hopefully growing number of RFCs and drafts documents. This chapter
332 lists the relevant ones. They can all be fetched from
333 @uref{http://quimby.gnus.org/notes/}.
338 Sieve: A Mail Filtering Language.
340 @item draft-martin-managesieve-03
341 A Protocol for Remotely Managing Sieve Scripts
345 @node GNU Free Documentation License
346 @appendix GNU Free Documentation License
347 @include doclicense.texi