<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>submit</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"/><link rel="home" href="#submit" title="submit"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

Copyright 1998 - 2009 S. Varshavchik.  See COPYING for distribution
information.

--></head><body><div class="refentry"><a id="submit" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>submit — Submit a new message to the <span class="application">Courier</span> mail server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">@bindir@/submit</code>  [-expn=<em class="replaceable"><code>address</code></em>] [-vrfy=<em class="replaceable"><code>address</code></em>] [-vhost=<em class="replaceable"><code>address</code></em>] [-bcc] [-delay=<em class="replaceable"><code>n</code></em>] [-rfc3848=<em class="replaceable"><code>type</code></em>] {module} {"<em class="replaceable"><code>type</code></em>; <em class="replaceable"><code>hostid</code></em>"}</p></div></div><div class="refsect1"><a id="submit_description" shape="rect"> </a><h2>DESCRIPTION</h2><p>
The <span class="command"><strong>submit</strong></span> program submits messages to the
<span class="application">Courier</span> mail server for processing.
The <span class="command"><strong>submit</strong></span> program is not intended to be invoked by the
end user.
It is used by the <span class="application">Courier</span> mail server
input modules only. The <span class="command"><strong>submit</strong></span> program's
global read and execute permissions are turned off, so that it can only be
executed by a process that's a member of the <code class="literal">@mailgroup@</code>
group.
<span class="command"><strong>submit</strong></span> is installed in the
<code class="filename">@libexecdir@/courier</code>
directory.</p><p><span class="command"><strong>submit</strong></span> always takes two command line arguments after any
options:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">module</span></dt><dd><p>
This argument identifies the module that's running
the <span class="command"><strong>submit</strong></span> command. It must be one of the module names that
the <span class="application">Courier</span> mail server knows about,
such as <code class="literal">local</code>, or <code class="literal">esmtp</code>.
This argument determines address rewriting rules.</p></dd><dt><span class="term">"<em class="replaceable"><code>type</code></em>; <em class="replaceable"><code>hostid</code></em>"</span></dt><dd><p>
This single argument identifies the source
of the message, and must be suitable for the Remote-MTA: header in
delivery status notifications, as specified by RFC 1894. For messages that
are received via ESMTP, this argument is typically "<code class="literal">dns; helohost
(hostname [ip.address])</code>".</p></dd></dl></div><p>
The <span class="command"><strong>submit</strong></span> program takes the following options:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">-expn=<em class="replaceable"><code>address</code></em></span></dt><dd><p>
Do not accept a message, instead "expand"
the given address. If the specified address matches a locally-defined
alias, <span class="command"><strong>submit</strong></span> prints the addresses this address expands to.
If the specified address does not match a locally-defined alias, the
address is displayed by itself.
</p></dd><dt><span class="term">-vrfy=<em class="replaceable"><code>address</code></em></span></dt><dd><p>
Do not accept a message, instead verify the
given address. <span class="command"><strong>submit</strong></span> prints a suitable message and sets the
exit code to indicate whether the specified address is valid, or not. If
the address matches a local alias, <span class="command"><strong>submit</strong></span> will indicate a
valid address, and exit. If the address does not match a local alias,
<span class="command"><strong>submit</strong></span> checks if this address is deliverable by any output
protocol module. If so, <span class="command"><strong>submit</strong></span> will indicate a valid address,
and exit. Otherwise, <span class="command"><strong>submit</strong></span> prints a "User unknown" error
message, and exits.</p></dd><dt><span class="term">-bcc</span></dt><dd><p>
If no recipients are given, obtain the list of
recipients from <code class="literal">Bcc:</code> headers only. Normally, if no recipients
are specified, <span class="command"><strong>submit</strong></span> reads the list of recipients from the
<code class="literal">To:</code>, <code class="literal">Cc:</code> and <code class="literal">Bcc:</code> headers
(<code class="literal">Bcc:</code> headers are always removed). The <code class="literal">-bcc</code>
option ignores <code class="literal">To:</code> and <code class="literal">Cc:</code> headers for this
purpose. This option is ignored if an explicit recipient list is specified
(see below).</p></dd><dt><span class="term">-delay=<em class="replaceable"><code>n</code></em></span></dt><dd><p>
Wait <em class="replaceable"><code>n</code></em> seconds before delivering
the message. If not specified, delivery begins after waiting the amount of
time specified by the <code class="filename">@sysconfdir@/submitdelay</code> configuration
time (default: 0 seconds -- immediate delivery).</p></dd><dt><span class="term">-rfc3848=<em class="replaceable"><code>text</code></em></span></dt><dd><p>
	    Specify the RFC 3848 transmission type label to be included
	    in the message's <span class="quote">“<span class="quote">Received:</span>”</span> header
	  </p></dd><dt><span class="term">-vhost=<em class="replaceable"><code>address</code></em></span></dt><dd><p>
	    Append <span class="quote">“<span class="quote">.<em class="replaceable"><code>address</code></em></span>”</span> to
	    names of all configuration files Courier reads while processing
	    this message.
	  </p></dd></dl></div></div><div class="refsect1"><a id="submit_responses_from_submit" shape="rect"> </a><h2>RESPONSES FROM <span class="command"><strong>submit</strong></span></h2><p>
