Emacs Sieve Manual

This manual documents the Emacs Sieve package.

It is intended as a users manual for Sieve Mode and Manage Sieve, and as a reference manual for the `sieve-manage' protocol Emacs Lisp API.

Sieve is a language for server-side filtering of mail. The language is documented in RFC 3028. This manual does not attempt to document the language, so keep RFC 3028 around.

A good online Sieve resources is http://www.cyrusoft.com/sieve/.

1. Installation    Getting ready to use the package.

2. Sieve Mode    Editing Sieve scripts.

3. Managing Sieve    Managing Sieve scripts on a remote server.

4. Examples    A few Sieve code snippets.

5. Manage Sieve API    Interfacing to the Manage Sieve Protocol API.

6. Standards    A summary of RFCs and working documents used.

7. Index    Function and variable index.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

1. Installation

The Sieve package should come with your Emacs version, and should be ready for use directly.

However, to manually set up the package you can put the following commands in your ~/.emacs:

(autoload 'sieve-mode "sieve-mode")

(setq auto-mode-alist (cons '("\\.si\\(v\\|eve\\)\\'" . sieve-mode) auto-mode-alist))

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

2. Sieve Mode

Sieve mode provides syntax-based indentation, font-locking support and other handy functions to make editing Sieve scripts easier.

Use `M-x sieve-mode' to switch to this major mode. This command runs the hook sieve-mode-hook.

Sieve mode is derived from c-mode, and is very similar except for the syntax of comments. The keymap (sieve-mode-map) is inherited from c-mode, as are the variables for customizing indentation. Sieve mode has its own abbrev table (sieve-mode-abbrev-table) and syntax table (sieve-mode-syntax-table).

In addition to the editing utility functions, Sieve mode also contains bindings to manage Sieve scripts remotely. see section 3. Managing Sieve.

C-c RET: Open a connection to a remote server using the Managesieve protocol.
C-c C-l: Upload the Sieve script to the currently open server.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

3. Managing Sieve

Manage Sieve is a special mode used to display Sieve scripts available on a remote server. It can be invoked with M-x sieve-manage RET, which queries the user for a server and if necessary, user credentials to use.

When a server has been succesfully contacted, the Manage Sieve buffer looks something like:

Server : mailserver:2000 2 scripts on server, press RET on a script name edits it, or press RET on <new script> to create a new script. <new script> ACTIVE .sieve template.siv

One of the scripts are highlighted, and standard point navigation commands (<up>, <down> etc) can be used to navigate the list.

The following commands are available in the Manage Sieve buffer:

m: Activates the currently highlighted script.
u: Deactivates the currently highlighted script.
C-M-?: Deactivates all scripts.
r: Remove currently highlighted script.
RET
mouse-2
f: Bury the server buffer and download the currently highlighted script into a new buffer for editing in Sieve mode (see section 2. Sieve Mode).
o: Create a new buffer in another window containing the currently highlighted script for editing in Sieve mode (see section 2. Sieve Mode).
q: Bury the Manage Sieve buffer without closing the connection.
?
h: Displays help in the minibuffer.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

4. Examples

If you are not familiar with Sieve, this chapter contains a few simple code snippets that you can cut'n'paste and modify at will, until you feel more comfortable with the Sieve language to write the rules from scratch.

The following complete Sieve script places all messages with a matching `Sender:' header into the given mailbox. Many mailing lists uses this format. The first line makes sure your Sieve server understands the fileinto command.

require "fileinto"; if address "sender" "[email protected]" { fileinto "INBOX.w3-beta"; }

A few mailing lists do not use the `Sender:' header, but does contain some unique identifier in some other header. The following is not a complete script, it assumes that fileinto has already been required.

if header :contains "Delivered-To" "[email protected]" { fileinto "INBOX.auc-tex"; }

At last, we have the hopeless mailing lists that does not have any unique identifier and you are forced to match on the `To:' and `Cc' headers. As before, this snippet assumes that fileinto has been required.

if address ["to", "cc"] "[email protected]" { fileinto "INBOX.kerberos"; }

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

5. Manage Sieve API

