     [file version.texi not included]
     [file rendition.texi not included]
     [file macros.texi not included]

Published by the Free Software Foundation, 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA

Copyright © 1999-2004, 2008-2012 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover, and no Back-Cover texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

GNU Mailutils
*************

This edition of the GNU Mailutils Manual, last updated on UPDATED, documents GNU Mailutils Version VERSION.

Introduction
************

GNU Mailutils is a set of libraries and utilities for handling electronic mail.  It addresses a wide audience and can be of interest to application developers, casual users and system administrators alike.

It provides programmers with a consistent API allowing them to handle a variety of different mailbox formats transparently and without having to delve into complexities of their internal structure. While doing so, it also provides interfaces that simplify common programming tasks, such as handling lists, parsing configuration files, etc.  The philosophy of Mailutils is to have a single and consistent programming interface for various objects designed to handle the same task.  It tries to use their similarities to create an interface that hides their differences and complexities.  This covers a wide variety of programming tasks: apart from mailbox handling, Mailutils also contains a unified iterface for work with various DBM databases and much more.

The utilities built upon these libraries share that same distinctive feature: no matter what is the internal structure of an object, it is always handled the same way as other objects that do the same task. Again, the most common example of this approach are, of course, mailboxes.  Whatever Mailutils program you use, you can be sure it is able to handle various mailbox formats.  You even don't have to inform it about what type a mailbox is: it will do its best to discover it automatically.

This approach sometimes covers entities which are seldom regarded as compatible.  For example, using Mailutils it is possible to treat an SMTP connection as a mailbox opened only for appending new messages.  This in turn, provides a way for extending the functionality of some utilities.  As an example, using this concept of mailboxes, the usual mail delivery agent becomes able to do things usually reserved for mail transport agents only!

At the core of Mailutils is libmailutils, a library which provides an API for accessing a generalized mailbox.  A set of complementary libraries provide methods for handling particular mailbox implementations: UNIX mailbox, Maildir, MH, POP3, IMAP4, even SMTP.  Mailutils offers functions for almost any mail-related task, such as parsing of messages, email addresses and URLs, handling MIME messages, listing mail folders, mailcap facilities, extensible Sieve filtering, access control lists.  It supports various modern data security and authentication techniques: TLS encryption, SASL and GSSAPI, to name a few.  Mailutils is able to work with a wide variety of authorization databases, ranging from traditional system password database up to RADIUS, SQL and LDAP.

The utilities provided by Mailutils include imap4d and pop3d mail servers, mail reporting utility comsatd, general-purpose mail delivery agent maidag, mail filtering program sieve, an implementation of MH message handling system and much more.

All utilities share the same subset of command line options and use a unified configuration mechanism, which allows to easily configure the package as a whole.

This software is part of the GNU Project and is copyrighted by the Free Software Foundation.  All libraries are distributed under the terms of the Lesser GNU Public License.  The documentation is licensed under the GNU FDL, and everything else is licensed under the GNU GPL.

What this Book Contains
=======================

This is more a plan on how the document should be structured, than a description of its actual structure.  However it is:

This book addresses a wide audience of both system administrators and users that aim to use Mailutils programs, and programmers who wish to use Mailutils libraries in their programs.  Given this audience, the book is divided in three major parts.

The first part provides a detailed description of each Mailutils utility, and advices on how to use them in various situations.  This part is intended for users and system administrators who are using Mailutils programs.  If you are not interested in programming using Mailutils, this is the only part you need to read.

Subsequent parts address programmers.

The second part is a tutorial which provides an introduction to programming techniques for writing mail applications using GNU Mailutils.

Finally, the third part contains a complete Mailutils library reference.

This version of the book is not finished.  The places that may contain inaccurate information carry prominent notices stating so. For updated versions of the documentation, visit http://mailutils.org/manual.  All material that ends up in this document is first published in the Mailutils Wiki, available at http://mailutils.org/wiki.  Be sure to visit it for latest updates.

If you have any questions that are not answered there, feel free to ask them at the mailing list bug-mailutils@gnu.org.

Mailutils 3.0 introduced such amount of changes, most of which being a complete rewrite of the existing codebase, that the library tutorial and reference became hopelessly obsolete.  It is my deep conviction that using incorrect documentation is much worse than having no documentation at all, therefore I have withdrawn the obsolete parts from this edition of GNU Mailutils manual.  I am doing my best to document new Mailutils libraries and hope to be able to re-introduce these parts of the documentation soon.

A bit of History, and why use this package?
===========================================

This package started off to try and handle large mailbox files more gracefully then available at that time POP3 servers did.  While it handles this task, it also allows you to support a variety of different mailbox formats without any real effort on your part. Also, if a new format is added at a later date, your program will support that new format automatically as soon as it is compiled against the new library.

Reporting Bugs
**************

Email bug reports to bug-mailutils@gnu.org.

As the purpose of bug reporting is to improve software, please be sure to include maximum information when reporting a bug.  The information needed is:

  * Version of the package you are using.

  * Compilation options used when configuring the package.

  * Conditions under which the bug appears.

The archives of bug-mailutils mailing list are available from http://mail.gnu.org/mailman/listinfo/bug-mailutils.

Mailutils Programs
******************

     [file programs.texi not included]

Mailutils Libraries
*******************

Sieve Language
**************

     [file sieve.texi not included]

Getting News About GNU Mailutils
********************************

The two places to look for any news regarding GNU Mailutils are the Mailutils homepage at http://mailutils.org or http://www.gnu.org/software/mailutils, and the project page at http://savannah.gnu.org/projects/mailutils.

The updated versions of this manual are available online from http://mailutils.org/manual.  See also Mailutils Wiki (http://mailutils.org/wiki) for the latest updates.

Acknowledgement
***************

In no particular order,

  * Jakob Kaivo jkaivo@ndn.net,

  * Jeff Bailey jbailey@gnu.org,

  * Sean Perry shaleh@debian.org,

  * Thomas Fletcher thomasf@qnx.com,

  * Dave Inglis dinglis@qnx.com,

  * Brian Edmond briane@qnx.com,

  * Sam Roberts sroberts@uniserve.com,

  * Sergey Poznyakoff gray@Mirddin.farlep.net,

  * François Pinard  pinard@IRO.UMontreal.CA.

  * Jordi Mallach jordi@sindominio.net

  * Wojciech Polak polak@gnu.org

References
**********

Date Input Formats
******************

     [file getdate.texi not included]

Configuring Help Summary
************************

     [file usage.texi not included]

GNU Free Documentation License
******************************

     [file fdl.texi not included]

Function Index
**************

This is an alphabetical list of all Mailutils functions.

Concept Index
*************

This is a general index of all issues discussed in this manual