
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.
- Run the search.
- Select Save As > Alert.
- Provide a Title and other information about the alert.
- From the Add Actions menu, select Send email.
- 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
- To, CC, and BCC email recipients.
- Specify other alert actions.
See set up alert actions for more information. - 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:
For example, place the following token in the subject field of an email notification to reference the search ID of a search job.
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
:
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.
- Navigate to Settings > Server settings > Email settings.
- Select Mail Server Settings. Enter the following details.
- Mail host. The default is localhost.
- Email security.
- (Optional) Username.
- (Optional) Password.
- 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.
- Specify the following PDF Report Settings.
- Report Paper Size.
- Report Paper Orientation.
- 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.
PREVIOUS Set up alert actions |
NEXT Use a webhook alert action |
This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14
Feedback submitted, thanks!