X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/64e8827c5d5def0325ab7181fe939623c77e807c..63621a81d16ab743de6b57d47578a9a2c670ad22:/man/send.man

diff --git a/man/send.man b/man/send.man
index c83a74fe..4eb7f902 100644
--- a/man/send.man
+++ b/man/send.man
@@ -1,13 +1,15 @@
-.\"
+.TH SEND %manext1% 2017-05-11 "%nmhversion%"
+.
 .\" %nmhwarning%
-.\"
-.TH SEND %manext1% "January 23, 2014" "%nmhversion%"
+.
 .SH NAME
-send \- send a message
+send \- send an nmh message
 .SH SYNOPSIS
 .HP 5
 .na
 .B send
+.RB [ \-help ]
+.RB [ \-version ]
 .RB [ \-alias
 .IR aliasfile ]
 .RB [ \-draft ]
@@ -32,36 +34,38 @@ send \- send a message
 .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 [ \-saslmaxssf
-.IR ssf ]
 .RB [ \-saslmech
 .IR mechanism ]
+.RB [ \-authservice
+.IR service ]
 .RB [ \-snoop ]
 .RB [ \-user
 .IR username ]
 .RB [ \-tls ]
 .RB [ \-initialtls ]
 .RB [ \-notls ]
+.RB [ \-certverify ]
+.RB [ \-nocertverify ]
 .RB [ \-width
 .IR columns ]
 .RB [ file
 \&...]
-.RB [ \-version ]
-.RB [ \-help ]
 .ad
 .SH DESCRIPTION
