submit is a daemon-less mail transfer agent for multi-user Unix systems. In contrast to other MTAs, it moves the configuration of non-local mail delivery away from system administrators and towards the individual users. Notable features are:

  • sendmail(8)-compatible command line interface.

  • Support for SMTP and Sendmail transports: submit can relay mails through smarthosts as well as interface with other sendmail programs (such as those provided by Postfix, Exim or the original Sendmail).

  • Synchronous delivery: When submit returns successfully, you can be sure that your mail is out.

  • SSL/TLS support, including CA- and fingerprint-based validation of the server’s identity and certificate-based authentication.

  • Pluggable interfaces (currently GTK+ and TTY) for authentication.

  • Optional daemon process storing SMTP passwords and passphrases to private keys.

  • Optional support for different delivery methods depending on the sender address selected in the mail client.

1. Introduction

sendmail is the traditional approach to e-mail delivery on Unix systems like GNU/Linux or BSD. It is a program, usually located in /usr/lib or /usr/sbin, that is called by all sorts of mail clients to send messages. These are usually sent on to a daemon process running on the local machine, the so-called “mailer daemon,” which then either directly stores the messages in a local user’s spool file or passes it on to an Internet server for further processing.

While this approach has the advantage of allowing for a central place to configure the mail delivery rules for a whole system, it has its shortcomings in today’s electronic mail environment. The most obvious problem is that users cannot customize sendmail for themselves: If they, for example, want to use their personal Gmail accounts for sending mails from a corporate workstation, there is no way to tell sendmail to do that—this would, in fact, require their system administrator to put their password into a system configuration file in cleartext. These users are stuck with configuring their mail client to bypass sendmail and directly post mails to Gmail’s SMTP server. If they choose to occasionally use another mail client or send mails using command line tools, things can get redundant and confusing.

submit is a sendmail-compatible program which addresses these issues by using a per-user approach. It asks users for their passwords, if necessary, and delivers mails either to local users using the original sendmail program, or to remote mailboxes via an SMTP relay server.

2. Installation

If your operating system has a package management system, please check if a submit package has been provided by someone. If yes, just install the package and skip the rest of this section.

2.1. Manual Installation

If you are not so lucky, please follow these steps.

  1. Install the software needed by submit. Your distribution probably comes with all or most of these.

  2. Grab the latest release of submit from the project homepage and unpack the tarball somewhere.

  3. As root, run python install. This will install the libraries that come with submit to the Python library search path and the submit binary to /usr/bin.

  4. Check if the installation succeeded by typing submit --help. If submit responds by giving you some hints about its usage, everything should be fine.

Then, either configure your mail client to use /usr/bin/submit instead of /usr/lib/sendmail and skip to the next section, or read on.

2.2. Using submit As sendmail

Depending on your system, it might be possible to override the default sendmail binary with the sendmail-compatible program provided by submit (see submit(1)). If you want to do that, please read this section carefully.

Never install submit as /usr/lib/sendmail (or /usr/sbin/sendmail, depending on your system). This leads to very ugly loops when mails are submitted to local users. You do not want cron sending an error mail to root to spawn an infinite number of processes caused by submit piping mails to itself over and over.

Symlinking sendmail to submit is safe, though: If submit detects that the sendmail program it is calling links to something called submit, it will refrain from using this executable. Additionally, a programm called sendmail.notsubmit is checked for before sendmail is tried. Thus, the preferred procedure to use the submit program as sendmail is:

  1. Find out where the original sendmail program is located. This is usually either /usr/lib/sendmail or /usr/sbin/sendmail; one of them could be a symlink to the other. Use ls -l to be sure.

  2. Rename this sendmail file as sendmail.notsubmit.

  3. Recreate the sendmail file as a symbolic link to /usr/bin/submit. The command for this is ln -s /usr/bin/submit /usr/lib/sendmail (replace the last argument, if necessary).

There is a big problem with this approach. If your distribution ships updates to your mail transfer agent, the package manager will overwrite the sendmail program instead of sendmail.notsubmit. You will need to take care not to upgrade your MTA before reverting the above procedure. If your package management system supports the redirection of files, there is an easy way out. This applies at least to users of Debian and its derivatives (like Ubuntu); become root and run

# dpkg-divert --divert /usr/sbin/sendmail.notsubmit /usr/sbin/sendmail

