Mail

5 minute read.

Last Modified 2023-11-17 15:28 EST

The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

Welcome to the TrueNAS SCALE Command Line Interface (CLI) guide!

The TrueNAS CLI in TrueNAS SCALE functions like a text-based version of the web UI with many functional areas grouped into parent and child namespaces that mirror the counterparts in the SCALE UI.

The underlying structure of the CLI namespaces and commands closely follows that of the SCALE API. For more information on API commands, arguments, options, and definitions go to API Keys and click on API Docs in the SCALE UI.

Mail Namespace

The mail namespace has three commands and is based on configuration management functions found in the SCALE API and web UI. It provides access to email configuration methods through the system namespace commands.

Mail Commands

The following mail commands allow you to view or edit mail settings and to send an email using configured settings. You can enter commands from the main CLI prompt or from the system namespace prompt.

Config Command

The config command displays the current system email configuration.

Using the Config Command

Description

config does not require entering properties or arguments. Enter the command and then press Enter. The command returns a table containing current email configuration settings.

Usage

From the CLI prompt, enter:

system mail config

Press Enter.

Command Example

system mail config
+----------------+---------------------+
|             id | 1                   |
|      fromemail | test@test.com       |
| outgoingserver | smtp.mailserver.com |
|           port | 587                 |
|       security | TLS                 |
|           smtp | true                |
|           user | test@test.com       |
|           pass | passw0rt            |
|       fromname | TrueNAS             |
|          oauth | <dict>              |
+----------------+---------------------+

Send Command

The send command sends an email from the system. A valid email send method must be configured before sending an email.

Using the Send Command

Description

The send command has one required property, mail_message, which has two required sub-properties, subject and text, and nine optional sub-properties (see chart below), and one optional property, mail_update, which uses the same properties as the update command.

Enter mail_message or mail_update properties as an array enclosed in curly brackets {}. Enclose properties and values in double quotes, do not double quote boolean values, separate properties from values using a colon, and separate property/value pairs using a comma.

mail_message Properties

Property	Required	Description	Syntax Example
`subject`	Yes	Enter a subject for the email.	`“subject”:"test"`
`text`	Yes*	Required if `html` is not set. Enter the email body text. Text is formatted to HTML using Markdown and rendered using the default email template.	`“text”:"Test message"`
`html`	Yes*	Required if `text` is not set. Enter the email body text and HTML formatting.	`“html”:"Some HTML"`
`to`	No	Enter the address to receive the email. If not set, defaults to the configured admin email address.	`“to”:"test@email.com"`
`cc`	No	Enter an address to carbon copy (CC) on the email.	`“cc”:"test@email.com"`
`interval`	No	Use to define a minimum interval in seconds for the email job to forbid duplicate emails within a given time frame. Defaults to `null`.	`“interval”:"60"`
`channel`	No	Enter the name of the channel to receive the email, if needed.	`“channel”:"notifications"`
`timeout`	No	Enter the send operation timeout limit in seconds. If not set, `timeout` defaults to 300, or five minutes.	`“timeout”:"300"`
`attachments`	No	Full documentation for this property is being developed.
`queue`	No	Set `true` to allow email queuing or `false` to disallow. Defaults to `true`.	`“queue”:false`
`extra_headers`	No	Use to specify any additional email headers, such as to designate the email priority.	`“extra_headers”:{"priority":"urgent"}`

Usage

From the CLI prompt, enter:

system mail send mail_message={“subject”:"test",“text”:"Test message"}

Where test is the email subject and Test message is the email body text. Press Enter.

Command Example

system mail send mail_message={"subject":"test","text":"Test message."}
[0%] ...
[100%] ...
true

Update Command

The update command configures the system email send method using either SMTP or OAuth.

Using the Update Command

Description

update has 9 optional properties (see the tables in Update Properties below). Enter the command followed by one or more property/value pairs. Enclose any values using special characters, for example a period . or @ in double quotes. Separate multiple property/value pairs with a space.

To configure the system email using SMTP, enter the mail update command followed by the SMTP properties.

To configure using OAuth, first obtain a valid OAuth token from your email provider. For example, see Authenticating with Google services. Enter the mail update command with the property OAuth followed by an array containing the client_id, client_secret, and refresh_token properties and values from the token.

The TrueNAS SCALE web UI provides a streamlined experience for Gmail OAuth authentication. See Setting Up System Email for details.

Press Enter. The command returns an empty line.

Use config to view updated configuration and send to confirm configuration by sending a test email.

Update Properties

SMTP Properties

Property	Required	Description	Syntax Example
`fromemail`	Yes	The email address to use for sending emails. You must first configure the user account email in Credentials > Local Users.	`fromemail="test@test.com"`
`fromname`	No	The name to show in front of the sending email address, for example: TrueNAS.	`fromname=TrueNAS`
`outgoingserver`	Yes	Host name or IP address of SMTP server to use for sending emails.	`outgoingserver="smtp.mailserver.com"`
`port`	Yes	SMTP port number. Typically 25, 465 (secure SMTP), or 587 (submission).	`port=587`
`security`	No	Enter the security type to use. Options are `PLAIN` (no encryption), `SSL` (Implicit TLS), or `TLS` (STARTTLS). See email encryption for more information on types.	`security=TLS`
`smtp`	No	Set to true to enable SMTP AUTH using PLAIN SASL. Requires a valid user name and password.	`smtp=true`
`user`	Yes*	Required when `smtp` is true. The user name for the sending email account, typically the full email address.	`user="test@test.com"`
`pass`	Yes*	Required when `smtp` is true. The password for the sending email account.	`pass=passw0rt`

OAuth Properties

Property	Required	Description	Syntax Example
`client_id`	Yes	Enter the OAuth client id.	`“client_id”:"12345678910…apps.googleusercontent.com"`
`client_secret`	Yes	Enter the OAuth client secret.	`“client_secret”:"GOCSPX…eQ2_"`
`refresh_token`	Yes	Enter the OAuth refresh token.	`“refresh_token”:"1//04KmHpZzM…YUwfI"`

Usage

From the CLI prompt, enter:

system mail update property=value

Where property is one of the optional properties (see table) and value is the setting you want to apply. Press Enter.

Command Example -- SMTP

system mail update fromemail="test@test.com" fromname=TrueNAS outgoingserver="smtp.mailserver.com" port=587 security=TLS smtp=true user="test@test.com" pass=passw0rt

Command Example -- OAuth

system mail update oauth={“client_id”:"12345678910…apps.googleusercontent.com",“client_secret”:"GOCSPX…eQ2_",“refresh_token”:"1//04KmHpZzM…YUwfI"}

Mail

Mail Namespace

Mail Commands

Config Command

Description

Usage

Send Command

Description

Usage

Update Command

Description

Usage

Related Content

SCALE Tutorials

SCALE UI Reference

Have more Questions?