CMail Usage

Usage

CMail 0.8.11 amd64 (LibreSSL 3.9.2), May 23 2024

Configuration

CMail operates in three modes:

(S)MTP mode is the default and is used when CMail is both constructing and sending an e-mail.
(F)ile mode can be used to construct an e-mail message for subsequent delivery via either CMail or another application.
(P)reconstructed e-mail mode is used to send e-mails constructed using File mode or another application.

Not all settings can be used with each mode. E.g., Settings labelled SF- apply only to SMTP and File modes.

CMail applies configuration options from a default configuration file, a command line specified configuration file, and from the command line itself, in that order. Settings for which multiple values can be assigned (E.g., -to) are ADDED from each configuration. For settings that can only be specified once, the last occurrence will be used. I.e. You can specify a default configuration in cmail.conf, and override settings for individual messages by specifying another config file, or via the command line.

Command line parameters will undergo code page conversion, unless -clutf8 is specified. Configuration files are assumed to be UTF-8 or ASCII.

The default configuration is stored in %APPDATA%\cmail.conf.

Configuration files must contain one setting per line, and do not include the '-' prefix. A '#' may be used to comment out a line.

Mandatory Options / Mode Selection

-host:[user:pass@]host[:port]

S-P

Specifies the SMTP server to be used to deliver the message. A username and password may optionally be specified for SMTP authentication. If user credentials are supplied, implies -starttls if authentication is not offered prior to STARTTLS. If -oauth is specified, use the OAuth token as the password.

-file:file

-F-

Enables (F)ile mode and specifies a filename to output the e-mail to.

-emailfile:file

--P

Enables (P)reconstructed e-mail mode and specifies a file containing a preconstructed e-mail for delivery via SMTP.

-from:address[:alias]

SFP

Specifies the e-mail address, with optional alias, to appear in the 'From' header of the message. This setting is required for SMTP and File modes. In Preconstructed mode, the 'From' header will be used if this setting is omitted.

Recipients

-to:address[:alias[:DSN]]|@file

SFP

Adds a recipient in the 'To' field of the message or specifies the name of a file containing a list of recipients. This setting may be specified multiple times.

-cc:address[:alias[:DSN]]|@file

SFP

As above, for CC recipients.

-bcc:address[::DSN]|@file

SFP

As above, for BCC recipients.

-reply-to:address[:alias]

SFP

Specifies the e-mail address to which replies should be sent.

The -to, -cc, and -bcc settings each add either a recipient to the message or a list of recipients from file.

When adding individual recipients, the first parameter is required and specifies an e-mail address. The second parameter can be used to specify an alias, usually the name of the recipient. The alias may be quoted (using double quotes, escaped as necessary), although this is only required where a colon may be present in the alias. The final parameter specifies DSN options for the recipient, using the same format as the -dsn option documented above. E.g., -to:user@example.com:"Example User":DF. Where an alias is not desired (or not applicable in the case of BCC), this field may be left blank. E.g., -bcc:user@example.com::SFD.

When adding recipients from file, the file name must be prefixed with '@'. E.g., -to:@filename. The file should contain one e-mail address per line in either the form "User Alias <user@example.com>", specifying an address with an alias, or "user@example.com" specifying only an address, both without quotes.

When -emailfile is used, recipients will be determined by the To and Cc header fields of the preconstructed message if a recipient setting is not present. In all other cases, at least one recipient setting is required.

Content And Formatting

-subject:subject text

SFP

Specifies the message subject (literal string).

-body:message body

SF-

Specifies the message body. Note: '\\','\r','\n', and '\t' are valid escape codes.

-body-file:file[:charset]

SF-

Specifies a file containing the message body. Implies -body-qp (-body-64 may also be specified).

-body-64

SF-

Use base64 encoding for the message body.

-body-qp

SF-

Use quoted-printable encoding for the message body.

-body-html:file

SF-

Specifies a file name containing a UTF-8 encoded HTML body. Attached images can be referred to using their Content-ID if attached using -ai.

-head:header:value

SFP

Add the specified header and header value to the message. This option may be specified multiple times. E.g., -head:X-No-Archive:Yes.

-delhead:header

--P

Remove the specified header. This option may be specified multiple times.

-rawhead

--P

Preserve original headers. Can be used with -head and -delhead but all other header settings will be ignored. Non-configurable headers such as Date and Message-ID will not be modified.

