jmail, jtool mail

A platform agent tool used to send an email message.

When run in job-context with the -j or -job-context switch, the -server switch is optional (it will use the SMTP server specified in the central Redwood Server).

This tool can be used outside job-context as a command line email client, however, the -server switch is mandatory.

Syntax

jmail [-h|-?|-help] [-l <loglevel>] [-f <logfile>] [-j|-job-context] [-server <server>] [-port <portnr>] [-o|-origin <sender>]
      [-i|-from <from>] -t|-to <to-list> [-c|-cc <cc-list>] [-b|-bcc <cc-list>] [-reply-to <reply-to-list>] [-s|-subject <subject>]
      [-mt|-mimetype <mimetype>] [-encoding <charset>] [-[no]mime] [-nosend] [-protect] [-historic] [-secretfile <secretfile>]
      [-header <header> ...] [[-content-ID <content-ID>] [-description <description>] [-a|-attachment <attachment>]]* [<file>]

  use - for file from stdin

Argument	Default Value	Description
-a,-attachment `<attachment>`		MIME attachment.
-b,-bcc `<cc-list>`		'Bcc:' address list.
-c,-cc `<cc-list>`		'Cc:' address list.
-content-ID `<content-ID>`		Content-ID for the following file attachment; must follow syntax `<name>@<name>` and be globally unique, see RFC 2392 for more information.
-description `<description>`		Content-Description for following file attachment; will be used in the Content-Description header of the MIME attachment. In some mail clients, the Content-Description header is used in the file name of the attachment.
-encoding `<charset>`		MIME characterset.
-f `<logfile>`	${JCS_LOGFILE:-stderr}	Log to file instead of stderr; defaults to environment variable ${JCS_LOGFILE} or stderr when the environment variable is not set.
-h,-?,-help		Show this help and exit.
-header `<header>`...		Additional mail header.
-historic		Do historic interpretation of recipients (to, cc, from, bcc) for v7/8 compatibility.
-i,-from `<from>`		'From:' address. You use the "`<name> <<email_address>>`" syntax to specify non-ASCII characters, where the email address is inside <>; such as "Anwälte Musterfrau und Mustermann`<emusterfrau@example.com>`". You can also use the syntax as defined in RFC 2047.
-j,-job-context		Obtain environment from job-context.
-l `<loglevel>`	${JCS_LOGLEVEL:-info}	Set the logging level; defaults to info if the JCS_LOGLEVEL environment variable is not set.
-mt,-mimetype `<mimetype>`		MIME message type; if not specified, the MIME type will be detected based on the file extension.
-[no]mime		Send as plain text or as MIME format.
-nosend		Do everything but sending the actual email; a dry run.
-o,-origin `<sender>`		SMTP sender name.
-port `<portnr>`	25	SMTP server port.
-protect		Encrypt mail using TLS/SSL.
-reply-to `<reply-to-list>`		'Reply-To:' recipient address list.
-s,-subject `<subject>`		Subject of the mail.
-secretfile `<secretfile>`		Secretfile for SMTP Auth generated by jsecret.
-server `<server>`		SMTP server hostname or address.
-t,-to `<to-list>`		'To:' recipient address list.
`<file>`		File to send as body.

TLS Arguments

The arguments require the -protect argument.

Argument	Environment Variable	Description
-tlsv1_3, -tls13	`JCS_SSL_METHOD=tlsv1_3`	Use TLS v1.3 secured connection.
-tlsv1_2, -tls12	`JCS_SSL_METHOD=tlsv1_2`	Use TLS v1.2 secured connection.
-tlsv1_1, -tls11	`JCS_SSL_METHOD=tlsv1_1`	Use TLS v1.1 or better secured connection.
-tlsv1, -tls	`JCS_SSL_METHOD=tlsv1`	Use TLS v1.0 or better secured connection (default).
-sslv3, -ssl	`JCS_SSL_METHOD=sslv3`	Use SSL v3 or better secured connection.
-cipherlist `<text>`	`JCS_SSL_CIPHERLIST`	Set list of available ciphers.
-passphrase `<text>`	`JCS_SSL_PASSPHRASE`	Set passphrase for private key.
-key `<file>`	`JCS_SSL_KEYPATH`	Set private key.
-cert `<file>`	`JCS_SSL_CERTIFICATE_PATH`	Set public certificate.
-ca `<file	path>`	`JCS_SSL_TRUSTED_CERTIFICATE_FILE`	Trusted CA certificates path or file.
-[no]verify	`JCS_SSL_VERIFY_CERT`	(Do not) verify peer (server or client) certificate.
-verify-names `<namelist>`	`JCS_SSL_VERIFY_SERVER_NAMES`, `JCS_SSL_VERIFY_CLIENT_NAMES`	Verify peer (server or client) certificate hostname against list.

