Alerting Manual

Email notification action

You can configure an alert to send an email notification to specified recipients when the alert triggers. You can send the email notification as a multipart MIME message that includes both HTML and text parts. You can also send the notification as plain text.

You configure the email notification action for an alert when you save the alert from the Search page. You can also configure email notification from the Alerts Page and directly from a search command.

Email notification contexts

There are several contexts from which you can send email notifications. The email options available differ, depending on the context.

• Alert actions
  Send email notifications as an alert action from a search. Specify the notification from the Search Page, a listing in the Alerts Page, or directly from the search command.

• Scheduled report
  Configure email notifications for a scheduled report either from a listing in the Reports Page or from a report.

• Scheduled PDF delivery of dashboards
  Configure PDF delivery either from a listing in the Dashboards Page or from a dashboard.

This topic covers alert actions from a search job. See Schedule reports and Generate Dashboard PDFs for information on the other contexts for email notification.

Configure email notification for alerts

You can configure email notifications when you save a search as an alert. You can also configure email notifications for when editing an alert's actions. The procedure is the same in both cases.

After running a search, save the search as an alert and configure email notification settings.

1. Run the search.
2. Select Save As > Alert.
3. Provide a Title and other information about the alert.
4. From the Add Actions menu, select Send email.
   
   
   
   
5. Specify the following:
   
   
   • To, CC, and BCC email recipients.
     Specify a comma-separated list of email recipients.
   • Priority
     Enforcement of priority depends on your email client.
   • Subject
   • Message
   • Include
     You can include the following items:
     
     Information about the search
       Link to the alert
       Search string
       Trigger condition
       Trigger time
     
     Information about search results
       Link to results
       Inline listing of results, as a table, raw events, or CSV file
       Results as a PDF attachment
       Results as a CSV attachment
   • Type
     Select HTML & Plain Text (multi-MIME message) or Plain Text
6. Specify other alert actions.
   See set up alert actions for more information.
7. Click Save.

Send email notification from a search command

You can send email notifications directly from the sendemail search command. For example:

index=main | head 5 | sendemail to=example@splunk.com server=mail.example.com subject="Here is an email notification" message="This is an example message" sendresults=true inline=true format=raw sendpdf=true

See the sendemail command listing in the Search Reference for details.

Send email to different recipients based on search results

This search example works with a token in the To email notification field to handle different notifications based on the result count. If there are more than 3500 results, a notification goes to recipient1. If there are fewer than 500 results, the notification goes to recipient2. If neither condition applies, then no notification is sent.

Here is the search.

"error" | stats count | eval recipient=case(count > 3500, "recipient1@domain.com", count >= 500, "recipient2@domain.com", 1==1, null()) | where isnotnull(recipient)

When the search is saved as an alert, configure the Send email alert action with the following token in the To recipient field.

$result.recipient$

Use tokens in email notifications

A token is a type of variable that represents data generated by a search job. Splunk Enterprise provides tokens that you can use to include information generated by a search in the fields of an email:

• To
• Cc
• Bcc
• Subject
• Message
• Footer

Access the value of a token with the following syntax:

$<token-name>$

For example, place the following token in the subject field of an email notification to reference the search ID of a search job.

Search results from $job.sid$

Tokens available for email notifications

This section lists common tokens you can use in email notifications. There are four categories of tokens that access data generated from a search. The context for using the tokens differ.

Category	Description	Context
Search metadata	Information about the search.	Alert actions from search Scheduled reports Scheduled PDF delivery of dashboards
Search results	Access results of a search	Alert actions from search Scheduled reports
Job information	Data specific to a search job	Alert actions from search Scheduled reports
Server information	Information about the Splunk Enterprise server	Alert actions from search Scheduled reports Scheduled PDF delivery of dashboards

In addition to the common tokens listed in this topic, the savedsearches.conf and alert_action.conf configuration files list attributes whose values are available from tokens. To access these attribute values, place the attribute between the '$' token delimiters. For example, to access the subject of an email notification, reference the following attribute listed in savedsearches.conf:

$action.email.subject$

Tokens that access search metadata

Common tokens that access information about a search. These tokens are available from the following contexts:

• Alert actions
• Scheduled reports
• Scheduled PDF delivery of dashboards

Here are some of the common tokens available.

Token	Description
$action.email.hostname$	Hostname of the email server.
$action.email.priority$	Priority of the search.
$app$	Name of the app containing the search.
$cron_schedule$	Cron schedule for the app.
$description$	Description of the search.
$name$	Name of the search.
$next_scheduled_time$	The next time the search runs.
$owner$	Owner of the search.
$results_link$	(Alert actions and scheduled reports only) Link to the search results.
$search$	The actual search.
$trigger_date$	(Alert actions only) The date that triggers the alert.
$trigger_time$	(Alert actions only) The scheduled time the alert runs.
$type$	Indicates if the search is from an alert, report, view, or the search command.
$alert.severity$	Severity level of the alert.
$alert.expires$	Time the alert expires.

Tokens available from results

From results, you use the result.<fieldname> token to access the first value of a specified field in search results. This token is available from the following contexts:

• Alert actions
• Scheduled reports

Token	Description
$result.fieldname$	Returns the first value for the specified field name from the first result in the search. The field name must be present in the search.

Tokens that access job information

Common tokens that access data specific to a search job, such as the search ID or messages generated by the search job. These tokens are available from the following contexts:

• Alert actions
• Scheduled reports

Token	Description
$job.earliestTime$	Initial time a search job starts.
$job.eventSearch$	Subset of the search that contains the part of the search before any transforming commands.
$job.latestTime$	Latest time recorded for the search job.
$job.messages$	List of error and debug messages generated by the search job.
$job.resultCount$	Number of results returned by the search job.
$job.runDuration$	Time, in seconds, that the search took to complete.
$job.sid$	Search ID.
$job.label$	Name given to the search job.

Tokens available from server

Common tokens that provide details available from your Splunk Enterprise server. They are available in the following contexts:

• Alert actions
• Scheduled reports
• Scheduled PDF delivery of dashboards

Token	Description
$server.build$	Build number of the Splunk Enterprise instance.
$server.serverName$	Server name hosting the Splunk Enterprise instance.
$server.version$	Version number of the Splunk Enterprise instance.

Deprecated email notification tokens

The following tokens from prior releases of Splunk Enterprise are deprecated.

Token	Description
$results.count$	(Deprecated) Use $job.resultCount$.
$results.url$	(Deprecated) Use $results_link$.
$results.file$	(Deprecated) No equivalent available.
$search_id$	(Deprecated) Use $job.id$.

Configure email notification settings

Before you send an email notification for an alert, configure email notification settings.

Prerequisites

• (Optional) Scheduling PDF delivery requires additional configuration of user roles. For more information, see User role configuration to schedule PDF delivery of dashboards.

• (Optional) To learn about using tokens in email configuration fields, see Use tokens in email notifications.
  
  

Here are the steps for configuring email notification settings in Splunk Web.

1. Navigate to Settings > Server settings > Email settings.
2. Select Mail Server Settings. Enter the following details.
   • Mail host. The default is localhost.
   • Email security.
   • (Optional) Username.
   • (Optional) Password.
3. Specify Email Format. Specify the following details.
   • Link hostname. The host name of the server used for creating URLs for outgoing results.
   • Send emails as. Enter an email address or a string specifying the sender.
   • Email footer. Footer text for each email. You can use tokens in the email footer.
4. Specify the following PDF Report Settings.
   • Report Paper Size.
   • Report Paper Orientation.
5. Click Save.

---

To learn about configuring email alert notifications using a configuration file, see alert_actions.conf.

User role configuration to schedule PDF delivery of dashboards

For a user to schedule PDF delivery of dashboards, the user role must contain the following capabilities:

• schedule_search
• admin_all_objects
  This capability is required only if the mail host requires log-in credentials.

See About defining roles with capabilities.