-linelen:length

SF-

Specifies the line length for the plain text message body. The minimum and default is 78 characters. The maximum is 998 characters.

-mime

SF-

Force use of MIME for the message body in messages without attachments.

-dotstuff

-F-

Replace '.' with '..' at the start of lines. Use with third-party tools that do not automatically do this when onsending via SMTP.

-priority:n

SFP

Set the message priority to 'n', 1 = Highest, 2 = High, 4 = Low, 5 = Lowest.

SF-

Read message body from stdin.

Attachments

-a:file

SF-

Attach the specified file. CMail will select base64 or quoted-printable encoding automatically. Files containing >85% ASCII text in the first 4kB will be quoted-printable encoded. Attachments of type message/* will use 7-bit transfer encoding for RFC compliance.

-a64:file

SF-

Attach the specified file using base64 encoding. Attachments of type message/* will be identified as text/plain.

-aqp:file

SF-

Attach the specified file using quoted-printable encoding. Attachments of type message/* will be identified as text/plain.

-ai:file

SF-

Attach the specified file as an inline (multipart/related) attachment, usually used for images referenced in a HTML message body. The Content-ID is the file name, URL encoded where applicable. This value is case-sensitive. Requires -body-html.

-auu:file

SF-

Attach the specified file using uuencoding. These attachments are encoded within the message body.

-awild:options:pattern[/…]

SF-

Attach multiple files matching one or more patterns. See below.

Using the -awild option, CMail supports adding multiple attachments from a source directory using patterns. Multiple patterns may be specified, separated by '/', and are evaluated from left to right. Patterns may include standard wildcard characters '*' or '?', and character sets and ranges [], and may be prefixed with a logical NOT operator '!'. In addition to the patterns, a number of options are available to modify the behaviour.

Options (Case sensitive):

H - Include hidden files
S - Include system files
A - Include ONLY files with the Archive attribute set
R - Recursive (include files in subdirectories)
C - Case sensitive matching
U - Use uuencoding
6 - Use base64 encoding
Q - Use quoted-printable encoding
I - Create inline attachments for use with -body-html

E.g., To recursively include logs from 1970, but exclude any .tmp files, you could do the following -awild:R:c:\logs\1970*/!*.tmp

Connection Options

-4

S-P

Force the use of IPv4.

-6

S-P

Force the use of IPv6.

-authtypes:type[,type…]

S-P

A comma-separated list of authentication types which may be used with the upstream server. Supported values are CRAM-MD5, PLAIN, LOGIN, OAUTHBEARER and XOAUTH2.

-helo:hostname

S-P

Use the specified hostname in HELO/EHLO.

-oauth

S-P

The password is an OAuth token.

-return-path:address

S-P

Specify the return path (envelope) address.

-proxy:[user:pass@]host[:port]

S-P

Connect via a proxy. Authentication is only supported for HTTPS proxies.

-proxytype:type

S-P

Specify the type of proxy being connected to. Supported proxy types are SOCKS (default proxy type, default port 1080), and HTTPS (default port 8080).

-requiretls

S-P

Require TLS be used for mail delivery. Implies -starttls.

-starttls

S-P

Attempt to use TLS if STARTTLS is advertised in response to EHLO.

-smtps

S-P

Specifies that the port being connected to uses SMTPS (SSL/TLS without STARTTLS). This setting changes the default port to 465. This method of securing mail transfer is deprecated, use -starttls if the target server supports that method.

-verify

S-P

Verify certificate when connecting using SMTPS or STARTTLS is used. Note, this setting only verifies certificates when TLS is used. Add -requiretls if TLS is required.

-verify-ca-path:path

S-P

Specifies the CA path to use for certificate validation. Certificates should be in cert.pem or the certs subdirectory. Required if -verify is specified.

-tls-ciphers:ciphers

S-P

Set which ciphers can be used (values from LibreSSL). Values are secure, compat, legacy and all. Default is all.

-tls-protocols:proto[,proto…]

S-P

Comma-separated list of protocols that may be used (values from LibreSSL). Values are tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.3, secure and all. Default is all.

-timeout:seconds

S-P

Sets the socket timeout.

Delivery Status Notification (DSN) / Message Disposition Notification (MDN)

-dsn:options

S-P