Using Standard Input

When you specify -, you can provide the input from standard input by piping a file or here-document (see Using standard in (-) example below) to jmail, or typing the text out.

You use - for interactive mode as well, once you have finished typing, you can hit <Control+D> (hold down the Ctrl and the letter d keys, at the same time, starting with Ctrl ) to terminate and send email.

Encoding

The default character set is not set in the MIME headers by default; you specify one using the -encoding switch. The MIME type of an attachment is derived from the file extension of the attachment if you do not specify one; Redwood recommends you set a MIME type for each attachment.

Header values are encoded according to RFC 2047 when they contain non-ASCII values. MIME parameter values are encoded according to RFC 2184 when they contain non-ASCII values.

For more information on encoding and character set issues, see Support Note 115542.

Forcing RFC 2047 syntax:

To avoid character set problems, you can encode the text containing non-ASCII characters and pass along the encoded string.

(=?<charset>?<encoding>?<encoded_text>?=)

<charset> - the character set of the original, decoded text.
<encoding> - the encoding technique to use; quoted-printable (Q) and base64 (B) encoding are defined in the standard.
<ecoded_text> - the encoded string.

The examples below contain the plain text to encode for illustration purposes.

You want to use Anwälte Musterfrau und Mustermann as the sender name. In the following example, you use base64 encoding in Powershell. Do note that UNICODE on Windows is UTF-16, if your text is UTF-8, like below, you use UTF8.GetBytes, if your text is UTF-16, you use UNICODE.GetBytes instead. Note that if you use UNICODE.GetBytes on a UTF-8 string, the characters in the decoded string will be separated by a space and some characters might not be displayed properly. Note also that when you encode a file, the file might contain line ending characters, these will have to be removed prior to encoding.

PS > $Bytes = [System.Text.Encoding]::UTF8.GetBytes("Anwälte Musterfrau und Mustermann")
PS > $EncodedText =[Convert]::ToBase64String($Bytes)
PS > jmail -server mail.example.com -t client@company.com  -i "(=?utf-8?B?${EncodedText}?=) emustermann@example.com" -s "AW: Vertragsrecht" -a robotics.txt

On UNIX with base64 encoding:

$ jmail -server mail.example.com -t client@company.com  -i "(=?utf-8?B?$(jecho -base64 "Anwälte Musterfrau und Mustermann")?=) emustermann@example.com" -s "AW: Vertragsrecht" -a robotics.txt

Return Codes

0 - the message was sent successfully
1 - (warning) not all recipients were accepted, message was successfully sent to the recipients that were accepted
2 - (error) either no recipients were accepted or the server refused the message
3 - (error) either the message could not be generated or the server could not be reached

Embedding Images

You specify image attachments to embed using the cid protocol in combination with the Content-ID to specify the image to insert:

<img src="cid:<content-ID>" alt="some image" />

<content-ID> - content-ID of a file attachment, in this case an image. Note that jmail automatically generates such an ID for each attachment if none is specified. If you wish to insert an image, you must know the Content-ID, so you use the -content-ID switch to set it.

A common method is to use the output of uuidgen -t, the @ sign, followed by the hostname.

<img src="cid:38c18c80-b49c-11e7-a2ee-fc15b4e60bb2@pcjdoe.example.com

In the Inserting an image into an email example below, the GUIDv4 environment variable is used in combination with the @ sign and the hostname.

Example

Send a mail with text file as body

jmail -server smtp.example.com -i jdoe@example.com -t jsmith@example.com -s "Please see attached" readme.txt

Send a mail with a text file as attachment

jmail -server smtp.example.com -i jdoe@example.com -t jsmith@example.com -s "Please see attached" -a readme.txt

Send a mail with an HTML file as attachement

jmail -server smtp.example.com -i jdoe@example.com -t jsmith@example.com -s "Please see attached" -mimetype text/html -a readme.html

Send a mail with an HTML body with an additional plain text file

jmail -server smtp.example.com -i jdoe@example.com -t jsmith@example.com -s "Please see attached" -mimetype text/html -a readme.html -mimetype text/plain -a readme.txt

Using standard in (-)

echo "%pMail_Body%" | jmail -server %pMail_Host% -t %pMail_To% -s "%pENV_Mail_Subject%" –

echo "This should be text in body of email" | jmail -server $Servername -t $Recipient -s $Subject -a "/tmp/file.txt" -a -

jmail -server smtp.example.com -i jdoe@example.com -t jsmith@example.com -s "Please see attached" -mimetype "text/html" -a "report.html" -mimetype "text/plain" -a - <<EOF

Hi ${User:-user},

