path: root/doc/texinfo/mailutils.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename mailutils.info
@settitle GNU Mailutils Manual
@setchapternewpage odd
@c %**end of header

@include version.texi
@include rendition.texi
@include macros.texi

@c Define indices
@defcodeindex op
@defcodeindex fl
@c Same as ky, but used for configuration keywords.
@defcodeindex kw

@c Combine indices.
@syncodeindex op fn
@syncodeindex tp fn
@syncodeindex fl cp
@c FIXME: Should kw be separate?
@syncodeindex kw ky

@ifinfo
@dircategory Email
@direntry
* Mailutils: (mailutils).       GNU Mail Utilities.
@end direntry
@dircategory Individual utilities
@direntry
* comsatd: (mailutils) comsatd.          Comsat Daemon.
* frm: (mailutils) frm.                  List Headers from a Mailbox.
* guimb: (mailutils) guimb.              Mailbox Processing Language.
* imap4d: (mailutils) imap4d.            IMAP4 Daemon.
* mail: (mailutils) mail.                Send and Receive Mail.
* maidag: (mailutils) maidag.            A General-Purpose Mail Delivery Agent.
* messages: (mailutils) messages.        Count Messages in a Mailbox.
* movemail: (mailutils) movemail.        Move Mail between Mailboxes.
* pop3d: (mailutils) pop3d.              POP3 Daemon.
* readmsg: (mailutils) readmsg.          Extract Messages from a Folder.
* sieve: (mailutils) sieve.              Mail Filtering Utility.
* mimeview: (mailutils) mimeview.        View MIME Messages.
* mailutils: (mailutils) mailutils.      Mailutils Multi-Purpose Tool
@end direntry
@end ifinfo

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

Copyright @copyright{} 1999-2020 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''.
@end copying

@titlepage
@title GNU Mailutils
@subtitle version @value{VERSION}, @value{UPDATED}
@author Alain Magloire, Sergey Poznyakoff et al.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@ifnothtml
@page
@summarycontents
@page
@end ifnothtml
@contents

@ifnottex
@node Top
@top GNU Mailutils

This edition of the @cite{GNU Mailutils Manual}, last updated on
@value{UPDATED}, documents GNU Mailutils Version @value{VERSION}.
@end ifnottex

@menu
* Introduction::            Preliminary Information.
* Mailbox::                 Mailboxes and URLs.
* Programs::                Mailutils Programs.
* Libraries::               Mailutils Libraries.
* Sieve Language::          The Sieve Language.
* Reporting Bugs::          How to Report a Bug.
* News::                    Getting News About GNU Mailutils.
* Acknowledgement::         Thanks and Credits.

Appendices

* References::              References.
* Date Input Formats::
* Date/time Format String::
* Usage Vars::              Configuring Help Summary
* GNU FDL::                 This manual is under the GNU Free
                            Documentation License.

Indices

* Function Index::          All Mailutils Functions.
* Variable Index::          All Mailutils Variables.
* Keyword Index::           Index of Keywords.
* Program Index::           All Mailutils Programs.
* Concept Index::           Index of Concepts.

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Book Contents::               What this Book Contains
* History::                     A bit of History

Mailbox

* Local Mailboxes::      Mailboxes stored on the local file system.
* Remote Mailboxes::     Mailboxes stored on remote hosts.
* SMTP Mailboxes::       Mailboxes that send mail.
* Program Mailboxes::

Mailutils Programs

* command line::      Command Line Syntax.  
* configuration::     Common Configuration File.
* debugging::

* frm and from::      List Headers from a Mailbox.
* mail::              Send and Receive Mail.
* messages::          Count the Number of Messages in a Mailbox.
* movemail::          Moves Mail from the User Maildrop to the Local File.
* readmsg::           Extract Messages from a Folder.

* sieve::             Mail Filtering Utility.
* guimb::             Mailbox Scanning and Processing Language.

* mda::               Local Mail Delivery Agent.
* lmtpd::             LMTP Daemon.
* putmail::           Incorporate a Message to a Mailbox.

* mimeview::          Universal File Viewer.

