1MANAGESIEVE(1) managesieve MANAGESIEVE(1)
2
6 managesieve - managesieve Documentation
7 A pure Python application (the interactive sieveshell) for remotely
8 managing Sieve scripts. For developers it includes a Python module
9 implementing the ManageSieve client protocol (RFC 5804).
10
12 Instructions for Windows Users
13 1. managesieve requires Python. If you don't have Python installed al‐
14 ready, download and install Python 3.6 from
15 https://python.org/download/3.6/
16 During installation, make sure to check "Include into PATH".
18 2. If you already have Python installed, please check that your Python
20 directory (normally C:Python36 for python 3.6) and the Python
21 Scripts directory (normally :file`C:Python36Scripts`) are in the
22 system path. If not, just add them in My Computer ‣ Properties ‣ Ad‐
23 vanced ‣ Environment Variables to the Path system variable.
24 3. Install managesieve by running
26 pip install managesieve
28 Then run the console command managesieve --help to get detailed
30 help.
31 If the command pip is unknown to you system, please refer to the pip
33 homepage for help.
34 Instructions for GNU/Linux and other Operating Systems
36 Most current GNU/Linux distributions provide packages for managesieve.
37 Simply search your distribution's software catalog.
38 Also many vendors provide Python, and some even provide managesieve.
40 Please check your vendor's software repository.
41 If your distribution or vendor does not provide a current version of
43 managesieve please read on.
44 If your vendor does not provide python please download Python 3.6 from
46 https://www.python.org/download/ and follow the installation instruc‐
47 tions there.
48 If you distribution or vendor missed providing pip, alongside python,
50 please check your vendor's or distribution's software repository for a
51 package called pip or python-pip. If this is not provided, please re‐
52 fer to the pip homepage for help.
53 Then continue with Installing managesieve using pip below.
55 Installing managesieve using pip
57 After installing Python (and optionally PyPDF2), just run:
58 sudo pip install managesieve
60 to install managesieve for all users. For installing managesieve for
62 yourself only, run:
63 pip install --user managesieve
65 If your system does not have network access download managesieve from
67 https://pypi.org/project/managesieve/, and run
68 sudo pip install managesieve-*.tar.gz
70 respective
72 pip install --user managesieve-*.tar.gz
74
76 If you like managesieve, please consider supporting me in some way.
77 Bank transfers
79 While PayPal donations are still very much appreciated PayPal takes a
81 large cut and has rather questionable business practices.
82 If you have the ability to make SEPA bank transfers at a low cost (for
84 example if you live within the EU) please contact Hartmut to ask for
85 his bank details. I trust in the power of free and open source soft‐
86 ware and thus made the entire source code publicly available for every
87 one to use. However, it takes a lot of time to develop the software and
88 manage the community. And I still need to make my living.
89 So, if you like the software, please consider donating, especially if
91 your organization benefits from this project.
92 Thank you!
94 [image: QR-Code for Bitcoin address] [image] Bitcoin address.UNINDENT
95 • Bitcoin: 13qryeeJR5Hc7vR5AmQMWDuLzDEgSDNJi2
97 • Bank-Transfer (prefered): If you have the ability to make SEPA bank
99 transfers at a low cost please contact me and I'll send you the ac‐
100 count details. If you want a bill, please state so and also leave
101 your name and address.
102 • PayPal: Donate - if you want a bill, please state so and leave your
104 name, address and email-address.
105 • Please contact me to arrange some kind of project grant, e.g. con‐
107 sulting or support.
108
110 0.7.1 (2021-03-11)
111 Author: Hartmut Goebel, Thanks to Wouter Bolsterlee.
112 managesieve
114 • Actually raise debug-only exceptions instead of jsut returning
116 them.
117 • Fix invalid string-escape in docstring.
119 • Some minor clean-up.
121 sieveshell
123 • Some minor clean-up.
125 0.7 (2021-03-05)
127 Author: Hartmut Goebel
128 sieveshell
130 • For get and put expand ~ and ~user constructions in filename .
132 For put, if script-name is not given, the file's basename is
133 used.
134 managesieve
136 • Fix error when constructing debug error message.
138 0.6 (2018-06-27)
140 Author: Hartmut Goebel
141 • Add support for Python 3. Minimum required Python version is now
143 Python 2.7.
144 • Homepage is now hosted at https://managesieve.readthedocs.io/
146 • Documentation is extended and includes API documentation.
148 sieveshell
150 • Security fix: No longer leak environment variable SIEVE_PASS‐
152 WORD when displaying usage help.
153 • Per default enforce secure transport. Suggested by Jan Zere‐
155 becki.
156 • Add possibility to use username/password from the .netrc file.
158 The order is: command line options -> environment variables ->
159 .netrc file -> ask user. Thanks to Grégoire Détrez.
160 managesieve
162 • Fail if TLS is requested, but server doesn't support TLS.
164 Suggested by Jan Zerebecki.
165 project
167 • Rework and enhance test-suite. Thanks to Matěj Cepl for nudg‐
169 ing to proper pytest integration.
170 • Lots if internal cleanup.
172 Version 0.5 (2013-03-24)
174 Author: Hartmut Goebel
175 sieveshell
177 • Changed default port for the MANAGESIEVE protocol to 4190 as
179 proposed by RFC 5804. Thanks to Guido Berhoerster for submit‐
180 ting the patch.
181 • Added option --port. Thanks to Damien Aumaitre for submitting
183 the patch and to Guido Berhoerster for an enhancement.
184 • Added option --verbose for controlling debug output in manage‐
186 sieve. May be given several times to increase verbosity.
187 managesieve
189 • Switched to Python standard logging system. This introduces a
191 minor interface change: MANAGESIEVE.debug and global Debug are
192 gone. See source for information about debugging log levels.
193 Version 0.4.2 (2010-01-06)
195 Author: Hartmut Goebel
196 managesieve
198 • Use ssl.wrap_socket() instead of deprecated socket.ssl().
200 Thanks to Guido Berhoerster for submitting the patch.
201 Version 0.4.1 (2009-10-08)
203 Author: Hartmut Goebel
204 managesieve
206 • fixed short read (thanks to paurkedal for submitting the
208 patch)
209 Version 0.4 (2008-10-13)
211 Author: Hartmut Goebel
212 managesieve
214 • now work with Python 2.3 and later
216 • added support for TLS (STARTTLS), special thanks to Gregory
218 Boyce for fixing some corner cases here
219 • added support for PLAIN authentication
221 • use optparse if available instead of optik.
223 • API change: login() no longer uses the LOGIN authentication
225 mechanism, but has become a convenience function. It uses the
226 best mechanism available for authenticating the user.
227 • Bugfixes:
229 • If a capability had no values (like 'STARTTLS'), parsing ca‐
231 pabilities failed. Fixed.
232 • removed dependency on some imaplib's private functions
234 • fixed typo: self.supports_tls
236 Thanks to Tomas 'Skitta' Lindroos, Lorenzo Boccaccia, Alain
238 Spineux, darkness and Gregory Boyce for sending patches.
239 sieveshell
241 • added support for different authentication mechanisms
243 • added option --start-tls
245 • more verbose output when server says "BYE" (prints out refer‐
247 rals etc.)
248 • automatic cmd_quit() when server says "BYE"
250 • several minor bugfixes and enhancements
252 Version 0.3
254 Author: Hartmut Goebel
255 managesieve
257 • MANAGESIEVE.authenticate() now only returns a OK/NO/BYE result
259 like any command not asking data from the server
260 sieveshell
262 • added 'edit', which may create scripts, too. (posix only)
264 • now prints out the server capabilities, thus the user knows
266 what the server is capable of (and which Sieve-Commands may be
267 used).
268 • fixed some minor bugs
270 Version 0.2
272 Author: Hartmut Goebel <h.goebel@crazy-compilers.com>
273 • renamed to 'managesieve'
275 • added sieveshell
277 • major overhaul
279 • added support for HAVESPACE, CAPABILITY
281 • added unittest testsuite (covers most cases)
283 Version 0.1
285 Author: Ulrich Eck <ueck at net-labs.de>
286 • initial release of Sieve.py by Ulrich Eck as part of 'ImapClient'
288 (see http://www.zope.org/Members/jack-e/ImapClient), a Zope product.
289
291 The source of managesieve is maintained at GitLab. Patches and
292 pull-requests are hearty welcome.
293 • Please submit bugs and enhancements to the Issue Tracker.
295 • You may browse the code at the Repository Browser Or you may check
297 out the current version by running
298 git clone https://gitlab.com/htgoebel/managesieve.git
300 Historical Note: managesieve was hosted at origo.ethz.ch, which closed
302 in May 2012. Then managesieve was hosted on gitorious.org, which was
303 closed in May 2015 and merged into gitlab.
304
306 managesieve
307 ManageSieve (RFC 5804) client module for remotely managing Sieve
308 Scripts.
309 All Sieve commands are supported by methods of the same name (in
311 lower-case). All arguments to commands are converted to strings, except
312 for authenticate().
313 class managesieve.MANAGESIEVE(host='', port=4190, use_tls=False, key‐
315 file=None, certfile=None)
316 Sieve client class.
317 Instantiate with: MANAGESIEVE(host [, port])
319 Parameters
321 • host -- host's name (default: localhost)
323 • port -- port number (default: standard Sieve port).
325 • use_tls -- switch to TLS automatically, fail if the
327 server doesn't support STARTTLS
328 • keyfile -- keyfile to use for TLS (optional)
330 • certfile -- certfile to use for TLS (optional)
332 exception abort
334 Service errors - close and retry
335 authenticate(mechanism, *authobjects)
337 Authenticate to the server.
338 Parameters
340 • mechanism (str) -- authentication mechanism to
342 use
343 • authobjects -- authentication data for this
345 mechanism
346 Returns
348 response (OK, NO, BYE)
349 capability()
351 Issue a CAPABILITY command and return the result.
352 As a side-effect, on succes these attributes are (re)set:
354 • capabilities (list of strings)
356 • loginmechs (list of strings)
358 • implementation (string)
360 • supports_tls (boolean)
362 Returns
364 tuple(response, capabilities) -- If response is
365 OK, capabilities is a list of strings.
366 deletescript(scriptname)
368 Delete a scripts at the server.
369 Parameters
371 scriptname (str) -- name of script to be deleted
372 Returns
374 response (OK, NO, BYE)
375 exception error
377 Logical errors - debug required
378 getscript(scriptname)
380 Get a script from the server.
381 Parameters
383 scriptname (str) -- name of script to be retrieved
384 Returns
386 tuple(response, str) -- if response is OK, str is
387 the script content.
388 havespace(scriptname, size)
390 Query the server for available space.
391 Parameters
393 • scriptname (str) -- name of script to XXX
395 • size (int) -- XXX
397 Returns
399 response (OK, NO, BYE)
400 listscripts()
402 Get a list of scripts on the server.
403 Returns
405 tuple(response, [data]) -- if response is OK, data
406 is a list of (scriptname, active) tuples.
407 login(auth, user, password)
409 Authenticate to the Sieve server using the best mechanism
410 available.
411 Returns
413 response (OK, NO, BYE)
414 logout()
416 Terminate connection to server.
417 Returns
419 response (OK, NO, BYE)
420 putscript(scriptname, scriptdata)
422 Put a script onto the server.
423 Parameters
425 • scriptname (str) -- name of script to be re‐
427 trieved
428 • scriptdata (str) -- script content
430 Returns
432 response (OK, NO, BYE)
433 setactive(scriptname)
435 Mark a script as the 'active' one.
436 Parameters
438 scriptname (str) -- name of script to be marked
439 active
440 Returns
442 response (OK, NO, BYE)
443 starttls(keyfile=None, certfile=None)
445 Puts the connection to the SIEVE server into TLS mode.
446 If the server supports TLS, this will encrypt the rest of
448 the SIEVE session. If you provide the keyfile and cert‐
449 file parameters, the identity of the SIEVE server and
450 client can be checked. This, however, depends on whether
451 the socket module really checks the certificates.
452 Author Hartmut Goebel <h.goebel@crazy-compiler.com>
454 License
456 Python Software Foundation License for the module, GPL v3 for
457 sieveshell and test suite.
458 Homepage
460 https://managesieve.readthedocs.io/
461 Download
463 https://pypi.org/project/managesieve
464 Development
466 https://gitlab.com/htgoebel/managesieve
467
469 sieveshell is a command line tool for talking to a remote mail server.
470 Sieve scripts allow users to filter incoming email on the mail server.
471 Typically these servers are sealed so users cannot log into them, yet
472 users must be able to update their scripts on them. This is what
473 sieveshell is for.
474 One can
476 • list scripts on the server
478 • upload scripts to the server
480 • display scripts stored on the server and download or edit them
482 • delete scripts stored on the server
484 • activate and deactivate scripts
486 sieveshell is simple yet functional and useful for user who wish to
488 manage sieve scripts without installing a fat GUI-based mail client.
489
491 The managesieve pure Python module is a ManageSieve (RFC 5804) client
492 library for managing Sieve scripts on a mail server, more specific the
493 Sieve server. For API details see the Module Documentation.
494
496 Hartmut Goebel
497
499 2003-2023 by Hartmut Goebel
5000.7 Nov 17, 2023 MANAGESIEVE(1)