The `sieve-manage.el' library contains low-level functionality for talking to a server with the MANAGESIEVE protocol.

A number of user-visible variables exist, which all can be customized in the sieve group (M-x customize-group RET sieve RET):

sieve-manage-default-user: Sets the default username.
sieve-manage-default-port: Sets the default port to use, the suggested port number is 2000.
sieve-manage-log: If non-nil, should be a string naming a buffer where a protocol trace is dumped (for debugging purposes).

The API functions include:

sieve-manage-open: Open connection to managesieve server, returning a buffer to be used by all other API functions.
sieve-manage-opened: Check if a server is open or not.
sieve-manage-close: Close a server connection.
sieve-manage-authenticate: Authenticate to the server.
sieve-manage-capability: Return a list of capabilities the server support.
sieve-manage-listscripts: List scripts on the server.
sieve-manage-havespace: Returns non-nil iff server have roam for a script of given size.
sieve-manage-getscript: Download script from server.
sieve-manage-putscript: Upload script to server.
sieve-manage-setactive: Indicate which script on the server should be active.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

6. Standards

The Emacs Sieve package implements all or parts of a small but hopefully growing number of RFCs and drafts documents. This chapter lists the relevant ones. They can all be fetched from http://quimby.gnus.org/notes/.

RFC3028: Sieve: A Mail Filtering Language.
draft-martin-managesieve-03: A Protocol for Remotely Managing Sieve Scripts

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

7. Index

Jump to:	I M S U

	Index Entry	Section

I
	Install	1. Installation

M
	manage remote sieve script	2. Sieve Mode

S
	Setup	1. Installation
	sieve-activate	3. Managing Sieve
	sieve-bury-buffer	3. Managing Sieve
	sieve-deactivate	3. Managing Sieve
	sieve-deactivate-all	3. Managing Sieve
	sieve-edit-script	3. Managing Sieve
	sieve-edit-script-other-window	3. Managing Sieve
	sieve-help	3. Managing Sieve
	sieve-manage	2. Sieve Mode
	sieve-manage-authenticate	5. Manage Sieve API
	sieve-manage-capability	5. Manage Sieve API
	sieve-manage-close	5. Manage Sieve API
	sieve-manage-default-port	5. Manage Sieve API
	sieve-manage-default-user	5. Manage Sieve API
	sieve-manage-getscript	5. Manage Sieve API
	sieve-manage-havespace	5. Manage Sieve API
	sieve-manage-listscripts	5. Manage Sieve API
	sieve-manage-log	5. Manage Sieve API
	sieve-manage-open	5. Manage Sieve API
	sieve-manage-opened	5. Manage Sieve API
	sieve-manage-putscript	5. Manage Sieve API
	sieve-manage-setactive	5. Manage Sieve API
	sieve-mode-map	2. Sieve Mode
	sieve-mode-syntax-table	2. Sieve Mode
	sieve-remove	3. Managing Sieve
	sieve-upload	2. Sieve Mode

U
	upload sieve script	2. Sieve Mode

Jump to:	I M S U

[Top]

[Contents]

[Index]

[ ? ]

1. Installation
2. Sieve Mode
3. Managing Sieve
4. Examples
5. Manage Sieve API
6. Standards
7. Index

[Top]

[Contents]

[Index]

[ ? ]

Short Table of Contents

1. Installation
2. Sieve Mode
3. Managing Sieve
4. Examples
5. Manage Sieve API
6. Standards
7. Index

[Top]

[Contents]

[Index]

[ ? ]

About this document

This document was generated using texi2html

The buttons in the navigation panels have the following meaning:

Button	Name	Go to	From 1.2.3 go to
[ < ]	Back	previous section in reading order	1.2.2
[ > ]	Forward	next section in reading order	1.2.4
[ << ]	FastBack	previous or up-and-previous section	1.1
[ Up ]	Up	up section	1.2
[ >> ]	FastForward	next or up-and-next section	1.3
[Top]	Top	cover (top) of document
[Contents]	Contents	table of contents
[Index]	Index	concept index
[ ? ]	About	this page

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

1. Section One

1.1 Subsection One-One

1.2 Subsection One-Two

1.2.1 Subsubsection One-Two-One
1.2.2 Subsubsection One-Two-Two
1.2.3 Subsubsection One-Two-Three <== Current Position
1.2.4 Subsubsection One-Two-Four

1.3 Subsection One-Three

1.4 Subsection One-Four

This document was generated by Simon Josefsson on July, 27 2002 using texi2html

1. Installation		Getting ready to use the package.
2. Sieve Mode		Editing Sieve scripts.
3. Managing Sieve		Managing Sieve scripts on a remote server.
4. Examples		A few Sieve code snippets.
5. Manage Sieve API		Interfacing to the Manage Sieve Protocol API.
6. Standards		A summary of RFCs and working documents used.
7. Index		Function and variable index.