sonar-sendmail

Sends input data as an email using the system SMTP configuration and Sonar's common mail template. Because the command applies the default mail body registered in the notification templates, the email uses the same layout and logo as the other mail notifications that Sonar sends automatically, and you can choose the template language that matches the recipient.

Command properties

Syntax

Options

html=BOOL

When set to t, sends the content of the message field in HTML format (default: f). In HTML format, disallowed tags and attributes are removed from the body before it is inserted into the template. When set to f, HTML special characters in the body are escaped and line breaks and spaces are preserved before the body is inserted into the template.

locale={en|ko|ja|zh}

Mail template language (default: the locale of the user who runs the query)

• en: English
• ko: Korean
• ja: Japanese
• zh: Chinese

Input fields

Output fields

Error codes

Parse errors

Runtime errors

N/A

Description

The sonar-sendmail command sends one email per input record. It reads the to, subject, and message fields of the input record to build the recipient, subject, and body, and adds CC and BCC recipients when the cc and bcc fields are present. The input record passes through to the next command regardless of whether delivery succeeds.

The mail body is inserted into the default mail body template of the notification templates. In the template, ${SUBJECT} is replaced with the email subject, ${DATE} with the delivery time in yyyy-MM-dd HH:mm format, and ${BODY} with the content of the message field. If no template is registered, the built-in default template is used, and if the template is empty, only the body is sent. When the template references a logo image, the mail logo registered in the system is attached as well.

The template is retrieved in the language specified by the locale option. If you omit the locale option, the command uses the locale of the user who runs the query, and falls back to the English template when that locale is not en, ko, ja, or zh. If no template exists for the specified language, the English template is used instead. You can register templates per language with the Set Notification Template API.

In the following cases, the command does not send the email and records the reason in the _sendmail_fail field:

• The to, subject, or message field is missing: missing field: FIELD_NAME
• An email address has no domain part (@): address has no domain part: ADDRESS
• The system SMTP configuration is missing: smtp is not configured
• The mail delivery queue is full: queue full

Because the command requires the system SMTP configuration, you must configure the SMTP server in the system settings of the web console first.

The input fields and the failure handling are the same as the sendmail command, but the body is composed differently. sendmail uses a fixed built-in layout and logo, provides no language selection, and fails at query execution time when the system SMTP configuration is missing. sonar-sendmail uses the layout registered in the notification templates and the mail logo registered in the system, and lets you select the language with the locale option.

Examples

To prepare the WEB_APACHE_SAMPLE table used in these examples, see Preparing sample data.

1. Sending web access statistics by email

   table WEB_APACHE_SAMPLE
   | stats count as total, count(status >= 400) as errors by method
   | eval to = "admin@example.com"
   | eval subject = "Web access summary"
   | eval message = concat(method, " requests: ", string(total), ", errors: ", string(errors))
   | sonar-sendmail
   

   Aggregates the total number of requests and error responses per HTTP method and sends each row as an email. The body is inserted into the common mail template before delivery.

2. Sending an error response summary in HTML format

   table WEB_APACHE_SAMPLE
   | search status >= 400
   | stats count as cnt by status, uri
   | sort -cnt
   | limit 10
   | eval to = "admin@example.com"
   | eval subject = "Top error URLs"
   | eval message = concat("<b>", string(status), "</b> ", uri, " (", string(cnt), ")")
   | sonar-sendmail html=t
   

   Sends the status codes and URIs of the top 10 error responses in HTML format. The HTML in the body is sanitized before it is inserted into the template.

3. Sending with CC and BCC recipients using the Korean template

   table WEB_APACHE_SAMPLE
   | stats count as total
   | eval to = "admin@example.com"
   | eval cc = "manager@example.com"
   | eval bcc = "audit@example.com"
   | eval subject = "Daily web access summary"
   | eval message = concat("Total requests: ", string(total))
   | sonar-sendmail locale=ko
   

   Uses the Korean mail template and delivers the email to the CC and BCC recipients as well.

Change history

The sonar-sendmail command is available in the Sonar 4.0 series starting with 4.0.2609.0.