Email Alerts

An email alert notifies you by email when new items matching a saved query arrive in your project. Alerts are built on top of favorites, so any query you can save as a favorite can also send you an email. For more information about favorites, see the Favorite Filters page.

Use an alert to track a topic without returning to the platform to run the same search again, for example a competitor name, a product defect, or a regulatory keyword.

Do not confuse an alert with a newsletter, which sends a scheduled digest of project content to the members of a project rather than notifying individuals about query matches. For more information, see the Newsletters page.

How Alerts Work

The platform evaluates alert queries as it processes incoming items, not by running the saved searches again on a timer. That approach has three consequences:

• An alert only reports items whose creation date is later than the alert creation, so it never notifies you about content that predates it. To review those earlier matches, run the query in the search bar.

• Items must pass through a pipeline workflow that contains the Search Tagging and Alerting step. If that step is missing, no alert in the project sends any email. For more information, see the Search Tagging and Alerting page.

• Matching runs asynchronously, so expect a short delay between an item arriving and its alert email going out.

Prerequisites

Any project member can create an alert. Every project role, including Reader, holds the savedsearches.* permission that alerts rely on, so you need no elevated rights. For more information, see the Permissions Reference page.

Administrator Setup

The SMTP and frontend_tld settings are server settings, configured once, and already done for you in Squirro Self-Service instances. Adding the pipeline step is your responsibility on every instance, Squirro Self-Service included, because it applies per workflow.

1. Configure the SMTP settings so the server can send email. Newsletters use the same settings, so this step is already done if newsletters work on this server. For more information, see the emailsender.ini page.

2. Set the frontend_tld option to the address at which end users reach your Squirro instance, so the links inside alert emails resolve correctly. For more information, see the digestmailer.ini page.

3. Add the Search Tagging and Alerting step to every pipeline workflow whose items should trigger alerts, placing it after the Indexing step. This is done once per workflow, independent of how many alerts exist. For more information, see the Search Tagging and Alerting page.

Dashboard Setup

The alert form opens from any of the following controls, so a dashboard needs at least one of them:

• Search Bar widget

  Turn on the Show Favorite button option to display the Add to favorites icon next to the search field. The icon appears once you enter a query, so an empty search bar does not show it. For more information, see the Search Bar Widget page.

• Favorite Filters widget

  Add this widget to give access to the favorites manager, where you edit existing alerts. For more information, see the Favorites Widget page.

• Actions widget

  Turn on the Save Filter option to display a button that saves the current query. For more information, see the Actions Widget page.

Global Search always displays the Add to favorites icon, so it needs no configuration.

Creating an Alert

1. Run the query you want alerts for. Fine-tune it until the results list contains what you expect. For more information about query syntax, see the Query Syntax page.

2. Select the Add to favorites icon, or the Save Filter button of the Actions widget. The Favorite Filter dialog opens.

3. Enter a recognizable name in the Name field.

4. Turn on the Email Alert toggle.

5. In Email Recipients, enter the addresses to notify, separated by commas. The field defaults to your own address.

6. Select an Alert Frequency. The Alert Frequency section below explains each option.

7. If you selected Daily, set the Time and Timezone for the daily email. The Time field takes the hour of the day as a number from 0 to 23, and defaults to 08. The Timezone field defaults to UTC. These two fields only appear for the daily frequency.

8. Select Save Favorite.

The alert is active from that moment and applies to items arriving afterwards.

Note

An alert you created in the user interface belongs to you only. Other members of the project do not see it, and only the recipients you list receive its emails. To create an alert shared by a whole project, use the API, as described in the Project-Wide Alerts and Webhooks section below.

Alert Frequency

The frequency sets the shortest interval at which an alert sends email. It does not change how often matching runs. An alert never sends email when there is nothing new to report.

Frequency	Behavior
Hourly	Sends an email as soon as an item matches, then waits at least one hour before sending again.
Daily	Sends one email a day, at the Time and Timezone you set. The alert collects matches occurring between two sends into the next email.
Weekly	Sends an email as soon as an item matches, then waits at least seven days before sending again.
Monthly	Sends an email as soon as an item matches, then waits at least 30 days before sending again.