Specifies the default DSN types to request if no DSN settings are specified for the recipient, using the first letter of each DSN type. Acceptable values are (S)uccess, (F)ailure, (D)elay, and (N)ever. E.g., -dsn:SFD will request a DSN for success, failure and delay. If (N)ever is included in the list, it will take precedence over all other values.

-dsnid:id

S-P

Sets the envelope ID for DSN requests. If not set, a random ID will be used.

-mdn

SFP

Request MDN (read receipt).

DomainKeys Identified Mail (DKIM)

CMail can optionally sign e-mail using DKIM signatures. DKIM is an advanced option requiring the creation of public/private key pairs and editing DNS records. DKIM signing is usually performed by e-mail submission servers. Refer to RFC 6376 for additional information.

-dkim:domain:selector:key

SFP

Specifies a domain, selector and the associated key file (in PEM format) to allow DKIM signing of e-mail. This setting can be specified multiple times, allowing for dual signing using RSA and Ed25519 keys. When specified multiple times, the last specified selector for the sending (or default) domain and key type will be used.

-dkim-default:domain

SFP

The default domain and associated selector will be used if no specific -dkim option matches the sender’s from domain.

-dkim-algo:algorithm

SFP

Use the specified DKIM signing algorithm. Supported values are ed25519-sha256, rsa-sha256, rsa-sha1, best (default) and all. This setting may be specified multiple times. The best setting follows best practice and will attempt to sign e-mail using both ed25519-sha256 and rsa-sha256, where suitable keys have been provided.

-dkim-canon:canon

SFP

Specifies the DKIM canonical form (simple or relaxed) for the message headers and body. Supported values are s/s (default), s/r, r/s and r/r.

-no-dkim

SFP

Disable DKIM signing of the message. This setting allows you to ignore any DKIM records in the configuration and send via hosts that will alter messages or sign on behalf of your domain.

Debugging

-d

S-P

Debug mode. Show data to and from the server. Passwords are not logged.

-dd

S-P

Extended debug mode. As above but adds socket and TLS debugging information. Passwords are not logged.

-showcmd

---

Display the command line parameters as seen by CMail both before and after conversion to UTF-8. Note that this option must be specified on the command line and CMail will exit after showing the output.

Command Line Only

-body-literal

SF-

Do not convert line breaks to CRLF on a message body specified using -body-file. The body will be quoted printable encoded (-body-64 may also be specified).

-clutf8

SFP

Assume command line parameters are UTF-8. Disables code page conversion and may be necessary when calling CMail from within other applications.

-encryptpass:password

---

Output an encrypted version of the specified password and exit. The encrypted password can be used with the -host option. Encryption only provides protection against casual password observation.

-bindpass

---

Encrypt password using a host-specific key.

-config:file

SFP

Apply the configuration from the specified file.

-nodefault

SFP

Do not apply settings from the default cmail.conf.

-skipnofile

SF-

Do not check attachments exist before constructing e-mail.

Output

CMail indicates success of failure through error codes. CMail will return 0 on success. In most other cases, the error code will reflect the actual SMTP error code, with values less than 100 indicating a configuration error (or rarely, an internal error). Detailed results may also optionally be output in JSON format when using SMTP or Preconstructed modes.

-results:filename

S-P

Output e-mail delivery details to a JSON file. Use '-' to output to stdout.

Error codes:

    0 - Success
 <100 - Configuration or internal error
>=100 - Actual SMTP response code

Example -results output:

{
   "subject": "Test",
   "date": "Date: Sun, 10 Mar 2024 00:00:00 GMT",
   "from": "user@example.com",
   "host": {
       "hostname": "mail.example.com",
       "ip": "172.16.1.1",
       "port": 587",
       "protocol": "ESMTPS",
       "tls": "version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384"
   },
   "recipients": [
       {
           "e-mail": "invaliduser@example.com",
           "status": "rejected"
           "smtp response": "550 Invalid recipient: <invaliduser@example.com>"
       },
       {
           "e-mail": "user@example.com",
           "status": "accepted"
       }
   ],
   "message-id": "<MYPVqgMA2iA_AaT2@example.com>",
   "status": "success",
   "smtp response": "250 2.0.0 7ae935ba Message accepted for delivery"
}

Note: The 'status' value for an e-mail may indicate 'success' or 'failure', with 'smtp response' indicating the response from the server. An 'error' value may also be set where applicable. A recipients status may be 'accepted' or 'rejected', with 'smtp response' set if the address is rejected.