* pop3d::             POP3 Daemon.
* imap4d::            IMAP4 Daemon.
* comsatd::           Comsat Daemon.

* mh::                The MH Message Handling System.

* mailutils::         The Mailutils Multi-Purpose Tool.

Command Line

* Option Basics::       Basic Notions About Command Line Options.
* Common Options::      Options That are Common for All Utilities.

Mailutils Configuration File

* conf-syntax::         Configuration File Syntax
* Variables::           Variable Expansion
* include::             Include Statement
* program statement::
* logging statement::
* debug statement::
* mailbox statement::
* locking statement::
* mailer statement::
* acl statement::
* tcp-wrappers statement::
* Server Settings::
* auth statement::
* pam statement::
* virtdomain statement::
* radius statement::
* sql statement::
* ldap statement::
* tls statement::
* tls-file-checks statement::
* gsasl statement::

Configuration File Syntax

* Comments::
* Statements::
* Paths::

Server Settings

* General Server Configuration::
* Server Statement::

Debugging

* Level Syntax::
* Level BNF::
* Debugging Categories::

@command{mail} --- Send and Receive Mail

* Invoking Mail::            Command Line Options.
* Reading Mail::             Reading Mail.
* Composing Mail::           Composing Mail.
* MIME::                     How to Attach Files.
* Scripting::                Scripting.
* Mail Variables::           How to Alter the Behavior of @command{mail}.
* Mail Configuration Files:: Personal and System-wide Configuration Files.

Reading Mail

* Command Syntax::           Syntax of mail internal commands.
* Quitting the Program::
* Obtaining Online Help::
* Moving Within a Mailbox::
* Changing mailbox/directory::
* Controlling Header Display::
* Displaying Information::
* Displaying Messages::
* Marking Messages::
* Disposing of Messages::
* Saving Messages::
* Editing Messages::
* Aliasing::
* Replying::
* Controlling Sender Fields::
* Incorporating New Mail::
* Shell Escapes::

Composing Mail

* Quitting Compose Mode::
* Getting Help on Compose Escapes::
* Editing the Message::
* Modifying the Headers::
* Enclosing Another Message::
* Adding a File to the Message::
* Attaching a File to the Message::
* Printing And Saving the Message::
* Signing the Message::
* Printing Another Message::
* Inserting Value of a Mail Variable::
* Executing Other Mail Commands::
* Executing Shell Commands::

@command{movemail} --- Moves Mail from the User Maildrop to the Local File

* Movemail Configuration::
* Ownership::            Setting Destination Mailbox Ownership
* Summary::              Short Movemail Invocation Summary

@command{readmsg} --- Extract Messages from a Folder

* Opt-readmsg::   Invocation of @command{readmsg}.
* Conf-readmsg::  Configuration of @command{readmsg}.

@command{sieve}

* sieve interpreter::   A Sieve Interpreter

A Sieve Interpreter

* Invoking Sieve::
* Sieve Configuration::
* Logging and Debugging::
* Extending Sieve::

@command{guimb} --- A Mailbox Scanning and Processing Language

* Specifying Scheme Program to Execute::
* Specifying Mailboxes to Operate Upon::
* Passing Options to Scheme::
* Command Line Option Summary::

mda

* Sendmail-mda::         Using @command{mda} with Sendmail.
* Exim-mda::             Using @command{mda} with Exim.
* MeTA1-mda::            Using @command{mda} with MeTA1.
* Mailbox Quotas::
* MDA Scripting::
* Forwarding::
* Conf-mda::             @command{mda} Configuration File Summary.
* Mailing lists::        How to implement Mailing Lists with @command{mda}.

Mailbox Quotas

* DBM Quotas::          Keeping Quotas in DBM File.
* SQL Quotas::          Keeping Quotas in SQL Database.

Scripting in @command{mda}

* Sieve MDA Filters::
* Scheme MDA Filters::
* Python MDA Filters::

mimeview

* Mimeview Invocation::
* Mimeview Config::

POP3 Daemon

* Login delay::
* Auto-expire::
* Bulletins::
* Conf-pop3d::           Pop3d Configuration
* Command line options::