The hourly, weekly, and monthly options behave the same way and differ only in the length of the waiting period. The first match sends an email immediately, so a new alert usually delivers its first email within minutes rather than after a full period. None of those three options is tied to a day or a clock time. The waiting period runs from the first match, so a weekly alert whose first match arrives on a Tuesday afternoon keeps sending on Tuesday afternoons for as long as matches keep arriving. If a full period passes with no match, the alert resets, and the next match notifies you straight away rather than waiting for the end of a period.

The daily option is the only one tied to a clock time. Choose it when a predictable delivery time matters more than speed.

Managing Alerts

Open the favorites manager using the pencil icon of the Favorite Filters widget. From there you can:

• Edit the name and query of an alert using the pencil icon next to its entry.

• Change the recipients, frequency, or delivery time.

• Turn off the Email Alert toggle. The favorite is kept and remains available as a saved query, but the alert sends no further email.

• Delete the favorite using the bin icon, which also removes its alert.

Customizing the Alert Email

Alert emails use the Favorite Filters Alert template, which you can configure per tenant under Server → Emails. The template controls the layout, the subject, and which item fields appear in the email. For the list of available template variables, see the Email Templates page.

Alert Behavior

• Repeated items

  An alert does not report the same item twice. Each alert keeps track of the items it has already reported and skips them on subsequent sends. Administrators can change how many items each alert remembers with the email_items_history option. For more information, see the filtering.ini page.

• Recipients

  You can list any number of addresses, separated by commas. Recipients do not need a Squirro account to receive the email, but the links inside it require an account and the corresponding project permissions.

• Query changes

  Editing the query of an existing alert applies to items arriving afterwards. It does not re-evaluate items that arrived under the previous query.

• Back-dated items

  An alert selects items by their creation date rather than by when they entered the project. Items that keep an older original creation date therefore do not appear in alert emails, even though they entered the project after you created the alert. Keep this in mind when importing historical archives.

• Time-based queries

  A relative date filter in the saved query, such as a restriction to the last 24 hours, applies when the alert query runs. Combining a relative date filter with a long frequency can produce empty or incomplete emails, so keep alert queries focused on content rather than on time.

Troubleshooting

No Alert in the Project Sends Email

Check the administrator prerequisites in the following order:

1. Confirm that the SMTP settings are configured. For more information, see the emailsender.ini page.

2. Confirm that the Search Tagging and Alerting step is present in the pipeline workflow used by the data sources feeding the project. This is the most common cause, because an alert saves successfully whether or not the step exists.

3. Confirm that the sqfilteringd, sqdigestmailerd, and sqemailsenderd services are running. For more information, see the Services page.

One Alert Sends No Email

• Confirm that new items matching the query are arriving. Run the query in the search bar and check whether recent items appear. An alert never reports items whose creation date is earlier than the alert itself.

• Confirm that the alert is turned on. Open it in the favorites manager and check the Email Alert toggle.

• Check the Email Recipients field for a typing error in an address.

Fewer Emails Arrive Than Expected

The frequency is a minimum interval rather than a schedule, and an alert never repeats an item it has already reported. An alert that matches continuously sends at most one email per period, and an alert whose matches are all repeats sends no email at all.

Links in the Email Do Not Work

The frontend_tld option points to the wrong address. For more information, see the digestmailer.ini page.

Project-Wide Alerts and Webhooks

The user interface creates alerts that belong to a single user and send email. The saved search API covers two cases the user interface does not:

• Alerts shared by a project

  Creating a saved search with the project scope makes one alert serve the whole project, rather than asking every member to create their own.

• Webhook delivery

  A saved search can call a URL instead of sending email, which allows a match to open a ticket or notify another system.

Create both by passing an action to the new_savedsearch method. For more information, see the SquirroClient (Python SDK) page.

The following options are available on a mail action:

Option	Usage
email	List of recipient addresses. This option is required. An action without it fails and sends no email.
cool_off_period_seconds	Shortest interval between two emails, in seconds. Defaults to 3600. The Alert Frequency setting writes this value.
schedule	Object with an hour key and an optional timezone key. Sends one email a day at that hour and ignores cool_off_period_seconds.
send_duplicates	When set to true, the alert includes items it has already reported. Defaults to false.