Please review the attached report.

Regards,

${From:-Reporting}

EOF

Inserting an image into an email

The following example can be used both in and outside of job-context, provided you change the -server to your SMTP server. It illustrates how you can insert text fragments or an image, the latter using the cid protocol.

##
### Example of generating an email with an embedded PNG picture.
##

if [ -z "${JCS_JOB_ID:-}" ]
then
  EXTRA_ARGUMENTS="-server smtp.example.com"
else
  EXTRA_ARGUMENTS="-j"
fi

inline_html='<html>
<body>
<p>This <em>Text</em> has been inserted inline!</p>
</body>
</html>'

cat <<EOD | base64 --decode > image.png
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
VpCfn8/YsWN544032ly7trY284QoUz0thgzIqm65CxPLJnoC/eijjzoVYG5uLq7rMmvWLMaMGcOa
NWtoampKq9MYiUSYMGECd999N0opXNeloKCgfQaYfftaRwkyFWUVYMpD2bbARSAvSCAQ8D4fOnSo
U0ICgQCWZbFmzRqi0SirVq1i+vTpRKNnX33qui65ubksWbKEefPmUV1dTV1dHSJCbm5uBxOolKK+
vj5zhChLLReRrMuMFZe0TkdpbGw847EJB75z505WrVrF6tWrqaioYOXKlVx88cVEIl3LY0ajUaZO
ncpTTz2FZVksWbKETZs20dDQ4HUKT0fIkSNHMmiylMxLOeXRjRg0cJC339zc3Kn5STYhkUiEQCBA
XV0dixYt4qGHHmLBggXU1dXx/PPPd2rGIpEI48aN44477mDQoEE8++yzvPXWWwSDQZRSnqad7lwR
4dSpU5nREBGmipKszBurJDv9p8azE4QkjnNdl/PPP5+ioiJs22bo0KGsWrWKKVOmtNEW27YZPHgw
S5cuZeHChYRCIUSEyy67jGAw2OXSoMRx6WuIpSrTSAl2K5rirQ4gJyenU+GIiBfKmqaJ67rceuut
lJeX8+677/LEE0/Q2NjIddddR2VlJddeey3r1q3jiy++YObMmZSVlbF7924efvhhGhoauPTSS5k7
dy6rV69m7dq17NixA8uyThsyJwcVGSFEYBpZOq7yRX1r9U9+fv4Zk4mJnnV5eTnTp08nHA5TVVXF
3r17sSyLYDBITU0N27Zto6Kigttvv538/Hz27t3Lk08+SV1dHYFAgJycHHbv3s3ixYuZNm0a999/
PxMnTvSCC9u2O4TRiegrE4T0Q8n5ZClOHmlbrDh48GCam5s7dcbRaJTKykqvL2KapteyE5pkmiav
vfYamzdvxnVd75jkaA7Asiy2bNnC9u3bue+++xgzZgzRaJSWlpYOhDiOQ3FxcQZ8iHB1theAvb/r
fW9/9OjRnZqscDiMiLB+/XrWrVuH1tojybZtbNv29h3HwTAMLMtCRLzfk4+LRqM4jsOJEyd4/PHH
2b9/PyJCY2NjB0KGDBniOfu0NEQMdXk2kyFBxWu/e43S8aVorSktLaW2trZDpldEaG5uRmvNzTff
zNVXX00oFPIShe173mcKChL7SikMwyAYDFJYWEggEEApxeHDhzv4j+TRw/QIES5pHajLwihLKV76
1UYWL1iMiFBWVsaaNWs6EGIYBi+//DIlJSUUFRVRUlKSmcLpxABd/O8HH3zArl272qRvIpEI11xz
jRd6pyVIFVC1otRl2Vwq4bTYNDU1kZeXB8Bzzz3HO++8c9pjw+EwBQUFDBgwoE22t7P+Q2fhayLj
m8j2hkIhjh07huM4bXwSQGFhIStWrPBOT9Opy6hsr1uRoGLlv67isR886pmk7du3k5OT0+HYYDBI
c3Nzp44/XW1tT6pt21RWViYX0b2SrlPP/nnfSvGjqh95pqOgoIBJkyZlxCSli5KSEkpLSxMmTYBl
6RAySPpIVVcoFKLqn6s8kzJ37tyMViemgmg0yvz58xMNQwP/IyK70hHpaCPX3EMfgRO1OXHsBAP6
x0YIPv/8cx577LEO/YeeQCQS4Z577kkM3SayHOcDR9LRkEL6EAzLZMq0Kd7YdnFxMQ8++CDhcLhH
n8O2bW644YbkcXQBviciR0QkjUUwlVyqTPVXfYmUA58eQAzFtd/6NgBDhw6lqKiIt99++7Qjid1h
piZNmsScOXOSM8xbReT7yeyk2CmUO1XA+Bl9DE6LzcZNG7lp5k3edx9++CErV67s1tKgcDjMnDlz
qKioSI6qPhaRMcnp/9QJMWWxsown6YNwWmx+s2Uz37lhSmve6+RJVq5cycGDBzNKjOu65OXlsWjR
ovaV7/uBUYCbkekIYqkVylQ/oI9W0DstNs/97DnuuvMuLwROFK+tX7+eUCiUFjGJlMuMGTOYMWNG
+3H0HSIyMaMTdpSlfiymup8+DCdk8zd3zuU/nl/bofDgzTffZOvWrezbt88b9etKLz0SiVBYWMj1
119PRUVF8nmJaOqfROSRzmbmpkGIsUFMZvf1KSau61JUVMQrL73MlVdc2YGYpqYm3nvvvTaTPpub
m73p04nkYWLS5/jx47ngggva8BSX8+fANBHZdaZp0qkTElDVotT1X5cpP06LzXdunMrTTz3NyBEj
2hCT4jzzBBEngSUi8tOuXCedfkjB12n+lZFrsvW3Wxk1ciR/OelbbNy0sbXVdp2M5HzM68DNIjJI
RH7a1eukoyF/FEON5GsKJ2qDC5PLJzN1yrRTixYsfBO4tJMO8Ulal9b4LfBrEXFT0aw0CDGOiiHn
cQ7AtZ0TOqrz2znwABCN9yfaOPZ0RlFTJySoHOnJyXm9CO1q1w07PTKhJA2ByjlBRtwz9Ni7njtC
TQc9GLykSkifGQvpa0iVkIHn0poD8caXk82E9D/31oDAzGZCDmnH/aV2Wwems2GMOuOuPBZh4Tr6
f4GmvuKuysRUN4uiEiXDRYRsrtXqVPrJqRJXo7X+NY5+STt6PSkucpMN8UOBGFIphtyCSLmo+Ipq
3fPP8VJv99Ju+Q0XQL+hXbZo2/0NsZWGvoYBncgkZcotCLNRMjieIc383HUNSCczInTcnGqtQf4P
9H40+7Rmj3b0R2i9i9iqoudahM0wMdWtouSvEcad9RS4eLWMTvxvQgiBPgpyFPRRtHwJ+ksNDbj6
sNYcwtWHgEN0cVXSc42Q9hgBDBGRgSIDE1uBXCNaHDRRjW5BEwJOxbdGYkm8MD58+PDhIxvw/5s6
9S8WUS2kAAAAAElFTkSuQmCC
EOD