to tell dpkg to redirect attempts to overwrite sendmail to the sendmail.notsubmit file created before. Other distributions might offer similar mechanisms.

3. Getting Started

Basically, submit distinguishes between mails delivered to remote hosts and to local users. In the default setup, both types of mails are passed on to sendmail. This is a reasonable default which ensures that by default, mail delivery works the same regardless of whether submit is installed or not. If you want to customize the transmission rules, you have to provide a configuration file called ~/.submit/config in your home directory. This is a simple example:

# ~/.submit/config example
[method remote]
type = smtp
host =
username = jdoe
starttls = on

This tells submit to hand over non-local mails to the SMTP relay at It will ask you for the password for the user jdoe at least once. Then, the password will be stored in the GNOME keyring, if available; if this doesn’t work, a daemon process will be launched to keep your password for an hour. The starttls line means that Transport Layer Security should be used for encryption; this is strictly recommended.

If you have created your own configuration file following the above pattern, you can test the settings:

$ submit --unlock all

You will be asked to supply your password. If submit returns to the shell without showing an error message after you have done so, sending mails should be no problem, either. If it doesn’t succeed, check your configuration file for typos or read the Configuration section of this manual.

If everything works fine, let’s go on to find out how to tell your mail client to use submit.

3.1. Configuring Mutt

Mutt uses sendmail in its default configuration. If you are using submit as your default sendmail program, don’t do anything. Otherwise, add this to /etc/Muttrc:

set sendmail="/usr/bin/submit -i"

3.2. Configuring Pine Or Alpine

Pine and Alpine use sendmail in their default configuration. If you are using submit as your default sendmail program, don’t do anything. Otherwise, add this to ~/.pinerc:

sendmail-path=/usr/bin/submit -t -i

3.3. Configuring Evolution

To use submit with Evolution, you have to provide sendmail as a symlink to submit as described above. Then, open Edit → Preferences, choose Mail Accounts, select your account, click Edit, activate the Sending Email tab, and choose Sendmail as your Server Type.

3.4. Configuring KMail

Open Settings → Configure KMail and click on the Accounts icon on the left. Choose the Sending tab and click Add…, pick Sendmail and confirm. In the Location field, enter /usr/bin/submit and click OK. Select the newly added entry in the list and click Set Default.

3.5. Configuring Thunderbird Or Icedove

Thunderbird does not support sendmail delivery. This means that you cannot use submit with it at the moment.

3.6. Configuring Sylpheed Or Claws Mail

Sylpheed does not support sendmail delivery. This means that you cannot use submit with it at the moment.

4. Configuration

submit’s default per-user configuration file is ~/.submit/config. Its general structure looks as follows:

# global settings

[method local]
# local delivery settings

[method your_custom_section]
# another delivery settings

[method remote]
# remote delivery settings

All of these sections can be omitted if you are fine with the defaults. Empty lines and lines starting with # are ignored. Each setting is a key = value pair, one per line. The value of a setting can either be a number, a boolean value (on or off), a filename, or some ordinary text. Filenames can either be given absolutely or relatively; in the latter case, they are searched for in ~/.submit.

4.1. Global Settings

default_from (string, default: your local mail address)

The “From:” header to append if there is none. This is very useful together with command line mail clients like mailx (as in the usual one-liners like echo subscribe example-list | mailx to conveniently subscribe to a mailing list).

expire (number; default: 60)

Specifies how many minutes the submit daemon process should store passwords. In reality, the passwords do not vanish from memory after the given time; submit will just ask for the password again after no mails have been sent for that long.

force_daemon (boolean; default: off)

If this flag is set, submit will always launch a daemon process when sending mails. Usually, this will only happen if no GNOME Keyring is available or if submit --daemon is run.

socket (filename, default: ~/.submit/socket)

The file to use for communication between submit and its daemon process. There shouldn’t be many reasons to change this value.

ui (string; default: gnome, gtk, tty)

The user interfaces to consider when asking for passwords or showing error messages. If one of these is not available for some reason (for example, when some Python modules are not installed or when you are working on a virtual console), the next one will be tried.

4.2. Delivery Settings