-.B Send
+.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, \*(lqDcc:\*(rq, and \*(lqFcc:\*(rq fields of the message.  If
 .B send
-is re\-distributing a message, as invoked from
+is re-distributing a message, as invoked from
 .BR dist ,
 then the
 corresponding \*(lqResent\-xxx\*(rq fields are examined instead.
@@ -101,9 +105,9 @@ for more information.
 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
+This conversion occurs before all other processing.
 .IR whatnow (1)
-man page describes the user interface for managing MIME attachments via
+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
@@ -145,7 +149,7 @@ 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 
+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:
@@ -156,6 +160,10 @@ 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,
@@ -200,9 +208,9 @@ switches invoke
 the
 .B nmh
 draft folder facility.  This is an advanced (and highly
-useful) feature.  Consult the
+useful) feature.  Consult
 .IR mh-draft (5)
-man page for more
+for more
 information.
 .PP
 If
@@ -230,7 +238,7 @@ lot of partial messages.  The argument to
 tells it how long
 to pause between postings.
 .PP
-.B Send
+.B send
 with no
 .I file
 argument will query whether the draft
@@ -257,7 +265,7 @@ If a \*(lqDcc:\*(rq field is encountered and the
 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
+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
@@ -273,7 +281,7 @@ If
 .B \-filter
 .I filterfile
 is specified, then this copy is filtered
-(re\-formatted) by
+(re-formatted) by
 .B mhl
 prior to being sent to the blind recipients.
 Alternately, if you specify the
@@ -308,7 +316,7 @@ switch must be enabled for this switch to have any effect.
 .PP
 If
 .B send
-is re\-distributing a message (when invoked by
+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.
@@ -320,12 +328,12 @@ is optional.
 .PP
 If a message with multiple \*(lqFrom:\*(rq
 addresses does
-.B NOT
+.I 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
+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
@@ -350,6 +358,28 @@ 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.
 .PP
+Beware that if an \*(lqFcc:\*(rq with one or more folders is present
+but none of the folders exist, and the default
+.I fileproc
+and
+.I postproc
+are in use, then
+.B refile
+will prompt the user to create the folder(s) if
+.B \-push
+is not specified.  If all responses are negative, or creation of each folder
+fails, or
+.B \-push
+is specified, the message will not be copied to any folder and will be
+removed by
+.BR post .
+With the default
+.B refile
+switches, the message draft will be renamed according to the specification
+of its
+.B \-nolink
+switch.
+.PP
 By using the
 .B \-width
 .I columns
@@ -358,23 +388,33 @@ switch, the user can direct
 as to how long it should make header lines containing addresses.
 .PP
 The mail transport system default is provided in
-.I %etcdir%/mts.conf
-but can be overriiden here with the
+.I %nmhetcdir%/mts.conf
+but can be overridden 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 %etcdir%/mts.conf
-.RI servers
+.I %nmhetcdir%/mts.conf
+.I 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.)
+plaintext or easily decoded base64.)  If
+.B \-sasl \-saslmech xoauth2
+is used, the HTTP transaction is also shown.
 .PP
 If
 .B nmh
@@ -387,28 +427,51 @@ 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
 .I netrc
-file can be used to store this password, as described in the
-mh-profile(5) man page).  The
+file can be used to store this password, as described in
+.IR mh-profile (5).
+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
+other than the default.  The credentials profile entry in
+.IR mh\-profile (5)
+describes the ways to supply a username and
 password.
 .PP
 If SASL authentication is successful,
-.BR nmh
+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.  The
-.B \-saslmaxssf
-switch can be used to select the maximum value of the Security Strength Factor.
-This is an integer value and the exact meaning of this value depends on the
-underlying SASL mechanism.  A value of 0 disables encryption.
+switch; see
+.IR post (8)'s
+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
+.IR mhlogin (1)
+for more details.
 .PP
 If
 .B nmh
@@ -425,13 +488,32 @@ using the STARTTLS command.  The
 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
+`(tls-decrypted)' when viewing the SMTP transaction with the
 .B \-snoop
-switch.
+switch; see
+.IR post (8)'s
+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
+When using TLS the default is to verify the remote certificate and SubjectName
+against the local trusted certificate store.  This can be controlled by
+the
+.B \-certverify
+and
+.B \-nocertverify
+switches.  See your OpenSSL documentation for more information on certificate
+verification.
+.PP
 The files specified by the profile entry \*(lqAliasfile:\*(rq and any
 additional alias files given by the
 .B \-alias
@@ -443,11 +525,102 @@ 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
+.IR mhlogin (1)
+for OAuth services, and
+.IR mh-profile (5)
+for login credentials.
+.PP
 .SH FILES
 .fc ^ ~
 .nf
-.ta \w'%etcdir%/ExtraBigFileName  'u
-^$HOME/\&.mh\(ruprofile~^The user profile
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u
+^$HOME/.mh_profile~^The user profile
 .fi
 .SH "PROFILE COMPONENTS"
 .fc ^ ~
@@ -455,18 +628,23 @@ for more information.
 .ta 2.4i
 .ta \w'ExtraBigProfileName  'u
 ^Path:~^To determine the user's nmh directory
-^Draft\-Folder:~^To find the default draft\-folder
+^Draft\-Folder:~^To find the default draft-folder
 ^Aliasfile:~^For a default alias file
 ^Signature:~^To determine the user's mail signature
 ^mailproc:~^Program to post failure notices
 ^postproc:~^Program to post the message
+^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 refile (1),
 .IR repl (1),
 .IR whatnow (1),
 .IR mh\-alias (5),
@@ -475,8 +653,8 @@ for more information.
 .IR post (8)
 .SH DEFAULTS
 .nf
-.RB ` file "' defaults to <mh\-dir>/draft"
-.RB ` \-alias "' defaults to %etcdir%/MailAliases"
+.RB ` file "' defaults to <mh-dir>/draft"
+.RB ` \-alias "' defaults to %nmhetcdir%/MailAliases"
 .RB ` \-nodraftfolder '
 .RB ` \-nofilter '
 .RB ` \-format '
@@ -488,6 +666,7 @@ for more information.
 .RB ` \-noverbose '
 .RB ` \-nowatch '
 .RB ` "\-width\ 72" '
+.RB ` \-certverify '
 .fi
 .SH CONTEXT
 None