smtpmail -- send mail using SMTP

SYNOPSIS

smtpmail [-ADoiS] [-s subject] [-f from-addr] [-F friendly-name] [-h hostname] [-m file] [-M htmlfile] [-c certfile] [-u username] [-p password] [-port port] [-service service] [-H GSSAPI-SPN | -spn GSSAPI-SPN] [-X auth_excl_list] [-timeout seconds | -w seconds] [-a attachment]... [-html | -l] [-ea|-eo|-e8] [-cc cc-address | -C cc-address ] [-bcc bcc-address | -B bcc-address ] [to-address]...

DESCRIPTION

The smtpmail command sends mail to a list of specified e-mail addresses using the Simple Mail Transport Protocol (SMTP). To use this command, you must have the TCP/IP service installed. You must also be actively connected using TCP/IP when issuing the smtpmail command because the command has no dialing capabilities and would otherwise be unable to connect to a host.

smtpmail reads the message to be sent from the standard input. The message is terminated by an EOF ( CTRL-Z on console) or a line consisting of a single period (.).

For secure hosts, ROOTDIR/etc/openssl/cert.pem. standard certificate authorities is loaded by openssl from ROOTDIR/etc/openssl/cert.pem. This file must be populated before openssl will initialize. It is not provided by the PTC MKS Toolkit installation, rather a script ROOTDIR/etc/openssl/mkcabundle.pl is provided to populate the file with a sample set of certificates dynamically downloaded from the mozilla trusted certificates list. You may of course choose to provide your own list of trusted root certificates. You can supply additional certificate authorities by adding a cert.pem file to your home directory or by specifying the -c option.

At least one e-mail address must be specified. It can be a to-address, cc-address, or bcc-address.

Options

-A

Enables the passing of your current login credentials to the server (see Authentication below). If authentication fails (possibly, because either the client or server does not support the mechanism used to pass the credentials), the user is prompted to provide a password.

-a attachment

Specifies a file to be attached to the message.

You can specify -a multiple times to attach multiple files.

-B bcc-address

-bcc bcc-address

Sends a "blind carbon copy" of the message. That is, a copy of the message is sent to the speciifed bcc-address but that e-mail address does not appear in the message received by other recipients.

You can specify -B or -bcc multiple times to send "blind carbon copies" to multiple addresses.

-C cc-address

-cc cc-address

Sends a "carbon copy" of the message. That is, a copy of the message is sent to the specified cc-address. That e-mail address is included in the message received by all recipients.

You can specify -C or -cc multiple times to send "carbon copies" to multiple addresses.

-c certfile

Specifies an alternative .pem file name to use as a certificate authority. The specified file may have been created with the openssl utility or supplied by a recognized authority.

-D

Provides extra debugging information.

-ea

-eo

-e8

Specifies the character encoding to be used in the message. When none of these three options are specified, smtpmail encodes the message as though -eo was specified.

-ea specifies that ISO-8859 ANSI encoding is to be used to encode the message header and body.

-eo specifies that the IBM850 OEM character set is to be used to encode the message header and body. Any non-ASCII header fields will be encoded using 7 bit US ASCII characters (as per Internet RFC 2047).

-e8 specifies that UTF8 encoding is to be used to encode the message header and body.

-f from-addr

Specifies an Internet mail address that identifies the sender.

from-addr can be of two forms: a simple e-mail address or a combination of a friendly name and an e-mail address. The first form is something like:

-f nobody@mks.com

while the second form adds a friendly name that is to be displayed instead of the e-mail address. It looks like this:

-f "Nobody At All <nobody@mks.com>"

When the TK_SMTPMAIL_FROMADDR environment variable is set, its value is used instead of any "from address" specified by this option.

-F friendly-name

Specifies a friendly name to be used in place of the e-mail address specified with -f when the message is displayed. For example:

-f nobody@mks.com -F "Nobody At All"

and

-f "Nobody At All <nobody@mks.com>"

are equivalent.

If the -f option already specifies a friendly name, this option is ignored. So, for example:

