X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/cfc525a9b85207225cb4071d1d3b01e8d1db2424..8cfcda36ca8f98694d1c5884c32ff96fe083ead3:/man/send.man?ds=sidebyside diff --git a/man/send.man b/man/send.man index 88fd9c3c..757eaced 100644 --- a/man/send.man +++ b/man/send.man @@ -1,198 +1,645 @@ .\" .\" %nmhwarning% -.\" $Id$ .\" -.\" include the -mh macro file -.so %etcdir%/tmac.h -.\" -.TH SEND %manext1% MH.6.8 [%nmhversion%] +.TH SEND %manext1% "October 10, 2016" "%nmhversion%" .SH NAME send \- send a message .SH SYNOPSIS -.in +.5i -.ti -.5i -send -\%[\-alias\ aliasfile] -\%[\-draft] -\%[\-draftfolder\ +folder] -.br -\%[\-draftmessage\ msg] \%[\-nodraftfolder] -.br -\%[\-filter\ filterfile] \%[\-nofilter] -\%[\-format] \%[\-noformat] -.br -\%[\-forward] \%[\-noforward] -\%[\-mime] \%[\-nomime] -\%[\-msgid] -.br -\%[\-nomsgid] -\%[\-push] \%[\-nopush] -\%[\-split\ seconds] -.br -\%[\-verbose] \%[\-noverbose] -\%[\-watch] \%[\-nowatch] -\%[\-sasl] \%[\-saslmech\ mechanism] \%[\-user\ username] -.br -\%[\-width\ columns] -\%[file\ ...] -\%[\-version] -\%[\-help] -.in -.5i +.HP 5 +.na +.B send +.RB [ \-help ] +.RB [ \-version ] +.RB [ \-alias +.IR aliasfile ] +.RB [ \-draft ] +.RB [ \-draftfolder +.IR +folder ] +.RB [ \-draftmessage +.IR msg ] +.RB [ \-nodraftfolder ] +.RB [ \-filter +.IR filterfile ] +.RB [ \-nofilter ] +.RB [ \-format " | " \-noformat ] +.RB [ \-forward " | " \-noforward ] +.RB [ \-mime " | " \-nomime ] +.RB [ \-msgid " | " \-nomsgid ] +.RB [ \-messageid +.IR localname " | " random ] +.RB [ \-push " | " \-nopush ] +.RB [ \-split +.IR seconds ] +.RB [ \-verbose " | " \-noverbose ] +.RB [ \-watch " | " \-nowatch ] +.RB [ \-mts +.IR smtp " | " sendmail/smtp " | " sendmail/pipe ] +.RB [ \-sendmail +.IR program ] +.RB [ \-server +.IR servername ] +.RB [ \-port +.IR port-name/number ] +.RB [ \-sasl ] +.RB [ \-nosasl ] +.RB [ \-saslmech +.IR mechanism ] +.RB [ \-authservice +.IR service ] +.RB [ \-snoop ] +.RB [ \-user +.IR username ] +.RB [ \-tls ] +.RB [ \-initialtls ] +.RB [ \-notls ] +.RB [ \-width +.IR columns ] +.RB [ file +\&...] +.ad .SH DESCRIPTION -\fISend\fR will cause each of the specified files to be delivered +.B Send +will cause each of the specified files to be delivered to each of the destinations in the \*(lqTo:\*(rq, \*(lqcc:\*(rq, -\*(lqBcc:\*(rq, and \*(lqFcc:\*(rq fields of the message. If \fIsend\fR -is re\-distributing a message, as invoked from \fIdist\fR, then the +\*(lqBcc:\*(rq, \*(lqDcc:\*(rq, and \*(lqFcc:\*(rq fields of the message. If +.B send +is re\-distributing a message, as invoked from +.BR dist , +then the corresponding \*(lqResent\-xxx\*(rq fields are examined instead. - -By default, \fIsend\fR uses the program \fIpost\fR(8) to do the actual +.PP +By default, +.B send +uses the program +.B post +to do the actual delivery of the messages, although this can be changed by defining the -\fIpostproc\fR profile component. Most of the features attributed to -\fIsend\fR are actually performed by \fIpost\fR. - -If `\-push' is specified, \fIsend\fR will detach itself from the user's -terminal and perform its actions in the background. If \fIpush\fR\0'd +.I postproc +profile component. Most of the features attributed to +.B send +are actually performed by +.BR post . +.PP +Before +.B send +gives the message to +.B post +for delivery, the message is processed by +.B mhbuild +to perform any necessary MIME encoding of the outgoing message. This +can be changed by the +.I buildmimeproc +profile component. +.B mhbuild +is invoked with the +.B \-auto +switch, so +.B mhbuild +directives are not processed by default. See +.IR mhbuild (1) +for more information. +.PP +.B mhbuild +will scan the message draft for a header named +.IR Attach . +The draft is converted to a MIME message if one or more matches are found. +This conversion occurs before all other processing. The +.IR whatnow (1) +man page describes the user interface for managing MIME attachments via +this mechanism. +.PP +The first part of the MIME message is the draft body if that body contains +any non-blank characters. +The body of each +.I Attach +header field is interpreted as a file name, and each file named is included as a separate +part in the MIME message. +.PP +Determination of the content MIME type inserted into the Content-Type +header for each part depends on how the +.B nmh +installation was configured. If a program, such as +.B file +with a +.B \-\-mime +or +.B \-i +option, was found that can specify the type of a file as a MIME type +string, then that will be used. To determine if your +.B nmh +was so configured, run +.B mhparam mimetypeproc +and see if a non-empty string is displayed. +.PP +If your +.B nmh +was not configured with a program to specify a file type as a MIME +string, then a different method is used to determine the content-type +string. For file names with dot suffixes, the profile is scanned for a +.I mhshow-suffix- +entry for that suffix. +The content-type for the part is taken from that profile entry if a match is +found. If a match is not found in the user profile, the mhn.defaults +profile is scanned next. +If no match is found or the file does not have a dot suffix, the content-type +is text/plain if the file contains only ASCII characters or application/octet-stream +if it contains characters outside of the ASCII range. See +.IR mhshow (1) +for more details and example syntax. +.PP +Each attached MIME part contains a +\*(lqContent-Description\*(rq header that includes the filename, and +adds a \*(lqContent-Disposition\*(rq header. +Here is an example of MIME part headers for an attachment: +.PP +.nf +Content-Type: text/plain; name="VERSION"; charset="us-ascii" +Content-Description: VERSION +Content-Disposition: attachment; filename="VERSION" +.fi +.PP +See +.IR mhbuild (1) +for explanation of how the Content-Disposition value is selected. +.PP +If +.B \-push +is specified, +.B send +will detach itself from the user's +terminal and perform its actions in the background. If +.BR push 'd and the draft can't be sent, then an error message will be sent (using -the mailproc) back to the user. If `\-forward' is given, then a copy -of the draft will be attached to this failure notice. Using `\-push' -differs from putting \fIsend\fR in the background because the output is -trapped and analyzed by \fInmh\fR. - -If `\-verbose' is specified, \fIsend\fR will indicate the interactions +the mailproc) back to the user. If +.B \-forward +is given, then a copy +of the draft will be attached to this failure notice. Using +.B \-push +differs from putting +.B send +in the background because the output is +trapped and analyzed by +.BR nmh . +.PP +If +.B \-verbose +is specified, +.B send +will indicate the interactions occurring with the transport system, prior to actual delivery. -If `\-watch' is specified \fIsend\fR will monitor the delivery of local +If +.B \-watch +is specified +.B send +will monitor the delivery of local and network mail. Hence, by specifying both switches, a large detail of information can be gathered about each step of the message's entry into the transport system. - -The `\-draftfolder\ +folder' and `\-draftmessage\ msg' switches invoke -the \fInmh\fR draft folder facility. This is an advanced (and highly -useful) feature. Consult the \fImh-draft\fR(5) man page for more +.PP +The +.B \-draftfolder +.I +folder +and +.B \-draftmessage +.I msg +switches invoke +the +.B nmh +draft folder facility. This is an advanced (and highly +useful) feature. Consult the +.IR mh-draft (5) +man page for more information. - -If `\-split' is specified, \fIsend\fR will split the draft into one +.PP +If +.B \-split +is specified, +.B send +will split the draft into one or more partial messages prior to sending. This makes use of the -MIME features in nmh. Note however that if \fIsend\fR is -invoked under \fIdist\fR\0(1), then this switch is ignored\0--\0it makes +MIME features in +.BR nmh . +Note however that if +.B send +is +invoked under +.BR dist , +then this switch is ignored\0--\0it makes no sense to redistribute a message in this fashion. Sometimes you want -\fIsend\fR to pause after posting a partial message. This is usually -the case when you are running \fIsendmail\fR and expect to generate a -lot of partial messages. The argument to `\-split' tells it how long +.B send +to pause after posting a partial message. This is usually +the case when you are running +.B sendmail +and expect to generate a +lot of partial messages. The argument to +.B \-split +tells it how long to pause between postings. - -\fISend\fR with no \fIfile\fR argument will query whether the draft -is the intended file, whereas `\-draft' will suppress this question. +.PP +.B Send +with no +.I file +argument will query whether the draft +is the intended file, whereas +.B \-draft +will suppress this question. Once the transport system has successfully accepted custody of the -message, the file will be renamed with a leading comma, which allows +message, the file will be renamed with a site-dependent prefix +(usually a comma), which allows it to be retrieved until the next draft message is sent. If there are -errors in the formatting of the message, \fIsend\fR will abort with a +errors in the formatting of the message, +.B send +will abort with a (hopefully) helpful error message. - +.PP If a \*(lqBcc:\*(rq field is encountered, its addresses will be used for delivery, and the \*(lqBcc:\*(rq field will be removed from the message sent to sighted recipients. The blind recipients will receive an entirely new message with a minimal set of headers. Included in the body of the message will be a copy of the message sent to the sighted recipients. -If `\-filter\ filterfile' is specified, then this copy is filtered -(re\-formatted) by \fImhl\fR prior to being sent to the blind recipients. -Alternately, if you specify the `-mime' switch, then \fIsend\fR will +.PP +If a \*(lqDcc:\*(rq field is encountered and the +.B sendmail/pipe +mail transport method is not in use, its addresses will be used for +delivery, and the \*(lqDcc:\*(rq field will be removed from the message. The +blind recipients will receive the same message sent to the sighted +recipients. *WARNING* Recipients listed in the \*(lqDcc:\*(rq field receive no +explicit indication that they have received a \*(lqblind copy\*(rq. +This can cause blind recipients to +inadvertently reply to all of the sighted recipients of the +original message, revealing that they received a blind copy. +On the other hand, since a normal reply to a message sent +via a \*(lqBcc:\*(rq field +will generate a reply only to the sender of the original message, +it takes extra effort in most mailers to reply to the included +message, and so would usually only be done deliberately, rather +than by accident. +.PP +If +.B \-filter +.I filterfile +is specified, then this copy is filtered +(re\-formatted) by +.B mhl +prior to being sent to the blind recipients. +Alternately, if you specify the +.B -mime +switch, then +.B send +will use the MIME rules for encapsulation. - -Prior to sending the message, the fields \*(lqFrom:\ user@local\*(rq, -and \*(lqDate:\ now\*(rq will be appended to the headers in the message. -If the environment variable \fB$SIGNATURE\fR is set, then its value -is used as your personal name when constructing the \*(lqFrom:\*(rq -line of the message. If this environment variable is not set, then -\fIsend\fR will consult the profile entry \*(lqSignature\*(rq for -this information. On hosts where \fInmh\fR was configured with the UCI -option, if \fB$SIGNATURE\fR is not set and the \*(lqSignature\*(rq profile -entry is not present, then the file \fB$HOME\fR/.signature is consulted. -If `\-msgid' is specified, then a \*(lqMessage\-ID:\*(rq field will also +.PP +Prior to sending the message, the \*(lqDate:\ now\*(rq field will be appended to the headers in the message. +If +.B \-msgid +is specified, then a \*(lqMessage\-ID:\*(rq field will also be added to the message. - -If \fIsend\fR is re\-distributing a message (when invoked by -\fIdist\fR\0), then \*(lqResent\-\*(rq will be prepended to each of these +.PP +The +.B \-messageid +switch selects the style used for the part appearing after the @ +in \*(lqMessage\-ID:\*(rq, \*(lqResent\-Message\-ID:\*(rq, and +\*(lqContent\-ID:\*(rq header fields. The two acceptable options are +.B localname +(which is the default), +and +.BR random . +With +.BR localname , +the local hostname is used. With +.BR random , +a random sequence of characters is used instead. Note that the +.B \-msgid +switch must be enabled for this switch to have any effect. +.PP +If +.B send +is re\-distributing a message (when invoked by +.BR dist ), +then \*(lqResent\-\*(rq will be prepended to each of these fields: \*(lqFrom:\*(rq, \*(lqDate:\*(rq, and \*(lqMessage\-ID:\*(rq. -If the message already contains a \*(lqFrom:\*(rq field, then a -\*(lqSender: user@local\*(rq field will be added as well. (An already -existing \*(lqSender:\*(rq field is an error!) - -By using the `\-format' switch, each of the entries in the \*(lqTo:\*(rq +.PP +A \*(lqFrom:\*(rq field is required for all outgoing messages. Multiple +addresses are permitted in the \*(lqFrom:\*(rq field, but a \*(lqSender:\*(rq +field is required in this case. Otherwise a \*(lqSender:\*(rq field +is optional. +.PP +If a message with multiple \*(lqFrom:\*(rq +addresses does +.B NOT +include a \*(lqSender:\*(rq field but does include an \*(lqEnvelope\-From:\*(rq +field, the \*(lqEnvelope\-From:\*(rq field will be used to construct +a \*(lqSender:\*(rq field. +.PP +When using SMTP for mail submission, the envelope\-from used for the SMTP +transaction is derived from the \*(lqEnvelope\-From:\*(rq field. +If no \*(lqEnvelope\-From:\*(rq field is present, the \*(lqSender:\*(rq +field is used. If neither the \*(lqEnvelope\-From:\*(rq nor the +\*(lqSender:\*(rq field is present, the \*(lqFrom:\*(rq field is used. +When \*(lqEnvelope\-From:\*(rq appears in a message +it will be removed from the final outgoing message. +.PP +By using the +.B \-format +switch, each of the entries in the \*(lqTo:\*(rq and \*(lqcc:\*(rq fields will be replaced with \*(lqstandard\*(rq format entries. This standard format is designed to be usable by all of the message handlers on the various systems around the Internet. -If `\-noformat' is given, then headers are output exactly as they appear +If +.B \-noformat +is given, then headers are output exactly as they appear in the message draft. - +.PP If an \*(lqFcc:\ folder\*(rq is encountered, the message will be copied to the specified folder for the sender in the format in which it will appear to any non\-Bcc receivers of the message. That is, it will have the appended fields and field reformatting. The \*(lqFcc:\*(rq fields will be removed from all outgoing copies of the message. - -By using the `\-width\ columns' switch, the user can direct \fIsend\fR +.PP +By using the +.B \-width +.I columns +switch, the user can direct +.B send as to how long it should make header lines containing addresses. - -If nmh has been compiled with SASL support, the `\-sasl' switch will enable +.PP +The mail transport system default is provided in +.I %nmhetcdir%/mts.conf +but can be overriiden here with the +.B \-mts +switch. +.PP +If nmh is using as its mail transport system +.BR sendmail/pipe , +the +.B \-sendmail +switch can be used to override the default +.B sendmail +program. +.PP +If nmh is using the SMTP MTA, the +.B \-server +and the +.B \-port +switches can be used to override the default mail server (defined by the +.I %nmhetcdir%/mts.conf +.RI servers +entry). The +.B \-snoop +switch can be used to view the SMTP transaction. (Beware that the +SMTP transaction may contain authentication information either in +plaintext or easily decoded base64.) If +.B \-sasl \-saslmech xoauth2 +is used, the HTTP transaction is also shown. +.PP +If +.B nmh +has been compiled with SASL support, the +.B \-sasl +and +.B \-nosasl +switches will enable and disable the use of SASL authentication with the SMTP MTA. Depending on the SASL mechanism used, this may require an additional password prompt from the -user (but the \*(lq.netrc\*(rq file can be used to store this password). -`\-saslmech' switch can be used to select a particular SASL mechanism, -and the the `\-user' switch can be used to select a authorization userid -to provide to SASL other than the default. - -Currently SASL security layers are not supported for SMTP. The SASL -SMTP code in nmh will always negotiate an unencrypted connection. - +user (but the +.I netrc +file can be used to store this password, as described in the +mh-profile(5) man page). The +.B \-saslmech +switch can be used to select a particular SASL mechanism, +and the +.B \-user +switch can be used to select a authorization userid to provide to SASL +other than the default. The credentials profile entry in the +mh\-profile(5) man page describes the ways to supply a username and +password. +.PP +If SASL authentication is successful, +.BR nmh +will attempt to negotiate a security layer for session encryption. +Encrypted data is labelled with `(encrypted)' and `(decrypted)' when +viewing the SMTP transaction with the +.B \-snoop +switch; see the +.B post +man page description of +.B \-snoop +for its other features. +.PP +If +.B nmh +has been compiled with OAuth support, the +.B \-sasl +and +.B \-saslmech xoauth2 +switches will enable OAuth authentication. The +.B \-user +switch must be used, and the +.I username +must be an email address the user has for the service, which must +be specified with the +.B \-authservice +.I service +switch. Before using OAuth authentication, the user must authorize nmh by +running +.B mhlogin +and grant authorization to that account. See the +.IR mhlogin (1) +man page for more details. +.PP +If +.B nmh +has been compiled with TLS support, the +.B \-tls +and +.B \-initialtls +switches will require the negotiation of TLS when +connecting to the SMTP MTA. The +.B \-tls +switch will negotiate TLS as part of the normal SMTP protocol +using the STARTTLS command. The +.B \-initialtls +will negotiate TLS immediately after the connection has +taken place, before any SMTP commands are sent or received. Encrypted data +is labelled with `(tls-encrypted)' and +`(tls-decrypted)' when viewing the SMTP transction with the +.B \-snoop +switch; see the +.B post +man page description of +.B \-snoop +for its other features. +The +.B \-notls +switch will disable all attempts to negotiate TLS. +.PP +If port 465 is specified and none of the TLS switches were enabled, +.B \-initialtls +will be implied if TLS support was compiled in. Though port 465 for +SMTPS (SMTP over SSL) was deregistered by IANA in 1998, it is still +used for that service. +.PP The files specified by the profile entry \*(lqAliasfile:\*(rq and any -additional alias files given by the `\-alias aliasfile' switch will be -read (more than one file, each preceded by `\-alias', can be named). -See \fImh\-alias\fR\0(5) for more information. -.Fi +additional alias files given by the +.B \-alias +.I aliasfile +switch will be +read (more than one file, each preceded by +.BR \-alias , +can be named). +See +.IR mh\-alias (5) +for more information. +.SS Selection based on sender address: sendfrom +One or more +.I sendfrom +profile components can be used to select a mail server address, mail server +port, or any other switch that can be supplied to +.BR post . +It works by first looking at the sender address and domain name in the +message draft, as described below. +It then looks for a corresponding profile entry, which contains the +.B post +switches. +To enable, add profile entries of the form: +.PP +.RS 5 +.RI sendfrom- "address/domain name" : " post switches" +.RE +.PP +The email address is extracted from the Envelope-From: header, if not blank, +the Sender: header, or the From: header line in the message draft. +Multiple profile entries, with different email addresses or domain names, are +supported. +This allows different switches to +.BR post , +such as -user, to be associated with different email addresses. +If a domain name is used, it matches all users in that domain. +.PP +Here is an example profile entry using OAuth for an account hosted by gmail: +.PP +.nf +.RS 5 +sendfrom-gmail_address@example.com: -sasl -saslmech xoauth2 +.RS 5 +-authservice gmail -tls -server smtp.gmail.com +-user gmail_login@example.com +.RE +.RE +.fi +.PP +(Indentation indicates a continued line, as supported in MH profiles.) +The username need not be the same as the sender address, which was extracted +from the appropriate header line as noted above. +.PP +Here are example profile entries that use an nmh credentials file: +.PP +.nf +.RS 5 +credentials: file:nmhcreds +sendfrom-sendgrid_address@example.com: -sasl -tls +.RS 5 +-server smtp.sendgrid.net +.RE +sendfrom-outbound.att.net: -sasl -initialtls +.RS 5 +-server outbound.att.net -port 465 +.RE +sendfrom-fastmail.com: -initialtls -sasl -saslmech LOGIN +.RS 5 +-server smtps-proxy.messagingengine.com -port 80 +.RE +.RE +.fi +.PP +where nmhcreds is in the user's nmh directory (from the Path profile component) +and contains: +.PP +.nf +.RS 5 +machine smtp.sendgrid.net +.RS 5 +login sendgrid_login@example.com +password ******** +.RE +machine outbound.att.net +.RS 5 +login att_login@example.com +password ******** +.RE +machine smtps-proxy.messagingengine.com +.RS 5 +login fastmail_login@example.com +password ******** +.RE +.RE +.fi +.PP +For more information on authentication to mail servers, see the +.IR mhlogin (1) +man page for OAuth services, and +.IR mh-profile (5) +man page for login credentials. +.PP +.SH FILES +.fc ^ ~ +.nf +.ta \w'%nmhetcdir%/ExtraBigFileName 'u ^$HOME/\&.mh\(ruprofile~^The user profile -.Pr +.fi +.SH "PROFILE COMPONENTS" +.fc ^ ~ +.nf +.ta 2.4i +.ta \w'ExtraBigProfileName 'u ^Path:~^To determine the user's nmh directory -.Ps ^Draft\-Folder:~^To find the default draft\-folder -.Ps ^Aliasfile:~^For a default alias file -.Ps ^Signature:~^To determine the user's mail signature -.Ps ^mailproc:~^Program to post failure notices -.Ps ^postproc:~^Program to post the message -.Sa -comp(1), dist(1), forw(1), repl(1), mh\-alias(5), post(8) -.De -`file' defaults to /draft -.Ds -`\-alias %etcdir%/MailAliases' -.Ds -`\-nodraftfolder' -.Ds -`\-nofilter' -.Ds -`\-format' -.Ds -`\-forward' -.Ds -`\-nomime' -.Ds -`\-nomsgid' -.Ds -`\-nopush' -.Ds -`\-noverbose' -.Ds -`\-nowatch' -.Ds -`\-width\ 72' -.Co +^sendfrom-address:~^Switches to post for sender address +^sendfrom-domain:~^Switches to post for sender domain name +.fi +.SH "SEE ALSO" +.IR comp (1), +.IR dist (1), +.IR file (1), +.IR forw (1), +.IR mhbuild (1), +.IR mhparam (1), +.IR mhlogin (1), +.IR repl (1), +.IR whatnow (1), +.IR mh\-alias (5), +.IR mh\-profile (5), +.IR mh\-tailor (5), +.IR post (8) +.SH DEFAULTS +.nf +.RB ` file "' defaults to /draft" +.RB ` \-alias "' defaults to %nmhetcdir%/MailAliases" +.RB ` \-nodraftfolder ' +.RB ` \-nofilter ' +.RB ` \-format ' +.RB ` \-forward ' +.RB ` \-nomime ' +.RB ` \-nomsgid ' +.RB ` "\-messageid\ localname" ' +.RB ` \-nopush ' +.RB ` \-noverbose ' +.RB ` \-nowatch ' +.RB ` "\-width\ 72" ' +.fi +.SH CONTEXT None -.Bu +.SH BUGS Under some configurations, it is not possible to monitor the mail delivery -transaction; `\-watch' is a no-op on those systems. -.sp -Using `\-split\00' doesn't work correctly. -.En +transaction; +.B \-watch +is a no-op on those systems. +.PP +Using +.B \-split +.I 0 +doesn't work correctly.