Email notification action

Send an email notification to specified recipients when an alert triggers. Email notifications can include information from search results, the search job, and alert triggering. You can set up an email notification action from the Search page, the Alerts page, or directly in a search command.

In addition to alerting, there are other email notification contexts. For information on email notifications for reports, see Schedule reports in the Reporting Manual. For information on dashboard PDF email delivery, see Generate Dashboard PDFs in Dashboards and Visualizations.

---

Configure email notification for your Splunk instance

You must configure email notification settings for your Splunk implementation before you can design an email notification action.

If your email notification settings are already configured you can skip this task.

Prerequisite

PDF delivery requires additional user role configuration. See User role configuration for PDF delivery.

Steps for Splunk Cloud Platform

1. From the Search and Reporting app home page, select Settings > Server settings > Email settings.
2. Settings in the Mail Server Settings section are specified by your Splunk Cloud Platform implementation administrator and are not editable.
3. (Optional) Specify a comma-separated list of allowed Email Domains. Do not enter a return (new line) between items in this list. This setting restricts the email domains to which alert emails can be sent. Leave the field blank for no domain restriction.

   If you put values in Email Domains, your users cannot set mail servers for individual saved searches with the action.email.mailserver setting on the Advanced Edit page. The Splunk software will use the Mail host on the Email settings page instead. Users get to Advanced Edit by selecting Edit > Advanced Edit for a search on the Searches, Reports, and Alerts page in Settings.

4. Specify Email Format settings.
   

   Email Format Setting	Definition
   Link hostname	This is the hostname for outgoing results URLs. This value is set by your Splunk Cloud Platform implementation administrator and isn't editable.
   Send email as	This value is set by your Splunk Cloud Platform implementation and cannot be changed. Entering a value in this field has no effect.
   Email footer	Footer for all emails. Use text and/or tokens.

5. Click Save.

Steps for Splunk Enterprise

1. From the Search and Reporting app home page, select Settings > Server settings > Email settings.
2. Specify the following Mail Server Settings values.
   

   Setting	Definition
   Mail host	The default value is localhost.
   Email security	Select one of the available options.
   Username	(Optional) Required for SMTP server authentication.
   Password	(Optional) Required for SMTP server authentication. If you enter a password, you must retype it in Confirm Password.

3. (Optional) Specify a comma-separated list of allowed Email Domains. This setting restricts the email domains to which alert emails can be sent. Leave the field blank for no domain restriction.

   If you put values in Email Domains, your users cannot set mail servers for individual saved searches with the action.email.mailserver setting on the Advanced Edit page. The Splunk software will use the Mail host on the Email settings page instead. Users get to the Advanced Edit page by selecting Edit > Advanced Edit for a search on the Searches, Reports, and Alerts page in Settings.

4. Specify Email Format settings.
   

   Email Format Setting	Definition
   Link hostname	The hostname for outgoing results URLs. Enclose IPv6 addresses in square brackets. Example: [2001:db8:0:1]
   Send emails as	(Optional) Specify a sender identification, used in the From email header field. Use an email address or a string. Strings cannot include spaces. Strings are concatenated with @<hostname>, using the hostname specified in alert_actions.conffor the machine sending the email notification or @localhost if no hostname is specified. Defaults to splunk@<hostname> or splunk@localhost if no hostname is specified.
   Email footer	Footer for all emails. Use text and/or tokens.

5. Click Save.

Define an email notification action for an alert or scheduled report

Prerequisites

• Configure the email notification settings in the Email Settings page. See Configure email notification for your Splunk instance.
  • Optionally restrict email notifications to a specific set of email domains. If email domains are listed in the Allowed Domains field, email notifications can be sent only to recipients with those domains.
  • Define email footers and PDF formats.