UNIQUE_ID=$(jtool echo '${GUIDv4}')@$(hostname)
echo "Generated unique GUID string $UNIQUE_ID"

cat <<EOD > body.html
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body>
  <h1>
    Generated by jmail
  </h1>

  Here is a small image <img height="64" width="64" src='cid:${UNIQUE_ID}' alt='user email image' /> from <a href="https://openclipart.org/detail/287799/user-mail">https://openclipart.org/detail/287799/user-mail</a> that has been modified.

${inline_html}

</body>
</html>
EOD

jtool mail $EXTRA_ARGUMENTS -to "John Doe <jdoe@example.com>" -subject "Example email" body.html -description "user email image" -mimetype "image/png" -content-ID "${UNIQUE_ID}" -a image.png -l trace -f jmail.log

Specifying non-ASCII Characters

jmail -server smtp.example.com -i "Jörg Doe <jdoe@example.com>" -t jsmith@example.com -s "Please see attached" readme.txt

Using RFC 2047 syntax:

To avoid character set problems, you can encode the text containing non-ASCII characters. The examples below contain the plain text to encode for illustration purposes.

You want to use Anwälte Musterfrau und Mustermann as the sender name. To encode this, you use the following syntax =?<charset>?<encoding>?<encoded_text>?=. Two encoding techniques that are supported are quoted printable ( Q ) and base64 ( B ) encoding.

In the following example, we use base64 encoding in Powershell. Do note that UNICODE on Windows is UTF-16, if your text is UTF-8, like below, you use UTF8.GetBytes, if your text is UTF-16, you use UNICODE.GetBytes instead.

PS > $Bytes = [System.Text.Encoding]::UTF8.GetBytes("Anwälte Musterfrau und Mustermann")
PS > $EncodedText =[Convert]::ToBase64String($Bytes)
PS > jmail -server mail.example.com -t client@company.com  -i "(=?utf-8?B?${EncodedText}?=) emustermann@example.com" -s "AW: Vertragsrecht" -a robotics.txt