IMAP4 Daemon

* Namespace::       Namespace.
* Conf-imap4d::     Configuration.
* Starting imap4d:: Invocation Options.

Comsat Daemon

* Starting comsatd::       Invocation.
* Configuring comsatd::    Configuration of @command{comsatd}.
* dot.biffrc::             A per-user configuration file.

Configuring @command{comsatd}

* General Settings::
* Security Settings::

MH --- The MH Message Handling System

* Diffs::      Major differences between Mailutils MH and other MH
               implementations.

Major differences between Mailutils MH and other MH implementations

* Format String Diffs::
* Profile Variable Diffs::
* Program Diffs::

mailutils

* mailutils invocation syntax::
* mailutils help::                Display a terse help summary.
* mailutils info::                Show Mailutils configuration.
* mailutils cflags::              Show compiler options.
* mailutils ldflags::             List libraries required to link.
* mailutils stat::                Show mailbox status.
* mailutils query::               Query configuration values.
* mailutils 2047::                Decode/encode email message headers.
* mailutils filter::              Apply a chain of filters to the input.
* mailutils acl::                 Test access control lists.
* mailutils wicket::              Scan wickets for matching URLs.
* mailutils dbm::                 DBM management tool.
* mailutils logger::              Log data using Mailutils log facility.
* mailutils pop::                 POP3 client shell.
* mailutils imap::                IMAP4 client shell.
* mailutils send::                Send a message.
* mailutils smtp::                Run a SMTP session.

mailutils dbm

* Create a Database::
* Add Records to a Database::
* Delete Records::
* List the Database::
* Dump the Database::
* Dump Formats::
* Dbm Exit Codes::

Sieve Language

* Lexical Structure::
* Syntax::
* Preprocessor::
* Require Statement::
* Comparators::
* Tests::
* Actions::
* Extensions::
* GNU Extensions::

Syntax

* Commands::
* Actions Described::
* Control Flow::
* Tests and Conditions::

Preprocessor

* #include::        Include the contents of a file.
* #searchpath::     Modify the current search path.

Tests

* Built-in Tests::
* External Tests::

Actions

* Built-in Actions::
* External Actions::

Extensions

* encoded-character::
* relational::
* variables::
* environment::
* numaddr::
* editheader::
* list::
* moderator::
* pipe::
* spamd::
* timestamp::
* vacation::

Date Input Formats

* General date syntax::            Common rules.
* Calendar date items::            19 Dec 1994.
* Time of day items::              9:20pm.
* Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}.
* Day of week items::              Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings::   19931219, 1440.
* Seconds since the Epoch::        @@1078100502.
* Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
* Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.

@end detailmenu
@end menu

