Examples

Basic E-Mail

cmail.exe -host:smtp.example.com -to:user1@example.com -from:user2@example.com "-subject:Simple test e-mail" "-body:This is just a test."

Attachments

cmail.exe -host:smtp.example.com -to:user1@example.com -from:user2@example.com "-subject:The file we discussed" "-body:See attached" "-a:c:\file_path\file_name"

Authentication

cmail.exe -host:Bob:qwerty@smtp.example.com -to:user1@example.com -from:user2@example.com "-subject:Authenticated message" "-body:This message was sent using the username 'Bob' and the password 'qwerty'."

Using a text file as message body

To use the content of a text file as the message body, you can either pipe text into CMail or specify a file using the -body-file setting.

type file.txt | cmail.exe -host:smtp.example.com -to:user1@example.com -from:user2@example.com "-subject:Body from text file" --

or (CMail 0.7.7 or later)

cmail.exe -host:smtp.example.com -to:user1@example.com -from:user2@example.com "-subject:Body from text file" -body-file:file.txt

Adding recipients from file

This option is available in CMail 0.8.0 or later.

The -to, -cc and -bcc settings can accept a file name, prefixed with '@'. The file should contain one entry per line, each consisting of an e-mail address or an alias with an e-mail address in angled brackets (the same format used in e-mail headers).

cmail.exe -host:smtp.example.com -to:@recipients.txt -from:user@example.com "-subject:Recipients from file"

Example recipient file.

Example User <user1@example.com>
user2@example.com

SSL/TLS (STARTTLS)

This method is for servers supporting STARTTLS. This is the method you should use to send e-mail via GMail. In this example, the -host option is specifying port 587, which some services require you to use for message submission. You can use -requiretls instead of -starttls to only send when encryption is possible, otherwise CMail will attempt to send messages even if encryption is not offered.

From 0.8.0 onwards, STARTTLS will be used automatically if authentication is not available prior to establishing a secure connection. The -starttls setting must still be used to ensure credentials are not sent over insecure connections if authentication is offered without TLS.

cmail.exe -host:Bob:qwerty@smtp.example.com:587 -starttls -to:user1@example.com -from:user2@example.com "-subject:Secure message" "-body:This message was sent securely if the server supported STARTTLS."

SSL/TLS (SMTPS)

This method is for servers requiring SMTPS. You should use the STARTTLS method above if supported, as SMTPS is considered deprecated. This method is the equivalent to using Blat with stunnel. Note, -smtps changes the default port to 465.

cmail.exe -host:Bob:qwerty@smtp.example.com -smtps -to:user1@example.com -from:user2@example.com "-subject:Secure message" "-body:This message was sent securely."

Password encryption

This option is available in CMail 0.8.0 or later.

Running CMail with the -encryptpass option will generate an encrypted password which can be used in place of the plain text password in the -host setting. The password is protected using a static key by default, and can be bound to a specific Windows install using the -bindpass option. Encrypted passwords provide protection against casual observation only.

cmail.exe -encryptpass:password

OAuth2 authentication

CMail supports user-supplied OAUTHBEARER/XOAUTH2 tokens. There is no built-in mechanism to request or refresh tokens. If you are able to obtain a token, authenticating using OAuth is similar to other authentication methods with the exception that the OAuth bearer token is used in place of the password and no other authentication methods will be available. OAuth authentication is enabled using the -oauth setting.

cmail.exe -host:user@example.com:ya29.a0A...163@smtp.example.com -oauth -to:user1@example.com -from:user2@example.com "-subject:OAuth2 authenticated message" "-body:This message was sent using the username 'user@example.com' with an OAuth2 Bearer token."

DKIM signing e-mail

DKIM signing is normally performed by the SMTP submission server. In rare instances it may be necessary for clients to sign e-mail before sending. If you find yourself needing to do this, the example below shows you how.

CMail automatically detects the key type (RSA or Ed25519) and can sign the same message using multiple algorithms. Assuming the private key is an RSA key, the e-mail below will be signed using RSA-SHA256 with relaxed/relaxed canonicalisation.

cmail.exe -host:smtp.example.com -to:user1@example.com -from:user2@example.com "-subject:DKIM signed message" "-body:This message is signed." -dkim:inveigle.net:thingamajig:c:\inveigle.private.key -dkim:example.com:selector:c:\example.private.key -dkim-canon:r/r -dkim-default:example.com

DKIM signing works in SMTP, File and Preconstructed modes. If using both File and Preconstructed modes, it’s recommended to sign only on delivery. Alternatively, -rawhead/-delhead/-no-dkim may be used to remove or avoid invalidating the original DKIM-Signature.

A practical example

CMail can do a lot, but there’s no such thing as a free lunch. The example below addresses the practical problem of sending a directory full of PDF files, while remaining under the default 10MB message limit imposed by many mail systems.

The script operates by constructing a supplementary configuration file for CMail (append.txt) containing a list of attachment commands, and keeping track of the total file size. When the next file would put the e-mail over the size limit, the e-mail is sent, and a new attachment list is started. There are a couple of key points to note here. Firstly, the size limit is set at 7,340,032 bytes, which is 7MB. Adding base64 encoding overhead, the resulting e-mail will safely remain under 10MB. The second consideration is that the attachments explicitly use base64 transfer encoding (-a64 setting). If CMail is asked to select the encoding to use (-a setting), any file that contains mostly text in the first 4KB would be quoted-printable encoded, which aside from being much less efficient for binary data, could put the e-mail over the maximum size.

Note, this script does not split files. Any PDF that is too large will be sent in its own e-mail, and would likely fail to send. If limits are to be exceeded, use of an archival tool such as 7-Zip is advised. This script is provided as-is. Use at your own risk.

setlocal enabledelayedexpansion
set MAXSZ=7340032
set SRC=C:\Some Directory

set SZ=0
pushd "%SRC%"
if exist attach.txt del attach.txt
for /f "delims=" %%a in ('dir /b /os *.pdf') do (
	set /a NEWSZ=!SZ!+%%~za
	if !NEWSZ! gtr %MAXSZ% (
		call :send
		set SZ=0
	)
	echo a64:%%a>>attach.txt
	set /a SZ=!SZ!+%%~za
)
call :send
popd
exit /b

:send
cmail.exe -host:smtp.example.com -to:recipient@example.com -from:sender@example.com -config:attach.txt
del attach.txt
exit /b

©2024 Inveigle.net
HOME | PRIVACY | CONTACT
Hosted on BuyVM/Frantech virtual private servers since 2017.