![[MU Poststamp]](/graphics/mustamp.png)
|
|
GNU Mailutils |
General-Purpose Mail Package |
Official GNU Software |
GNU Mailutils Manual (split by section): 
The mailutils utility is a multi-purpose tool shipped with
Mailutils. It can be used for various mail and database-related
tasks, as well as an auxiliary tool for compiling and linking programs
with Mailutils.
Mailutils is a command line tool. Its invocation syntax is:
mailutils [options] command [args]
where options are options that affect the behavior of
mailutils as a whole, command instructs it what it is to do
and args are any arguments the command needs in order to be
executed.
The commands are:
Decodes or encodes email message headers.
Tests Mailutils access control lists.
Shows compiler options needed to compile with Mailutils.
Invokes a DBM management tool.
Applies a chain of filters to the input.
Displays a terse help summary.
Invokes an IMAP4 client shell (in development).
Displays information about Mailutils compile-time configuration.
Constructs a ld(1) command line for linking a program with Mailutils.
Logs information using Mailutils log facility.
Invokes a POP3 client shell.
Queries configuration values.
Scans wicket for matching URLs
The mailutils help command lists all available options and command
names along with short descriptions of what each of them does. It is
similar to the mailutils --help option.
A command name can be supplied as an argument to
help, in which case it will display a help page for that
particular command, e.g.:
mailutils help ldflags
will output help for the ldflags command. It is synonymous
to the --help option used with that particular command, e.g.:
mailutils ldflags --help.
The mailutils info command displays information about Mailutils
compile-time configuration. In normal form its output lists a single
configuration flag per line, e.g.:
$ mailutils info VERSION=2.99.93 SYSCONFDIR=/etc MAILSPOOLDIR=/var/mail/ SCHEME=mbox LOG_FACILITY=mail IPV6 USE_LIBPAM HAVE_LIBLTDL WITH_GDBM WITH_GNUTLS WITH_GSASL
A configuration flag can consist either of a single word, indicating that a particular capability has been enabled at compile time, or of a keyword/value pair delimited by an equal sign, which indicates a particular value used by default for that feature. For example, ‘IPV6’ means that Mailutils was compiled with support for IPv6, whereas ‘SYSCONFDIR=/etc’ means that the default place for configuration files is in /etc directory.
Such short output is convenient for using mailutils info in scripts
to decide whether it is possible to use a given feature. To assist
human users, the --verbose (-v) option is provided.
It prints a short description next to each flag:
$ mailutils info --verbose VERSION=2.99.93 - Version of this package SYSCONFDIR=/etc - System configuration directory MAILSPOOLDIR=/var/mail/ - Default mail spool directory SCHEME=mbox - Default mailbox type LOG_FACILITY=mail - Default syslog facility IPV6 - IPv6 support USE_LIBPAM - PAM support HAVE_LIBLTDL - a portable `dlopen' wrapper library WITH_GDBM - GNU DBM WITH_GNUTLS - TLS support using GNU TLS WITH_GSASL - SASL support using GNU SASL
The mailutils cflags command shows compiler options needed to
compile a C source with Mailutils. It is intended for use in
configuration scripts and Makefiles, e.g.:
CFLAGS=-g -O2 `mailutils cflags`
The mailutils ldflags command is a counterpart of cflags
which is used for linking. It constructs a ld command line
for linking a program with Mailutils.
When used without arguments, it outputs ld arguments which
would link only with the core Mailutils library libmailutils, e.g.:
$ mailutils ldflags -L/usr/local/lib -lmailutils
This command accepts a number of keywords which allow to select a particular subset of Mailutils libraries to link with. In particular, the argument ‘all’ instructs it to link in all available libraries:
$ mailutils ldflags all -L/usr/local/lib -lmu_mbox -lmu_mh -lmu_maildir -lmu_imap -lmu_pop \ -lmu_mailer -lmu_compat -lmailutils -lmu_auth -lgsasl -lgnutls -lgcrypt \ -lldap -lgnuradius -lpam -ldl
Other available keywords are:
Link in the UNIX mbox format support.
Link in the MH format support.
Link in the Maildir format support.
Link in the IMAP protocol support.
Link in the POP protocol support.
Enable support for mailers.
Link in the support for Sieve mail filtering language.
Link in the support for DBM databases (libmu_dbm library).
Link in the Mailutils authentication library.
Provide Guile language bindings.
Provide Python language bindings.
The command mailutils stat shows status of a mailbox. The
name or URL of the mailbox to operate upon is supplied in the first
argument. If not given, the command will display status of the
invoking user system mailbox.
$ mailutils stat type: maildir path: /var/mail/smith URL: /var/mail/smith size: 3498 messages: 24 recent messages: 3 first unseen: 20 uidvalidity: 1338543026 next uid: 87 access: 2016-12-15 09:15:08 +0200
The output format is controlled by the --format (-c) option. Its argument is the desired format string, composed of ordinary characters, which are reporduced on standard output verbatim, backslash sequences, and format specifiers, beginning with ‘%’.
Backslash sequences are interpreted as in C.
A format specifier consists of a leading ‘%’ followed by a letter. Optional ‘:’ may occur between ‘%’ and the letter. Its presense instructs the program to print the description of the corresponding value before the value itself.
The following format sequences are understood:
Name of the mailbox as supplied in the command line. If
mailutils stat was used without explicit mailbox argument,
‘%f’ is equivalent to ‘%U’.
Type of the mailbox (‘mbox’, ‘maildir’, etc.). The description string is ‘type’.
Path to the mailbox. In case of remote mailboxes, it is the path part of the mailbox URL. Description string: ‘path’.
URL of the mailbox. Description string: ‘URL’.
Size of the mailbox in octets. Description string: ‘size’.
Number of messages in the mailbox. Description string: ‘messages’.
Number of recent (unread) messages in the mailbox. Description string: ‘recent messages’.
Index of the first unseen message. Description string: ‘first unseen’.
The UIDVALIDITY value. Description string: ‘uidvalidity’.
The UID value which will be assigned to the new message to be incorporated into the mailbox. Description string: ‘next uid’.
Access time of the mailbox, as a number of seconds since the epoch.
Access time of the mailbox in human-readable format.
The mailutils query command queries values from Mailutils
configuration files. It takes one or more configuration paths
(see Paths) as its arguments. On output, it displays the values
it found, each value on a separate line. If the requested value is a
block statement it is displayed in full. For example, if main
configuration file contained:
logging {
syslog yes;
facility mail;
}
Then:
$ mailutils query .logging.syslog
syslog yes;
$ mailutils query .logging.syslog .logging.facility
syslog yes;
facility mail;
$ mailutils query .logging
logging {
syslog yes;
facility mail;
};
Several command line options allow to modify output format. The --value option instructs the command to output only values:
$ mailutils query --value .logging.syslog yes
The --path option instructs it to print full pathnames for each value:
$ mailutils query --path .logging.syslog logging.syslog: yes
The --program option instructs mailutils to behave as if
it was called under another program name. For example, the following
command:
$ mailutils query --program=pop3d .server.transcript
will return the value of the ‘.server.transcript’ statement which
the pop3d utility would see.
By default, mailutils query operates on the main configuration
file. Another configuration file can be supplied using the
--file (-f) option:
$ mailutils query --file /usr/local/etc/file.conf .pidfile
The mailutils 2047 command is a filter for decoding or encoding
email message headers formatted in accordance with RFC 2047 (see
http://www.faqs.org/rfcs/rfc2047.html. By default, it operates
in encode mode and assumes the ‘iso-8859-1’ encoding. If
arguments are supplied in the command line, they are treated as the
text to operate upon. Otherwise the command acts as a UNIX filter,
reading lines from the standard input and printing results on the
standard output.
For example:
$ mailutils 2047 'Keld Jørn Simonsen <keld@dkuug.dk>' =?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= <keld@dkuug.dk>
The decode mode can be requested via the --decode (-d) option:
$ mailutils 2047 --decode '=?ISO-8859-1?Q?Keld_J=F8rn_Simonsen?= \ <keld@dkuug.dk>' Keld Jørn Simonsen <keld@dkuug.dk>
The --charset (-c) option changes the default character set. It is meaningful both in decode and in encode modes. In decode mode it instructs the utility to convert the output to the given character set. In encode mode it indicates the encoding of the input data, which will be reflected in the resulting string:
$ mailutils 2047 --charset=utf-8 'Keld Jørn Simonsen <keld@dkuug.dk>' =?utf-8?Q?Keld J=C3=B8rn Simonsen <keld@dkuug.dk>?=
The --encoding (-E) option can be used in encode mode to change the output encoding. Valid arguments for this option are: ‘quoted-printable’ (the default) or ‘base64’.
The --newline (-n) option prints an additional newline character after each line of output.
The mailutils filter command applies a chain of filters to the
input. The filters to apply and their arguments are given
in the command line. The full invocation syntax is:
mailutils filter [option] filter-chain
The syntax for filter-chain in Backus-Naur form follows:
<filter-chain> ::= <filter> | <filter-chain> "+" <filter> <filter> ::= <filter-spec> <ARG>* <filter-spec> ::= <WORD> | "~" <WORD>
where <WORD> stands for the filter name and <ARG> represents filter arguments. To obtain a list of known filter names, run:
mailutils filter --list
Filters are applied in the order of their appearance, from left to right and operate in encode mode. The plus sign has the same meaning as pipe in shell. The default mode can be changed using the --decode (-d) and --encode (-e) options. Whatever the default mode is, a ‘~’ character before filter name reverts the mode for that filter alone.
For example, to encode the contents of file file.txt in Base64 run:
mailutils filter base64 < file.txt
To convert it to base64 and use CRLF as line delimiters, run:
mailutils filter base64 + crlf < file.txt
The following command will decode the produced output:
mailutils filter --decode crlf + base64
It can also be written as
mailutils filter ~crlf + ~base64
The following example converts the input from ISO-8859-2 to UTF-8, quotes eventual ‘From’ occurring at the beginning of a line, encodes the result in Base64 and changes line delimiters to CRLF:
mailutils filter iconv iso-8859-2 utf-8 + from + base64 + crlf
This final example removes UNIX-style comments from the input and joins continuation lines:
mailutils filter --decode inline-comment -S '#' + linecon
Such invocation can be useful in shell scripts to facilitate configuration file processing.
The mailutils acl command tests Mailutils Access Control Lists. By
default it reads ACL from the Mailutils configuration file section
‘acl’. The command takes a list of IP addresses as its
arguments, applies the ACL to each of them in turn and prints the result.
To select the ACL to test, two options are provided. The --file (-f) option supplies the name of configuration file to read instead of the default one. The --path (-p option supplies the pathname (see Paths) of the ACL section to use instead of the default ‘.acl’. For example, to test ACL in section ‘server 213.130.1.232’ of file /etc/pop3d.conf use:
mailutils acl --file=/etc/pop3d.conf \
--path=/server="213.130.1.232"/acl address
As an example of its use, consider file test.conf with the following contents:
acl {
deny from 10.10.10.1;
deny from 10.10.1.0/24;
log from any "Connect from ${address}";
allow from 10.0.0.0/8;
allow from 192.168.1.0/24;
deny from any;
}
Then, running mailutils acl --file=test.conf 127.0.0.1 you will get:
Testing 127.0.0.1: mailutils: Connect from 127.0.0.1 127.0.0.1: deny
More examples:
$ mailutils acl --file=test.conf 127.0.0.1 10.10.10.1 \
10.10.1.3 10.5.3.1 192.168.1.0 192.168.2.0
Testing 127.0.0.1:
mailutils: Connect from 127.0.0.1
127.0.0.1: deny
Testing 10.10.10.1:
10.10.10.1: deny
Testing 10.10.1.3:
10.10.1.3: deny
Testing 10.5.3.1:
mailutils: Connect from 10.5.3.1
10.5.3.1: accept
Testing 192.168.1.0:
mailutils: Connect from 192.168.1.0
192.168.1.0: accept
Testing 192.168.2.0:
mailutils: Connect from 192.168.2.0
192.168.2.0: accept
The mailutils option --debug-level will give you a deeper
insight into the address matching algorithm:
$ mailutils --debug-level=acl.trace9 acl --file test.conf 127.0.0.1
Testing 127.0.0.1:
mailutils: Checking sockaddr 127.0.0.1
mailutils: 1:deny: Does 10.10.10.1/255.255.255.255 match 127.0.0.1? no;
mailutils: 2:deny: Does 10.10.1.0/255.255.255.0 match 127.0.0.1? no;
mailutils: 3:log: Does any match 127.0.0.1? yes;
mailutils: Expanding "Connect from ${address}";
mailutils: Expansion: "Connect from 127.0.0.1";.
mailutils: Connect from 127.0.0.1
mailutils: 4:accept: Does 10.0.0.0/255.0.0.0 match 127.0.0.1? no;
mailutils: 5:accept: Does 192.168.0.0/255.255.0.0 match 127.0.0.1? no;
mailutils: 6:deny: Does any match 127.0.0.1? yes;
127.0.0.1: deny
See acl.
The mailutils wicket command looks up matching URLs in the
Mailutils ticket file (by default, ~/.mu-tickets) and prints
them. The URLs to look for are supplied in the command line.
Consider the following ticket file as an example:
smtp://foo:bar@* smtp://bar:baz@gnu.org *://baz:qux@* *://quux:bar@gnu.org
Now, running mailutils wicket smtp://bar@gnu.org will show:
smtp://bar@gnu.org: /home/user/.mailutils-tickets:2
(where user is your login name). This means that this URL
matches the line 2 in your .mailutils-tickets file. The
wicket command does not show the actual matching line to
avoid revealing eventual security-sensitive information. You can
instruct it to do so using the --verbose (-v)
option:
$ mailutils wicket -v smtp://bar@gnu.org smtp://bar@gnu.org: /home/user/.mu-tickets:2: smtp://bar:***@gnu.org
As you see, even in that case the tool hides the actual password part
by replacing it with three asterisks. If you are working in a secure
environment, you can tell mu wicket to show passwords as
well, by supplying the -v option twice.
A counterpart of --verbose is the --quite
(-q) option, which instructs wicket to suppress any
output, excepting error messages. This can be used in scripts, which
analyze the mailutils wicket exit code to alter the control flow.
The mailutils wicket tool exits with code 0 if all URLs were
matched and with code 1 if some of them were not matched in the ticket
file. If an error occurred, the code 2 is returned.
The mailutils dbm tool manages DBM files using libmu_dbm
The invocation syntax is:
mailutils dbm subcommand [options] file [keys]
or
mailutils dbm [options] subcommand file [keys]
where subcommand selects the operation mode, options modify the tool behavior and file specifies the DBM file to operate upon. Some commands allow for optional keys to be specified.
The file argument can be either a DBM file name or a Database URL.
The create subcommand and its synonym load instruct the tool to create a new database:
mailutils dbm create file.db
If the argument file already exists, it will be truncated prior to adding new records to it.
The data to populate the database with are read from the standard
input. The mailutils dbm command supports several formats for
these data, which are discussed later. In the simplest case (a so
called ‘format 0.0’) each input line must consist of two fields
separated by any amount of whitespace. The first field is treated as
a key and the second one as the corresponding value.
The usual way to read data from a file is, of course, by redirecting the file to the standard input as in:
mailutils dbm create file.db < input.txt
There is also a special option for that purpose: --file (-f). Thus, the following command is equivalent to the one above:
mailutils dbm create --file input.txt file.db
The --file option has the advantage that it allows, in conjunction with another options, for copying input file metadata (owner UID, GID and file mode) to the created database. For example, the following command ensures that the created database file will have the same metadata as the input file:
mailutils dbm create --file input.txt --copy-permissions file.db
The --copy-permissions (-P) option is the one that does the job.
There are also other ways to control mode and ownership of the created database, which are described below.
More advanced dump formats (e.g. ‘version 1.0’ format) carry additional information about the file, including its original name, ownership and mode. If input is in one of these formats, the file name argument becomes optional. If it is not supplied, the name stored in the input stream will be used. For example, supposing that the file users.dump is in format 1.0, the following command suffices to restore the original filename, ownership, mode and, of course, data:
mailutils dbm create --file users.dump
The add subcommand adds records to a database. Records are read from the standard input and must be formatted as for create:
mailutils dbm add file.db
If the argument file does not exist, it will be created.
Adding a record with a key which is already present in the database produces an error. To replace existing records, use the replace subcommand instead.
The same options that affect the behavior of create apply to add and ‘replace’ as well, e.g.:
mailutils dbm replace --file input.txt --copy-permissions file.db
To delete records, use the delete subcommand. It reads a list of keys to delete to be specified as arguments in the command line:
mailutils dbm delete file.db foo bar
The command above will delete from file.db records with keys ‘foo’ and ‘bar’.
It is not an error to attempt to delete a key that does not exist in the database, although such use will produce a warning message.
By default, keys are matched literally. It is also possible to use various pattern matching techniques, depending on the option specified.
The --glob (-G) option instructs the tool to use UNIX globbing pattern matching. For example, the command below will delete all keys starting with ‘foo’ and ending with a decimal digit:
mailutils dbm delete file.db 'foo*[0-9]'
(note the quoting necessary to prevent shell from interpreting the metacharacters itself).
Another option, --regex (-R) instructs mailutils
to treat supplied keys as extended regular expressions:
mailutils dbm delete --regex file.db 'foo.*[0-9]{1,3}'
Both options are affected by the --ignore-case (-i) option, which turns on case-insensitive matching.
Using pattern matching to delete records can be a risky operation as selecting a wrong pattern will lead to removing wrong records. It is recommended to first use the list mode described below to verify that the patterns match the right keys.
The list command lists the content of the database:
mailutils dbm list file.db
By default, entire content is listed on the standard output.
If supplied more than one command line argument, this mode treats the rest of arguments after the database file name as the keys to look for and lists only records with these keys:
$ mailutils dbm list file.db foo bar foo 1 bar 56
The --glob and --regex options instruct the tool to use UNIX globbing or extended regular expression matching, correspondingly. These were described in detail above.
The dump subcommand dumps the database to the standard output in a format suitable for backup or sending over the network (a version 1.0 format).
mailutils dbm dump file.db < file.dump
The produced file is suitable for input to the create (load) command. Among other uses, it provides an easy way to convert databases between various formats supported by Mailutils. For example this is how to convert the database file file.db to the GDBM database new.db:
mailutils dbm dump file.db | mailutils dbm create gdbm://new.db
Both list and dump subcommands share the same set of options. In fact, they are pretty similar, except that use different defaults. The list subcommand is designed to produce a human-readable output, whereas the dump subcommand is oriented towards backup purposes.
As of version 3.14, mailutils dbm supports two formats
for dumping DBM databases. Both formats are line-oriented. Comments
are introduced with a sharp (‘#’) sign in the column 0 of a line,
followed by at least one white space character (space or tab). Sharp
sign followed by a colon (‘#:’) introduces a pragmatic
comment, which carries some additional information to the loader.
The version 0.0 format is suitable for databases whose records contain only ASCII data. In this format, each record occupies a separate line, which consists of the key and value separated by a single TAB character. Empty lines are ignored. For example:
$ mailutils list /etc/mail/users.db root guessme smith pAssword qed fooBar
The output in version 0.0 format is human readable and can be used as input to the popauth utility (see popauth. However, version 0.0 has serious drawbacks. First of all, it is not suitable for databases that contain binary data. Secondly, it cannot properly handle keys beginning with a sharp sign or containing TAB. The version 1.0 format is free from these drawbacks.
The version 1.0 dump format begins with a header
containing important information about the file, such as its file
name, ownership and file mode. This information is stored in
pragmatic comments and allows mailutils dbm load to easily recreate
an exact copy of the file. The following comments are defined:
Indicates that the data that follow are in version 1.0 format.
Original database file name, without directory parts.
Owner UID.
Owner name.
Owner GID
Owner group name.
File mode in octal
Following this header are actual data. Each record is output in two parts: key and value. Each part begins with a ‘#:len=n’ construct on a line by itself, where n is the length of the data in decimal. This line is followed by one or more lines of the actual data, encoded in base64. The data are formatted so that each line does not exceed 76 bytes in length (not counting the terminating newline). An example of this format follows:
# Database dump file created by GNU Mailutils 2.99.93 on # Tue Nov 1 13:28:03 2011 #:version=1.0 #:file=users.db #:uid=0,user=root,gid=25,group=mail,mode=640 #:len=6 c21pdGgA #:len=9 cEFzc3dvcmQA #:len=5 cm9vdAA= #:len=8 Z3Vlc3NtZQA= #:len=4 cWVkAA== #:len=7 Zm9vQmFyAA==
The table below summarizes exit codes used by mailutils dbm:
| Code | Symbolic name | Meaning |
|---|---|---|
| 0 | EX_OK | Successful termination |
| 64 | EX_USAGE | Command line usage error |
| 65 | EX_DATAERR | Error in user-supplied data: the input file is badly formatted, or some of the data supplied in the command line are invalid (e.g. user name, uid or the like), etc. |
| 66 | EX_NOINPUT | Cannot open input file |
| 67 | EX_NOUSER | No such user or UID when trying to set output file ownership |
| 69 | EX_UNAVAILABLE | Operation cannot be performed due to some kind of problem (e.g. access to the file denied, etc.) |
| 70 | EX_SOFTWARE | Internal software error |
| 74 | EX_IOERR | Input/output error |
The mailutils logger tool logs information using Mailutils log facility.
Syntax:
mailutils logger [options] [message]
The message argument, if supplied, gives the text to log. If not supplied, the utility reads lines of text from standard input or a file (if the --file option is given) and sends them to log:
# Send text to log $ mailutils logger I am here # Log each line from file.txt $ mailutils logger --file file.txt # Read stdin and log it: $ mailutils logger
The default logging channel is bound to standard error. To bind it to
syslog, use the --syslog command line option. In that case
mailutils uses facility ‘user’ and priority ‘err’. You
can change this by using the --priority (-p) option.
Its argument is either a syslog facility name or facility and severity
names separated by a dot. For example, the following invocation will use
facility ‘auth’, severity ‘info’:
mailutils logger --priority auth.info
The syslog tag can be set using the --tag (-t) option:
mailutils logger --tag myprog
The default tag is ‘mu-logger’.
The --severity (-s) option sets the Mailutils severity level. Its argument can be any of the following: ‘debug’, ‘info’, ‘notice’, ‘warning’, ‘error’, ‘crit’, ‘alert’, ‘emerg’.
Finally, the --locus (-l) option binds log messages to a location in a file. Its argument has the following syntax:
file:line[:col]
where file is the file name, line is the line number and optional col is the column number in that file.
For example, the following invocation:
mailutils logger --locus mailutils.conf:34 Suspicious statement
will send the following to the log:
mu-logger: mailutils.conf:34: Suspicious statement
The mailutils pop command invokes an interactive POP3 client shell.
It reads commands from the standard input, executes them and displays
the results on the standard output. If the standard input is
connected to a terminal, the readline and history facilities are
enabled (provided that Mailutils is configured with GNU Readline).
The mailutils pop commands form two major groups. POP3 protocol
commands interact with the remote POP3 server and display responses
obtained from it. These commands are named after their POP3
equivalents. Another group, internal commands, are used to
configure the shell itself.
Open connection to hostname. If the -tls option is given, TLS encryption (also known as POPS protocol) will be used. If port argument is not given, the command uses port 110 for a plain POP connection or 995 for POPS (if -tls is given).
Start TLS negotiation. This command is valid only after successful
unencrypted connection has been initiated (using connect
without -tls argument).
Send user name to the server. The pass command must follow.
Send password. This command is valid only after user. If
the password argument is omitted, the shell will ask you to
enter it. While entering, both echoing and history recording will be
disabled. Use this to avoid compromising your password.
Authenticate with APOP. If the password argument is omitted, you will be asked to supply it. While entering, both echoing and history recording will be disabled.
List server capabilities. Any number of arguments is accepted. If given, the shell will display only the named capabilities, otherwise it displays entire list. By default capa reuses the response of its previous invocation (if there was any), instead of resending the ‘CAPA’ command to the server. To force it do so, use the -reread option.
Send a ‘NOOP’ (no operation) command to the server.
Get the mailbox size and number of messages in it.
Shows unique message identifiers. Without arguments, shows identifiers for each message in the mailbox. If number is given, the command returns the UIDL of that particular message only.
Lists messages. See above for the meaning of number. Each line
of the produced listing contains describes a single message and
contains at least the message number and size in bytes. Depending on
the POP3 server implementation, additional fields may be present. For
example, Mailutils pop3d can also output number of lines in
the message in the additional third field.
Retrieve a message.
Display message headers and first number (default 5) of lines of its body.
Mark message for deletion.
Remove deletion marks.
Quit pop3 session.
Close existing connection.
Control output verbosity. Without arguments the verbose
command shows current settings.
The argument ‘off’ (the default) turns off all additional output. The ‘verbose on’ command enables POP3 protocol tracing output. Additional arguments can be used to provide more verbosity. The ‘secure’ argument enables display of user passwords in the trace output and the ‘payload’ argument enables showing payload data (e.g. response body sent in the reply to ‘RETR’ command, etc.) Thus, the full diagnostics output is obtained by
verbose on secure payload
The ‘mask’ and ‘unmask’ arguments allow to disable and enable such additional verbosity. For example, supposing the command above is in action, the following command will suppress the display of user passwords in the traces:
verbose mask secure
Similarly, verbose unmask secure will turn it back again.
Set command prompt. The argument can contain variable references in any of the following forms:
$name
${name}
where name is the variable name. Such references are expanded to the actual value of the variable at the time of expansion. The following variables are defined:
| Variable | Expansion |
|---|---|
| user | Login name of the authenticated POP3 user. If the session is not authenticated yet, expands to ‘[nouser]’. |
| host | Name of the remote host, or ‘[nohost]’ if no connection is established. |
| program-name | Name of the program, as typed on the command line to invoke it. |
| canonical-program-name | ‘mailutils’ |
| package | ‘Mailutils’ |
| version | Mailutils version number (3.14) |
| status | Session status. One of: ‘disconnected’, ‘connected’ or ‘logged in’. |
For example:
prompt "[${user}@$host "
Notice the use of quotes to include the space character in the prompt.
Exit the program.
Without arguments displays a list of commands with possible arguments and short descriptions.
With one argument, displays a terse description for the given command.
Shows command history.
The mailutils imap command invokes an interactive IMAP4 client
shell. It reads commands from the standard input, executes them and
displays the results on the standard output. The shell is similar to
the mailutils pop (see mailutils pop) shell.
Most commands in this group correspond (with minor differences) to IMAP commands described in RFC 35015.
Opens connection to the server host. If the -tls option is given, TLS encryption (also known as IMAPS protocol) will be used. If port argument is not supplied, the command uses port 143 for a plain IMAP connection or 993 for IMAPS (if -tls is given).
Lists server capabilities. Any number of names is accepted. If
at least one is given, the shell will display only the named
capabilities, otherwise it displays the entire list. By default,
capability reuses the response of its previous invocation
(if there was any), instead of resending the CAPABILITY command to the
server. To force it do so, use the -reread option.
Starts TLS negotiation. This command is valid only after unencrypted connection has been successfully initiated using connect without the -tls option.
Logs in to the server as user with optional password. If the pass argument is omitted, the shell will ask you to enter it. While entering, both echoing and history recording will be disabled. Use this to avoid compromising your password.
Quits the imap session.
Sends IMAP ID command. See RFC 29716, for a discussion of arguments. By default, this command outputs entire ID list. If, however, the -test option is given, it will check whether the keyword kw is defined and display its value if so.
Requests a server checkpoint.
Selects the named mailbox. Without argument, selects ‘INBOX’.
Examines the named mailbox, i.e. selects it in read-only mode. If mbox is not given, ‘INBOX’ is assumed.
Gets mailbox status. Valid keywords (kw arguments) are: ‘MESSAGES’, ‘RECENT’, ‘UIDNEXT’, ‘UIDVALIDITY’, and ‘UNSEEN’. Keywords are case-insensitive.
Fetches message data. See RFC 3501, section 6.4.57, for a discussion of its arguments.
Alters mailbox data. See RFC 3501, section 6.4.68, for a discussion of its arguments.
Closes the currently selected mailbox (with expunge).
Closes the currently selected mailbox (without expunge).
Deletes the mailbox mbox.
Renames existing mailbox old-name to new-name.
Permanently removes messages marked for deletion.
Creates new mailbox with the given name.
Reads an RFC-822 message from file and appends it to the mailbox. Use the -time option to supply envelope date for the message. Use the -flag option to supply message flags. For example:
append -time "25-Aug-2002 18:00:00 +0200" -flag \Seen INBOX input.msg
Lists matching mailboxes. See RFC 3501, section 6.3.89, for a discussion of its arguments.
Lists subscribed mailboxes (RFC 3501, section 6.3.910).
Subscribes to a mailbox.
Removes mailbox mbox from the subscription list.
Sends a no operation command.
Closes existing connection.
The imap shell implements the same set of internal commands as
pop shell: See Internal commands. There is
only one imap-specific internal command:
Controls the UID mode. When the UID mode is on, the commands
fetch and store operate on and return message UIDs
instead of their sequence numbers.
To examine the current state of the UID mode, issue the uid
command without arguments.
Reads an RFC-822 message from a file and sends it over to a specified SMTP server. The syntax is:
mailutils send [options] host file
where host defines the SMTP server through which to send the message, and file is the name of the input file containing the message. For example, to send a message from file input.msg using SMTP service at localhost, one would write:
$ mailutils send localhost input.msg
The host argument can be an IP address, hostname, or a valid SMTP URL.
The following command line options are understood:
Supplies envelope sender address.
Supplies envelope recipient address. It can be specified multiple times.
Instructs the program to read recipient email addresses from the message ‘To:’, ‘Cc:’, and ‘Bcc:’ headers.
The mailutils smtp command invokes an interactive SMTP client
shell. It reads commands from the standard input, executes them and
displays the results on the standard output. If the standard input is
connected to a terminal, the readline and history facilities are
enabled (provided that Mailutils is configured with GNU Readline).
Connects to SMTP server at host (IP address or host name). If the -tls option is given, TLS encryption (also known as SMTPS protocol) will be used. The default port number is 25 for plain SMTP and 465 for SMTPS. Explicit port argument overrides the default value.
A number of parameters is associated with an open connection:
Domain name used in EHLO statement. Defaults to the current host name.
The following parameters are used for ESMTP authentication:
User name.
User password.
GSASL service name.
Realm name.
Host name.
SMTP URL. It can contain all of the above. Default is smtp://
These parameters are manipulated using the following statements:
Sets parameter param to value. Several parameters can be
set with one set statement.
Unset the supplied connection parameters. If used without arguments, unsets all parameters.
Lists the values of the connection parameters. If used without arguments, lists all parameters.
Sends the ESMTP greeting. Unless domain is supplied, the connection parameter ‘domain’ is used.
Lists the server capabilities.
Initiates encrypted connection. This command is disabled if the connection is opened with the -tls option.
Authenticate using the supplied mechanisms.
Reset the session state.
Sets sender email address. If used without arguments, prints the sender email address.
Sets recipient email address. If used without arguments, prints all recepient names collected so far.
Sends the command with its arguments verbatim.
Quits the SMTP session.
Reads the message from file and sends it. If file is not
supplied, the action depends on whether a send command was used
prevously within the same session. If so, mailutils will
first ask whether to reuse the already supplied message. If not, it
will start an editor, allowing you to enter the new message. When you
exit from the editor, you will be prompted what to do with the
message: send, edit, or quit (discard) it.
Internal commands are the same as in pop shell: See Internal commands.
This command fixes attributes and UID assignments in ‘maildir’ mailboxes created by mailutils versions prior to 3.10.90.
Attribute flags used in ‘maildir’ mailboxes by these versions of
mailutils were a bit different from those described in the original
description of the ‘maildir’ format11
and those used by another implementations. The discrepancy has been
reported in the Mailutils bug tracker12
and was fixed in version 3.10.90. Along with this fix, measures has
been taken to ensure persistence of UID assignments between different
sessions. Starting from version 3.10.90, whenever mailutils
library opens a maildir mailbox, it determines the version that
created it. If the mailbox is writable and the library determines
that the mailbox is affected by the two problems described above, it
fixes the mailbox on the fly. This process is completely transparent
to the user.
If you operate a site with a large number of mailboxes in
‘maildir’ formats, you may choose to fix up all of them at once.
That’s what the maildir_fixup command is for. It takes one
or more directory names as its arguments and recursively scans these
directories in search for ‘maildir’ mailboxes. Each mailbox
found is analyzed and a fix-up is performed, if necessary. If a
mailbox is already in the new format, it remains untouched.
The following options modify the program’s behavior:
List each maildir name before processing it.
Don’t touch maildirs, just print their names,
The maildir_fixup tool reads main mailutils configuration
file by default. It looks for program-specific settings in the
section ‘program maildir_fixup’. If the include statement
is present that has a directory name as its argument, the file
maildir_fixup is looked up in that directory and parsed, if
present.
The program uses the following configuration statements:
| Statement | Reference |
|---|---|
| debug | See debug statement. |
| locking | See locking statement. |
| mandatory-locking | See mandatory-locking statement. |
See http://www.faqs.org/rfcs/rfc3501.html.
http://www.faqs.org/rfcs/rfc2971.html
http://tools.ietf.org/html/rfc3501#section-6.4.5
http://tools.ietf.org/html/rfc3501#section-6.4.6
http://tools.ietf.org/html/rfc3501#section-6.3.8
http://tools.ietf.org/html/rfc3501#section-6.3.9
http://cr.yp.to/proto/maildir.html
GNU Mailutils Manual (split by section):
This document was generated on January 2, 2022 using makeinfo.
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.