1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/sieve
3 @settitle Emacs Sieve Manual
9 This file documents the Emacs Sieve package, for server-side mail filtering.
11 Copyright @copyright{} 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
12 2009, 2010 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3 or
17 any later version published by the Free Software Foundation; with no
18 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
19 and with the Back-Cover Texts as in (a) below. A copy of the license
20 is included in the section entitled ``GNU Free Documentation License''.
22 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
23 modify this GNU manual. Buying copies from the FSF supports it in
24 developing GNU and promoting software freedom.''
30 * Sieve: (sieve). Managing Sieve scripts in Emacs.
35 @setchapternewpage odd
38 @title Emacs Sieve Manual
40 @author by Simon Josefsson
42 @vskip 0pt plus 1filll
50 @top Sieve Support for Emacs
52 This is intended as a users manual for Sieve Mode and Manage Sieve, and
53 as a reference manual for the @samp{sieve-manage} protocol Emacs Lisp
56 Sieve is a language for server-side filtering of mail. The language
57 is documented in RFC 3028. This manual does not attempt to document
58 the language, so keep RFC 3028 around.
65 * Installation:: Getting ready to use the package.
66 * Sieve Mode:: Editing Sieve scripts.
67 * Managing Sieve:: Managing Sieve scripts on a remote server.
68 * Examples :: A few Sieve code snippets.
69 * Manage Sieve API :: Interfacing to the Manage Sieve Protocol API.
70 * Standards:: A summary of RFCs and working documents used.
71 * GNU Free Documentation License:: The license for this documentation.
72 * Index:: Function and variable index.
81 The Sieve package should come with your Emacs version, and should be
82 ready for use directly.
84 However, to manually set up the package you can put the following
85 commands in your @code{~/.emacs}:
88 (autoload 'sieve-mode "sieve-mode")
91 (setq auto-mode-alist (cons '("\\.s\\(v\\|iv\\|ieve\\)\\'" . sieve-mode)
99 Sieve mode provides syntax-based indentation, font-locking support and
100 other handy functions to make editing Sieve scripts easier.
102 Use @samp{M-x sieve-mode} to switch to this major mode. This command
103 runs the hook @code{sieve-mode-hook}.
105 @vindex sieve-mode-map
106 @vindex sieve-mode-syntax-table
107 Sieve mode is derived from @code{c-mode}, and is very similar except
108 for the syntax of comments. The keymap (@code{sieve-mode-map}) is
109 inherited from @code{c-mode}, as are the variables for customizing
110 indentation. Sieve mode has its own abbrev table
111 (@code{sieve-mode-abbrev-table}) and syntax table
112 (@code{sieve-mode-syntax-table}).
114 In addition to the editing utility functions, Sieve mode also contains
115 bindings to manage Sieve scripts remotely. @xref{Managing Sieve}.
122 @cindex manage remote sieve script
123 Open a connection to a remote server using the Managesieve protocol.
128 @cindex upload sieve script
129 Upload the Sieve script to the currently open server.
135 @chapter Managing Sieve
137 Manage Sieve is a special mode used to display Sieve scripts available
138 on a remote server. It can be invoked with @kbd{M-x sieve-manage
139 RET}, which queries the user for a server and if necessary, user
142 When a server has been successfully contacted, the Manage Sieve buffer
143 looks something like:
146 Server : mailserver:2000
148 2 scripts on server, press RET on a script name edits it, or
149 press RET on <new script> to create a new script.
155 One of the scripts are highlighted, and standard point navigation
156 commands (@kbd{<up>}, @kbd{<down>} etc) can be used to navigate the
159 The following commands are available in the Manage Sieve buffer:
165 @findex sieve-activate
166 Activates the currently highlighted script.
170 @findex sieve-deactivate
171 Deactivates the currently highlighted script.
175 @findex sieve-deactivate-all
176 Deactivates all scripts.
181 Remove currently highlighted script.
189 @findex sieve-edit-script
190 Bury the server buffer and download the currently highlighted script
191 into a new buffer for editing in Sieve mode (@pxref{Sieve Mode}).
195 @findex sieve-edit-script-other-window
196 Create a new buffer in another window containing the currently
197 highlighted script for editing in Sieve mode (@pxref{Sieve Mode}).
201 @findex sieve-bury-buffer
202 Bury the Manage Sieve buffer without closing the connection.
209 Displays help in the minibuffer.
216 If you are not familiar with Sieve, this chapter contains a few simple
217 code snippets that you can cut'n'paste and modify at will, until you
218 feel more comfortable with the Sieve language to write the rules from
221 The following complete Sieve script places all messages with a matching
222 @samp{Sender:} header into the given mailbox. Many mailing lists uses
223 this format. The first line makes sure your Sieve server understands
224 the @code{fileinto} command.
229 if address "sender" "owner-w3-beta@@xemacs.org" @{
230 fileinto "INBOX.w3-beta";
234 A few mailing lists do not use the @samp{Sender:} header, but has a
235 unique identifier in some other header. The following is not a
236 complete script, it assumes that @code{fileinto} has already been
240 if header :contains "Delivered-To" "auc-tex@@sunsite.dk" @{
241 fileinto "INBOX.auc-tex";
245 At last, we have the hopeless mailing lists that does not have any
246 unique identifier and you are forced to match on the @samp{To:} and
247 @samp{Cc} headers. As before, this snippet assumes that @code{fileinto}
251 if address ["to", "cc"] "kerberos@@mit.edu" @{
252 fileinto "INBOX.kerberos";
256 @node Manage Sieve API
257 @chapter Manage Sieve API
259 The @file{sieve-manage.el} library contains low-level functionality
260 for talking to a server with the @sc{managesieve} protocol.
262 A number of user-visible variables exist, which all can be customized
263 in the @code{sieve} group (@kbd{M-x customize-group RET sieve RET}):
267 @item sieve-manage-default-user
268 @vindex sieve-manage-default-user
269 Sets the default username.
271 @item sieve-manage-default-port
272 @vindex sieve-manage-default-port
273 Sets the default port to use, the suggested port number is @code{2000}.
275 @item sieve-manage-log
276 @vindex sieve-manage-log
277 If non-@code{nil}, should be a string naming a buffer where a protocol trace
278 is dumped (for debugging purposes).
282 The API functions include:
286 @item sieve-manage-open
287 @findex sieve-manage-open
288 Open connection to managesieve server, returning a buffer to be used
289 by all other API functions.
291 @item sieve-manage-opened
292 @findex sieve-manage-opened
293 Check if a server is open or not.
295 @item sieve-manage-close
296 @findex sieve-manage-close
297 Close a server connection.
299 @item sieve-manage-authenticate
300 @findex sieve-manage-authenticate
301 Authenticate to the server.
303 @item sieve-manage-capability
304 @findex sieve-manage-capability
305 Return a list of capabilities the server supports.
307 @item sieve-manage-listscripts
308 @findex sieve-manage-listscripts
309 List scripts on the server.
311 @item sieve-manage-havespace
312 @findex sieve-manage-havespace
313 Return non-@code{nil} if the server has room for a script of given
316 @item sieve-manage-getscript
317 @findex sieve-manage-getscript
318 Download script from server.
320 @item sieve-manage-putscript
321 @findex sieve-manage-putscript
322 Upload script to server.
324 @item sieve-manage-setactive
325 @findex sieve-manage-setactive
326 Indicate which script on the server should be active.
333 The Emacs Sieve package implements all or parts of a small but
334 hopefully growing number of RFCs and drafts documents. This chapter
335 lists the relevant ones. They can all be fetched from
336 @uref{http://quimby.gnus.org/notes/}.
341 Sieve: A Mail Filtering Language.
343 @item draft-martin-managesieve-03
344 A Protocol for Remotely Managing Sieve Scripts
348 @node GNU Free Documentation License
349 @appendix GNU Free Documentation License
350 @include doclicense.texi
361 arch-tag: 6e3ad0af-2eaf-4f35-a081-d40f4a683ec3