-f "Nobody At All <nobody@mks.com>"  -F "Nobody Does It Better"

sends the e-mail from nobody@mks.com with a friendly name of "Nobody At All". The friendly name specified by the -F option is not used.

-h hostname

Attempts to connect with the specified hostname. Without this option, smtpmail connects with the machine identified by the MAILHOST environment variable, if set. If MAILHOST is unset, smtpmail attempts to connect with mailhost.yourdomain where yourdomain is read from the registry (either from HKLM\System\CurrentControlSet\Services\Tcpip\Parameter\Domain or HKLM\System\CurrentControlSet\Services\Tcpip\Parameter\DhcpDomain, depending on which is populated).

-html

-l

Includes the specified message text (ANSI, OEM, or UTF8 text passed in from -m file or the standard input) twice in the message. It is included first in its original text format and then again enclosed in a simple HTML wrapper.

When you specify the -M option, the -l or -html option is ignored.

-H GSSAPI-SPN

-spn GSSAPI-SPN

Attempts to connect to the server with the Server Provider Name (SPN) specified by GSSAPI-SPN. When the GSSAPI or DIGEST-MD5 authentication mechanisms are being used, the client must specify a SPN registered by the server.

When neither of these options is specified, smtpmail uses a SPN of HOST/hostname if the -h hostname option is given or a SPN of HOST/$MAILHOST if -h is also omitted. Finally, if none of these options are specified and the MAILHOST environment variable is not set, smtpmail attempts to connect with the machine specified as the Domain host in the TCP/IP settings.

You can determine the SPN of a server by using the setspn utility (provided as part of the Windows support tools that can be installed from your Windows CD). The command:

setspn -L account

displays all the registered SPNs of the specified account. To display the list of registered SPNs associated with a given computer account, one would use:

setspn -L computername$

-i

Ignores SSL security errors.

-M htmlfile

Specifies an HTML alternative to the non-HTML message text supplied by the -m file option or through the standard output. The message sent includes first the non-HTML text and then the HTML contents of the specified htmlfile.

When you specify this option, the -html or -l option, if also specified, is ignored.

-m file

Sends the contents of the specified file as the text of the message.

-o

Sends the time zone as a numeric offset from Greenwich Mean Time (Coordinated Universal Time) rather than the default abbreviation. This is the default behavior for smtp. You do not need to explicitly set this option.

-p password

Specifies a password to use when the remote hostname requires authentication. If you don't use this option with the -u option, smtpmail prompts you for a password.

-P port

Specifies the outbound TCP port to use to connect to the SMTP server. This option is mututally exclusive to the -r TCP service option.

-r port

Specifies the outbound TCP service to use to connect to the SMTP server. The service is looked up in the services database and that port is used to connect to the SMTP server. This option is mututally exclusive to the -P TCP port option.

-S

creates a secure connection using SSL.

-s subject

Includes a standard e-mail header with the message and specifies the subject text for that header. Without this option, smtpmail assumes that the message contains a properly formatted e-mail header and nothing is added.

-timeout seconds

-w seconds

Specifies the number of seconds that smtpmail has to complete the operation before timing out and issuing an error.

-u username

Specifies the username to use if the remote hostname requires authentication. If you don't also specify -p password, smtpmail prompts you for one.

Note:: Not all authentication mechanisms understand domain names. For those that do, you can specify username as domain/user or domain\user. However, for those that do not (such as CRAM-MD5), the domain name should not be included.

-X auth_excl_list

Specifies an authentication exclusion list (auth_excl_list). auth_excl_list is a comma-separated list of authentication mechanisms to ignore when attempting authentication. This list can contain any of the authentication mechanisms listed under Authentication below and is case insensitive.

It is recommended that auth_excl_list be placed within double quotes to ensure the command is always correctly interpreted by the shell or command interpreter being used.

If a header is added, it has the following fields:

