Email Notifications
Send email Notifications to alert on your scheduled searches.
If you’re a Cribl Search Admin, email Notifications make it easy for you (or designated other people) to receive alerts about operational issues that merit your attention, such as a scheduled search’s execution details.
An email Notification requires two things – a configured Notification and an email Notification target. Organizations on an Enterprise plan also have access to a preconfigured email Notification target.
Email Notifications do not provide an unsubscribe option. Recipients who do not want to receive particular email Notifications should contact their Cribl Search Admins.
Email Notifications are sent on a no-reply basis.
Email Notification Targets
You can send Notifications by email, using an SMTP server of your choice. Once you have configured the email Notification target, you can specify the recipients, and customize the subject line and message content. For details, see Configure Email Notifications.
To add an email Notification target in Cribl Search, do one of the following:
- Open a saved or scheduled search, then select Notifications. Toggle Send notifications on, if necessary, then configure the target.
- From the Cribl Search sidebar, select Settings, then Search, then Notification Targets, then Add Target.
If you have an Enterprise plan, you can use the preconfigured default Email Notification target.
General Settings
Target ID: Enter a unique name to identify this email Notification target.
Configuration
Address: Identify the SMTP server by its hostname or IP address.
Port: Set the SMTP port. Use port 587 for SMTP Secure (SMTPS). You can also use port 25. Use 465 when SSL/TLS
is enabled. You can also use port 2525 if your email service provider supports this port as a backup when other ports
are blocked by a network provider or a
firewall.
From: Identify the email address of the sender.
Encryption type: Specify the encryption type used to secure SMTP communication. Options include:
- STARTTLS: Select this option to start the connection as plaintext, then upgrade it to a TLS-encrypted one if the
server supports it. If the server doesn’t support it, the connection remains plaintext.
STARTTLS upgrades the connection to be encrypted but does not authenticate the server. Take additional steps to prevent man-in-the-middle attacks.
- Require STARTTLS: Select this option to require TLS. If the server doesn’t support a secure connection, the connection will be dropped.
- TLS (SMTPS): Select this option to use an encrypted connection from the start without requiring a subsequent connection upgrade.
- None: Select this option to use a plaintext connection.
Minimum TLS version: Optionally, select the minimum TLS version to use when connecting.
Maximum TLS version: Optionally, select the maximum TLS version to use when connecting.
Validate server certs: Toggle on to reject certificates that are not authorized by a CA in the CA certificate path or by another trusted CA (such as the system’s CA).
Authentication
Username: The authentication principal (if required).
Password: The authentication credential (if required).
Test Email Notification Targets
For arrival tests and log indicators, see Test the Email Notification Target.
Default Email Notification Target for Cribl.Cloud Enterprise Orgs
For Cribl.Cloud Enterprise orgs, a default email Notification target is available for Cribl Stream, Edge, and Search. You can use this target to route any email Notification to any valid email address.
This target appears in the Notifications > Target modal as system_email. You cannot modify or remove this
target.
The system_email Notification target is managed by Cribl. It will be disabled in the unlikely event of abuse. If this
target is disabled for a Workspace, a log entry will appear in the Notifications Service logs. Select Monitoring >
Logs > Notifications Service to view this log.
The
system_emailemail Notification target is available only for Organizations on an Enterprise plan. For details, see Pricing.
Send Domain for Cribl.Cloud Email Notifications
Every Cribl.Cloud Organization and Workspace has a unique address for its email Notification target. Messages sent using
this target will have a sender’s address in the form do-not-reply@<workspaceName>-<organizationId>.criblcloud.email. To ensure
delivery, recipients should add the criblcloud.email domain to their email allowlists.
Configure Email Notifications
To create an email Notification:
- Create a scheduled search.
- To schedule an existing search: Save it, then open its configuration modal from the Saved Searches tab.
- On that modal’s Schedule left tab, enable Run on schedule.
- On the Notifications left tab, enable Send notifications to unlock the options listed below.
| Field | Description |
|---|---|
| When… | Use these controls to define the condition that will send the Notification (see Notification Triggers). |
| Send Notification to | Select an existing email Notification target from the drop-down. Or select Create to define a new target (see Email Notification Targets). |
Once you’ve selected an email target, the following fields are available.
| Field | Description |
|---|---|
| To | Email address(es) of one or more primary recipients. |
| Cc field | Toggle this on to expose a field where you can enter additional recipients’ addresses. |
| Bcc field | Toggle this on to expose a field where you can enter blind-copy recipients’ addresses. |
| Include search results | For details about this option, see Include Search Results With Email Notifications. |
| Subject | The subject line of the email Notification. You can use variables here. |
| Message | The body of the email Notification. You can use variables here. |
Cribl Search does not limit the total number of recipients of an email Notification, but your email service might set a limit.
Email Notification Variables
Email variables are placeholders in the email template, which Cribl Search replaces with actual values when each email is sent. You can use these variables in the Notification’s Subject or Message (body) field. Insert a variable between pairs of double braces, in this format:
{{timestamp}}.
| Variable | Description |
|---|---|
resultSet | Array containing results of the search. |
savedQueryId | ID of the saved search that triggered the Notification. |
searchId | ID of the search job. |
searchResultsUrl | URL corresponding to the search job results. |
notificationId | ID of this Notification (autogenerated). |
timestamp | Date when this Notification was triggered. |
tenantId | ID of the Cribl Organization. |
Include Search Results With Email Notifications
You can send email notifications that include a subset of the search results that you’re being notified about. The results can be included as a table within the message body or attached as a CSV or JSON file.
To set this up:
- Set up an email Notification target.
- Open a scheduled search, and select Notifications.
- Configure the Notifications, using the email Notification target you’ve created.
- During the configuration, enable Include search results.
- Select one of the following:
- CSV, to include the results as a CSV attachment.
- JSON, to include the results as a JSON attachment.
- Inline table, to include the results within the email body. If you choose this options, see the considerations in the next section.
Inline Table Notifications
If you select the Inline table option, keep these details in mind:
The results table can accommodate up to 100 rows and 20 columns. If a table exceeds this size, Cribl Search will truncate it.
In the table, text will wrap. To make the results more legible, limit the number of fields sent (use the project operator) and the length of each field (use the trim function).
Security Risk
Embedding unverified or unsanitized search results into an email can pose unintended security risks. Cribl recommends reviewing or sanitizing the results prior to including them.
Troubleshoot Email Notifications
For troubleshooting, see Common Issues and Resolutions.