@node Introduction
@chapter 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 @file{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 @command{imap4d} and
@command{pop3d} mail servers, mail reporting utility
@command{comsatd}, general-purpose mail delivery agent
@command{maidag}, mail filtering program @command{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.

@menu
* Book Contents::               What this Book Contains
* History::                     A bit of History
@end menu

@node Book Contents
@section What this Book Contains

@FIXME{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
@uref{http://mailutils.org/manual}.  All material that ends up in this
document is first published in the Mailutils Wiki, available at
@uref{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 @email{bug-mailutils@@gnu.org}. 

@FIXME{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.}

@node History
@section A bit of History, and why use this package?
@UNREVISED

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. 

@node Mailbox
@chapter Mailbox
@cindex mailbox URL
@cindex URL, mailbox

The principal object Mailutils operates on is @dfn{mailbox} --
a collection of mail messages.  The two main characteristics of a
mailbox are its type and path.  The @dfn{type} defines how the
messages are stored within a mailbox.  The @dfn{path} specifies
the location of the mailbox.  The two characteristics are usually
combined within a @dfn{Uniform Resource Locator} (@acronym{URL}),
which uniquely identifies the mailbox.  The syntax for @acronym{URL}
is:

@example
@var{type}:[//[@var{user}:@var{password}@@]@var{host}[:@var{port}]]@var{path}[?@var{query}][;@var{params}]
@end example

The square brackets do not appear in a @acronym{URL}, instead they are
used to denote optional parts.

Not all parts are meaningful for all types.  Their usage and purpose
are described in the sections that follow.

@menu
* Local Mailboxes::      Mailboxes stored on the local file system.
* Remote Mailboxes::     Mailboxes stored on remote hosts.
* SMTP Mailboxes::       Mailboxes that send mail.
* Program Mailboxes::
@end menu

@node Local Mailboxes
@section Local Mailboxes
@cindex local mailbox
@cindex mailbox, local
@cindex URL, local

@dfn{Local mailboxes} store mail in files on the local file system.  A
local mailbox URL is:

@example
@var{type}://@var{path}[;@var{params}]
@end example

The @var{path} defines its location in the file system.  For example:

@example
mbox:///var/spool/mail/gray
@end example

Optional @var{params} is a semicolon-separated list of optional
arguments that configures indexed directory structure.  @xref{local
URL parameters}, for a detailed description.

The local mailbox types are:

@table @asis
@anchor{mbox}
@cindex mbox
@item mbox
A traditional UNIX mailbox format.  Messages are stored sequentially
in a single file.  Each message begins with a @samp{From} line,
identifying its sender and date when it was received.  A single empty
line separates two adjacent messages.

This is the default format.

@cindex maildir
@item maildir
The @dfn{Maildir} mailbox format.  Each message is kept in a separate
file with a unique name.  Each mailbox is therefore a directory.  This
mailbox format eliminates file locking and makes message access much
faster.

@cindex Bernstein, D. J. 
This format was originally described by D.@: J.@: Bernstein in
@url{http://cr.yp.to/proto/maildir.html}.

@cindex mh
@item mh
MH Message Handling System format.  Each message is kept in a separate
file named after its sequential numeric identifier within the mailbox.
Deleted messages are not removed, but instead the corresponding file
is renamed by prepending a comma to its original name.  Each mailbox
is a directory.  Mailboxes can be nested.

@cindex RAND Corporation
This format was originally developed by RAND Corporation.  Mailutils
implementation is compatible both with the original implementation and
with its descendant @dfn{nmh}.

@cindex file, mailbox type
@item file
This type can be used when accessing an existing mailbox of any of the
formats defined above.  The actual mailbox format is determined
automatically.  This type is assumed when a mailbox is referred to by
its full pathname.
@end table

@node Remote Mailboxes
@section Remote Mailboxes
@cindex remote mailbox
@cindex mailbox, remote
@cindex URL, remote

@dfn{Remote mailboxes} are accessed via one of the remote message
protocols. 

The basic remote mailbox types are:

@table @asis
@cindex pop, mailbox
@item pop
Remote mailbox accessed using the @dfn{Post Office Protocol}
(@acronym{POP3}).  Default port number 110.

The URL is:

@example
pop://[@var{user}[:@var{pass}][;auth=+APOP]@@]@var{host}[:@var{port}][;notls]
@end example

The @var{host} gives the name or IP address of the host running a POP3
server. Optional @var{port} can be used to connect to a port other than
the default 110.

The @var{user} and @var{pass} supply authentication credentials. If any
of them is missing, Mailtils will first try to obtain it from the ticket
file.  If that fails, the behavior depends on the type of the controlling
terminal. If the terminal is a tty device (i.e. the program accessing
the mailbox was started from the command line), it will ask the user
to supply the missing credentials.  Otherwise it will issue an
appropriate error message and refuse to access the mailbox.

By default, the usual POP3 authentication is used. The @samp{auth=+APOP}
authentication parameter instructs Mailutils to use APOP authentication
instead.

If the server offers the STLS capability, Mailutils will attempt to
establish encrypted TLS connection.  The @samp{notls} parameter
disables this behavior.

@cindex pops, mailbox
@item pops
Remote mailbox accessed using the @dfn{Post Office Protocol}
(@acronym{POP3}).  The transmission channel is encrypted using the
@dfn{transport layer security} (@acronym{TLS}).  The default port is 995.

The URL is:

@example
pops://[@var{user}[:@var{pass}][;auth=+APOP]@@]@var{host}[:@var{port}]
@end example

The meaning of its components is the same as for @samp{pop} type.

@cindex imap, mailbox
@item imap
Remote mailbox accessed via the @dfn{Internet Message Access
Protocol}.  Default port number is 143.

The URL is:

@example
imap://[@var{user}[:@var{pass}]@@]@var{host}[:@var{port}][;notls]
@end example

The @var{host} gives the name or IP address of the host running a IMAP4
server. Optional @var{port} can be used to connect to a port other than
the default 143.

The @var{user} and @var{pass} supply authentication credentials. If any
of them is missing, Mailtils will first try to obtain it from the ticket
file.  If that fails, the behavior depends on the type of the controlling
terminal. If the terminal is a tty device (i.e. the program accessing
the mailbox was started from the command line), it will ask the user
to supply the missing credentials.  Otherwise it will issue an
appropriate error message and refuse to access the mailbox.

If the server offers the STARTTLS capability, Mailutils will attempt to
establish encrypted TLS connection.  The @samp{notls} parameter
disables this behavior.

@cindex imaps, mailbox
@item imaps

The @samp{imaps} type differs in that its transmission channel is
encrypted using the @dfn{transport layer security} (@acronym{TLS}).
The default port is 993.

The URL is:

@example
imaps://[@var{user}[:@var{pass}]@@]@var{host}[:@var{port}]
@end example

The meaning of its components is the same as for @samp{imap} type.
@end table

@node SMTP Mailboxes
@section SMTP Mailboxes
@cindex mailbox, SMTP
@cindex URL, SMTP

SMTP mailboxes types are special remote mailboxes that allow only
append operation.  Appending a message is equivalent to sending it to
the given recipient or recipients. 

@table @asis
@cindex smtp, mailbox
@item smtp
A remote mailbox accessed using the Simple Message Transfer Protocol.

The SMTP URL syntax is:

@example
smtp://[@var{user}[:@var{pass}][;auth=@var{mech},...]@@]@var{host}[:@var{port}][;@var{params}]
@end example

The @var{host} gives the name or IP address of the host running SMTP
server. Optional @var{port} can be used to connect to a port other than
the default 25.

The @var{user}, @var{pass}, and @samp{auth=} elements supply
credentials for ESMTP authentication, if the server supports it.

If the ESMTP authentication is used, Mailutils will select the best
authentication mechanism from the list offered by the server. To force
it to use a particular authentication mechanism, use the @samp{auth}
authentication parameter. Its value is a comma-separated list of
authentication mechanisms, in the order from the most to the least
preferred one, e.g.:

@example
smtp://smith:guessme;auth=cram-md5,digest-md5@@localhost
@end example

Optional @var{params} is a semicolon-separated list of additional
parameters.  Valid parameters are:

@table @asis
@kwindex domain
@item domain=@var{string}
Append @samp{@@@var{string}} to those recipient addresses that lack
the domain part.

@kwindex from
@item from=@var{addr}
Use @var{addr} as sender address.

@kwindex noauth
@item noauth
Disable ESMTP authentication.

@kwindex notls
@item notls
Disable TLS.

@item recipient-headers[=@var{name}[,@var{name}...]]
Use the supplied header names to determine recipient addresses.
When no values are supplied, disables header scanning.

@kwindex strip-domain
@item strip-domain
Strip domain part from all recipient addresses.

@kwindex to
@item to=@var{addr}[,@var{addr}...]
Deliver messages to the supplied email addresses.
@end table

@cindex smtps, mailbox
@item smtps
A remote mailbox accessed using the Simple Message Transfer Protocol, with
the transmission channel encrypted using the @dfn{transport layer
security} (@acronym{TLS}).  The default port is 465.

The URL is

@example
smtps://[@var{user}[:@var{pass}][;auth=@var{mech},...]@@]@var{host}[:@var{port}][;@var{params}]
@end example

See the @samp{smtp} type for a detailed description of its types.
The only difference from @samp{smtp} is that the @samp{notls}
parameter is not used.
@end table

@node Program Mailboxes
@section Program Mailboxes
@cindex mai