Return-Path:: contains the address of the sender. This is the Internet address specified by the -f option. When no -f option is given, it is an address formed by combining the user name of the current user with the domain name specified in the registry (either in HKLM\System\CurrentControlSet\Services\Tcpip\Parameter\Domain or HKLM\System\CurrentControlSet\Services\Tcpip\Parameter\DhcpDomain, depending on which is populated).
Subject:: contains the specified subject text.
From:: contains the same address as the Return-Path: field.
Date:: contains the date and time that the smtpmail command was issued.
To:: contains the list of users to receive the message as specified on the command line.

Authentication

When smtpmail attempts to connect to a server, the following steps are performed:

smtpmail attempts to connect using the user name and password specified with -u and -p (prompting for a password, if no -p is given and login credential passing is disabled) by cycling through various authentication mechanisms until connection is acheived. When no -u is specified, smtpmail tries to connect using anonymous authentication, that is, no user name or password are passed to the server.

When login credential passing is enabled (either with -A or by setting the TK_ENABLE_CREDENTIAL_PASSING variable) and -u is specified, smtpmail passes that user name to SSPI and lets Windows determine the appropriate password and cycles through various authentication mechanisms until the connection is achieved.

When login credential passing is enabled and no user name is specified with -u, smtpmail uses various methods to determine the user name depending on the authentication mechanism being attempted. For example, with SSPI mechanisms, no credentials are passed and Windows determines what user name should be used while with CRAM-MD5 or LOGIN, the current logged in user name is used (along with the domain if necessary).

Normally, login credential passing is disabled for the smtpmail utility. However, by setting the environment variable TK_ENABLE_CREDENTIAL_PASSING or by specifying the -A option on the command line, you can enable its use.

The following authentication mechanisms are supported for smtpmail:

CRAM-MD5: Uses a keyed MD5 checksum created using a shared secret string (known only to the client and server) as the key. With this mechanism, the shared secret string does not need to be stored as clear text on the server and, thus, is more secure.
DIGEST-MD5: Uses a MD5 checksum (similar to that generated by the md5sum utility) generated from the user name, password, and other information for authentication. This mechanism is only slightly more secure than BASIC.
GSSAPI: Stands for Generic Security Systems Application Programming Interface. It is a generic API for performing client-server authentication. As such, it allows applications to pass or receive credentials without knowledge of the specific authentication mechanism being used. GSSAPI has been implemented for a range of underlying mechanisms (such as Kerberos) based on secret-key and public-key cryptography. SSPI (Security Service Provider Interface) on Windows systems can generate GSSAPI-compatible Kerberos packets.
LOGIN: Is a not particularly secure authentication method that uses primarily clear text to transmit the user name and password. This is similar to the BASIC authentication method used by the web utility.
NTLM: Is an authentication mechanism used by Windows, particularly as a integrated single sign-on (SSO) mechanism. It uses a challenge-response dialog between the client and server to allow the client to prove its identity without actually sending a password.

EXAMPLES

You can use smtpmail as the mail delivery agent for mailx by adding the following line to your ROOTDIR/etc/mailx.rc file:

set sendmail=c:/mks/mksnt/smtpmail.exe

Note that you must replace c:/mks/mksnt with the path to the smtpmail executable on your system.

ENVIRONMENT VARIABLES

MAILHOST: specifies the machine to be used as the mail host when the -h is not specified.
TK_ENABLE_CREDENTIAL_PASSING: When set, enables the passing of your current login credentials to the server.
TK_SMTPMAIL_FROMADDR: specifies an Internet mail address that identifies the sender. See the description of the -f option for the format of this address. When set, this environment variable overrides any "from address" set with the -f option.

DIAGNOSTICS

Possible exit status values are:

0

The message was successfully transmitted to the remote host. This does not mean that any of the specified users actually received the message, only that it was successfully sent on the first stage of its journey.

1

Failure due to any of the following:

— could not connect to the remote host

— the remote host rejected all of the supplied recipients

— the connection to the remote host was closed prematurely

PORTABILITY

Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

AVAILABILITY

PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

smtpmail
send mail using SMTP

Command