All replies from <span class="command"><strong>submit</strong></span> follow the format of SMTP responses, as
defined in RFC822.</p><p>
To summarize: the responses are one or more lines long. Every line in the
response instead of the last one consists of a three-digit numerical code, a
dash, then arbitrary text. The last line (or the only line of the response)
starts with a three-digit numerical code, a single space, and arbitrary text.
The first digit of the numerical code indicates whether the response indicates
success, or failure. If the first digit is 5, the response indicates a
permanent failure. If the first digit is 4, the response indicates a temporary
failure (the message or the address should be resubmitted later). If the first
digit is not 4 or 5, the response indicates success, or acceptance.</p></div><div class="refsect1"><a id="submit_message_submission" shape="rect"> </a><h2>MESSAGE SUBMISSION</h2><p>
Unless either <code class="option">-expn</code> or <code class="option">-vrfy</code> option is specified,
<span class="command"><strong>submit</strong></span> reads the message envelope and contents from standard
input, as follows. All input and output to <span class="command"><strong>submit</strong></span> consists of
newline-terminated (NOT carriage return/newline terminated) lines of
text.</p><p>
<span class="command"><strong>submit</strong></span> reads the first line of text, which specifies the
envelope sender address. The line is formatted as follows:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
address<span class="token">&lt;tab&gt;</span>format<span class="token">&lt;tab&gt;</span>envid
</pre></div><p>
<span class="token">&lt;tab&gt;</span> is the ASCII tab character. The address may be an
empty string, optionally followed by tab, then "format", another tab, then
"envid".</p><p>
      <em class="replaceable"><code>format</code></em> is one or more chatacters that
      specify delivery status
      notification processing, and other message options. The 'F' character
      specifies that delivery status notifications should include the entire
      message, 'H' specifies just the headers of the message should be included.
      Absence of either 'F' or 'H' specifies no preference. "S{keyword}"
      specifies
      the optional SECURITY extension keyword for this message.
      The 'V' character in
      <em class="replaceable"><code>format</code></em> sets the VERP extension flag for
      this message.
      The '8' character is a flag indicating that the message was received
      via SMTP with a <code class="literal">SMTPUTF8</code> keyword, this prepends
      <span class="quote">“<span class="quote">UTF8</span>”</span> to the transmission type passed in via
      <code class="option">-rfc3848</code>.
    </p><p>
<em class="replaceable"><code>envid</code></em> is the original message envelope ID, that will be shown on any
delivery status notifications. NOTE: <em class="replaceable"><code>envid</code></em> must be specified using
xtext encoding (see the relevant RFCs).</p><p>
After reading the first line of text, <span class="command"><strong>submit</strong></span> prints a response
(see "RESPONSES FROM SUBMIT", above). If the response is a failure,
<span class="command"><strong>submit</strong></span>
terminates immediately. Otherwise, <span class="command"><strong>submit</strong></span>
then reads one or more envelope recipients.</p><p>
Each envelope recipient is read as a single non-empty line of text,
formatted as follows:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
address<span class="token">&lt;tab&gt;</span>dsn<span class="token">&lt;tab&gt;</span>oreceipient
</pre></div><p>
<em class="replaceable"><code>address</code></em> is a non-empty recipient E-mail address, optionally followed
by the tab character, then zero or more characters specifying <em class="replaceable"><code>dsn</code></em>, then
a tab character, then the <em class="replaceable"><code>orecipient</code></em> value.</p><p>
      <em class="replaceable"><code>dsn</code></em> is zero or more of the following
      characters: S - send a delivery
      status notification upon a successful delivery to this address,
      F - send a DSN upon a failed delivery,
      D - send a DSN upon a mail delay,
      N - never send a DSN.
      <em class="replaceable"><code>oreceipient</code></em> is the "Original Recipient",
      as specified in RFC1894, except that is not encoded using xtext
      encoding, but in unencoded UTF-8.
    </p><p>