• Specific roles and capabilities are required for some email notification features. For more information on roles and capabilities, see About defining roles with capabilities in Securing the Splunk Platform.
  • To send an email notification within a search to a mail server that requires SMTP authentication, you must have the admin role.
  • To send an email notification within a search to a mail server that does not require SMTP authentication, your role must have the list_settings capability. By default, only the admin, splunk-system-role, and can_delete roles have the list_settings capability.
  • If you want to allow users not belonging to any of these roles to send email notifications using the sendemail command in their search, you must assign them the list_settings and schedule_search capabilities.
• PDF delivery requires additional user role configuration. See User role configuration for PDF delivery.
• See Use tokens in email notifications for more information about token usage.

Steps

1. You can configure the email notification action when you create a new alert, edit the actions for an existing alert, or define or edit the schedule for a report. Follow one of the options below.
   

   Option	Steps
   Create a new alert	From the Search page in the Search and Reporting app, select Save As > Alert. Enter alert details and configure triggering and throttling as needed.
   Edit an existing alert	From the Alerts page in the Search and Reporting app, select Edit > Edit actions for an existing alert.
   Define or edit the schedule of a report	From the Reports page in the Search and Reporting app, select Edit > Edit schedule for a report.

2. Click Add Actions and select Send email.
3. Type a comma-separated list of To email recipients.
4. (Optional) Click Show CC and BCC to type comma-separated lists of CC, and BCC email recipients.
5. (Optional) Set the email Priority. Enforcement of email priority depends on your email client.
6. (Optional) Provide the email Subject and Message.
   You can optionally use tokens in the subject and message text.
7. (Optional) Select one or more of the following options to include material in the email.
   

   Option	Adds to email
   Link to Alert or Link to Report	A link to the alert or scheduled report that the email is associated with.
   Link to Results	A link to the results for the related search job.
   Search String	The search string used by the alert or scheduled report.
   Inline...	Displays the results as an inline table, a list of raw events, or in CSV file format.
   Trigger condition (for alerts only)	The condition that triggered the alert.
   Trigger time (for alerts only)	The alert timestamp.
   Attach CSV	A file attachment that provides the results in CSV format.
   Attach PDF	A file attachment that provides the results in PDF format.
   Allow Empty Attachment	Allow the Splunk platform to include a CSV or PDF attachment with the email even when the associated search has not returned results.

8. (Optional) Change the email Type to Plain Text.
   Type is set to HTML & Plain Text by default.
9. Click Save.

If you have Splunk Enterprise, you can configure email alert settings by editing the alert_actions.conf configuration file. For details, see alert_actions.conf.

---

Use a search command to send an email notification

You can send email notifications directly from the sendemail search command. Here is an example.

index=main | head 5 | sendemail to=<email address> server=<server info> subject="Here is an email notification" message="This is an example message" sendresults=true inline=true format=raw sendpdf=true

If you are sending an email notification to a server that requires SMTP authentication, you must have the admin role assigned.

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

---

Example - Send email to different recipients based on search results

This example shows you how you can use the $result.recipient$ token to make the Splunk software send notification emails to different recipients depending on the number of results returned by the search.

The $result.recipient$ token works in conjunction with an eval statement in the search. This eval statement sets the conditions under which emails are sent to specific addresses.

Here is an example of a search that is designed to work with $result.recipient$.

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

After this search is saved as an alert or scheduled report, you design an email notification action for it where you type $result.recipient$ in the To field.

When the alert is triggered or the scheduled report runs on its schedule, a notification is sent recipient1 if there are more than 3500 results. If there are 500 or fewer results, a notification is sent to recipient2. If neither condition applies, no notification is sent.

The email addresses represented by tokens are validated only at the time of the search.

See Use tokens in email notifications for more information about token usage.

---

User role configuration for PDF delivery

The following capabilities are required for PDF delivery scheduling.

• schedule_search
• admin_all_objects. This capability is required if the mail host requires login credentials.
• list_settings

See About defining roles with capabilities in the Security Manual for more information.