When delivering mails, all sections starting with the word method will be matched against the “From:” address of the message and its list of recipients. More than one delivery method can match. For example, if you send an e-mail to john, jane@localhost,, in the default configuration, the message will go through the local section for John and Jane, and through remote for Alice and Bob.

local is always tried first to collect all local addresses, remote is checked last and acts as a fallback for all unmatched recipients.

domains (string, default: empty)

If non-empty, this comma-separated list of domains specifies which target domains are handled by this delivery section. In the method local section: Defaults to localhost and your hostname. In the method remote section: Ignored.

extra_domains (string, default: empty)

In the method local section: Comma-separated list of additional domains to be considered local. Use this if you want to add local domains to those automatically determined if you do not explicitly set domains. In all other sections: Ignored.

from (string, default: empty)

If non-empty, only mails with the specified “From:” addresses (comma-separated list) will be considered by this delivery method. Addresses can start with an at sign to match a whole domain. See the Examples section for a typical usage example. In the method remote section: Ignored.

type (string, default: sendmail)

The deliverer to use. This can be one of smtp, smtps or sendmail; see below for a detailled documentation of those.

4.2.1. Sendmail Delivery

program (string, default: /usr/{lib,sbin}/sendmail{.notsubmit,})

Location of the sendmail program. You can specify something like ssh /usr/lib/sendmail here for SMTP-less remote delivery.

arguments (string, default: -oem -oi)

The arguments to use when invoking program. -f envelope-sender is always added to the arguments specified here.

4.2.2. SMTP Delivery

host (string, default: empty)

The name of the host to connect to when delivering mails. If you are using an SMTP server managed by yourself, you should know the value for this setting. For freemail providers, you’ll usually find the information in “help centers.”

password (string, default: empty)

The password to be used with username. You should not set this.

port (number, default: 25)

The port to use. Only change this if your mail provider does not use the default port.

starttls (boolean, default: off)

Encrypt the connection to the SMTP server using Transport Layer Security. Use this whenever possible.

username (string, default: empty)

The username used to authenticate at the SMTP server. If no username is specified, no authentication is attempted. Most of the time, you should enter the part of your mail address before the at sign here.

If you choose to use starttls, these additional options become available:

ca (filename, default: empty)

The certificate authority that has certified the identity of the SMTP server. If this setting points to a valid PEM-encoded X.509 CA certificate file and the certificate sent by the server does not match, mail delivery is aborted. Also setting fingerprint is recommended.

cert (filename, default: empty)

The client certificate to be used for TLS-based authentication.

fingerprint (string, default: empty)

The SHA-1 fingerprint of the server certificate. If this is set and the server certificate does not match, mail delivery is aborted. Also setting ca is recommended.

key (filename, default: empty)

The private key file to be used for TLS-based authentication. The key can be encrypted with DES; you will be asked for the passphrase if needed.

key_passphrase (filename, default: empty)

The passphrase for unlocking key. You should not set this.

4.2.3. SMTPS Delivery

SMTPS delivery is similar to SMTP delivery with a starttls = on setting, but deprecated. If you do not need to use this, please go with smtp and starttls instead.

The options for smtps are the same as for smtp. The only two differences are that the default value for the port option is 465 instead of 25, and that there is no starttls option.

4.3. Examples

4.3.1. A Complete Example

This is the configuration file used by the author. He wants to send his mails through his SMTP server at by default, where he authenticates himself using his TLS private key in ~/.submit/uiae.key. When he sends messages from his old Gmail address, he has to use Google’s servers instead.

default_from =

[method gmail]
from =,
type = smtp
host =
starttls = on
username =

[method remote]
type = smtp
host =
starttls = on
fingerprint = c9:58:6c:bf:b0:96:7f:9e:60:9c:01:7c:6e:3c:50:1d:0f:0a:b0:24
ca = cacert.crt
key = uiae.key
cert = uiae.crt

4.3.2. Calling Sendmail Remotely Over SSH

This is another way how the author could use submit: This remote delivery method connects to his mail server and feeds the message to the /usr/sbin/sendmail binary provided by the Postfix installation.

[method remote]
type = sendmail
program = ssh /usr/sbin/sendmail

5. References

6. Author

submit is Copyright © 2008 Michael Schutte.

Please write to if you have comments or suggestions regarding submit itself or this documentation.

Patches are always appreciated. Development takes place in Git, you can find the repositories on Github or (gitweb only).