<span class="command"><strong>submit</strong></span> will print a response to each recipient (see "RESPONSES
FROM SUBMIT", above). If at least one recipient address has been succesfully
specified, a blank line is read to specify end of recipient list, which is
followed by the entire message, headers and body.</p><p>
A single blank line terminates the list of recipients. That is followed by
the message itself, until end of file.</p><p>
The blank line can be present before even a the first recipient is
specified. If so, <span class="command"><strong>submit</strong></span> obtains the list of recipient from the
message's headers.</p><p>
<span class="command"><strong>submit</strong></span> reads the message headers and body until end-of-file.
Then, <span class="command"><strong>submit</strong></span> prints a response (see above), indicating whether or
not the message was accepted for delivery, and terminates.</p></div><div class="refsect1"><a id="submit_address_rewriting" shape="rect"> </a><h2>ADDRESS REWRITING</h2><p>
Each recipient address (whether specified explicitly, or obtained from the
message headers), will be rewritten according to the rewriting rules specified
by the input module. Each address in the headers of the message will also be
rewritten.</p><p>
After rewriting each recipient address, <span class="command"><strong>submit</strong></span> will search the
aliases.dat file for this address, to see if it represents a locally defined
alias. Submit searches
<code class="filename">@libexecdir@/courier/modules/<em class="replaceable"><code>module</code></em>/aliases.dat</code> and
<code class="filename">@sysconfdir@/aliases.dat</code> (actual locations may be changed by the
system administrator). If the address is found, the recipient address will be
replaced by the addresses defined in the <code class="filename">aliases.dat</code> file.</p></div><div class="refsect1"><a id="submit_environment_variables" shape="rect"> </a><h2>ENVIRONMENT VARIABLES</h2><p>
<span class="command"><strong>submit</strong></span> also reads the following environment variables to further
specify how the message is to be processed:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">BLOCK</span></dt><dd><p>
If this variable is set to a non-empty value,
submit will reject every recipient (in effect, rejecting the message). The
contents of the environment variable will be used as the error
message.</p></dd><dt><span class="term">DSNENVID</span></dt><dd><p>
If envid is not specified, or is blank, and this
environment variable is defined, the contents of this variable is used as
the original envelope id field for DSNs. Note that DSNENVID is copied
verbatim into the Original-Envelope-Id field (if the message is relayed to
another MTA, the <span class="application">Courier</span> mail server
automatically xtext-encodes it).</p></dd><dt><span class="term">DSNNOTIFY</span></dt><dd><p>
If the dsn field for a recipient is empty, the
contents of this environment variable is used in its place. Also, if the
recipient list is read from the headers, the contents of this environment
variable are used to set the dsn setting.</p></dd><dt><span class="term">DSNRET</span></dt><dd><p>
If the format field for this message is empty, the
contents of this environment variable is used in its place.</p></dd><dt><span class="term">NOADDDATE</span></dt><dd><p>
Normally the <span class="application">Courier</span> mail server adds a
<code class="literal">Date:</code>
header to the message, if it does not have one. If this environment
variable is set, the <span class="application">Courier</span> mail server
will not add a <code class="literal">Date:</code> header.</p></dd><dt><span class="term">NOADDMSGID</span></dt><dd><p>
Normally the <span class="application">Courier</span> mail server adds a
<code class="literal">Message-Id:</code> header to the message, if it does not have it.
If this environment variable is set, the
<span class="application">Courier</span> mail server will not add a
<code class="literal">Message-Id:</code> header.</p></dd><dt><span class="term">NOADDRREWRITE</span></dt><dd><p>
	    Normally the <span class="application">Courier</span> mail server
	    rewrites addresses in the <code class="literal">From:</code>,
	    <code class="literal">To:</code>, and <code class="literal">Cc:</code> header fields.
	    If this environment variable is set to <code class="literal">1</code>, the
	    <span class="application">Courier</span> mail server will not rewrite them.
	    If it is set to a higher value, the
	    <span class="application">Courier</span> mail server will only rewrite it
	    if no
	    <code class="literal">DKIM-Signature:</code> header field was found.
	  </p></dd><dt><span class="term">MIME</span></dt><dd><p>
Normally the <span class="application">Courier</span> mail server
adds any missing
RFC2045 headers to the message. The <code class="envar">MIME</code> environment variable
can be set to the following values: <code class="literal">none</code> - do not do any
RFC2045 processing whatsoever; <code class="literal">7bit</code> - if the message contains
any 8-bit text, convert it to <code class="literal">quoted-printable</code> encoding;
<code class="literal">8bit</code> -if the message contains any quoted-printable encoded
text that can be representing as 8bit-encoded text, then convert it to
8bit encoding.</p></dd></dl></div></div><div class="refsect1"><a id="submit_see_also" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="courierpop3d.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courierpop3d</span>(8)</span></a>,
<a class="ulink" href="couriertcpd.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">couriertcpd</span>(8)</span></a>,
<a class="ulink" href="authlib.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">authlib</span>(7)</span></a>.</p></div></div></body></html>
