# 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](favorite-filters.md#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](../../integrations/newsletters.md#integrations-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](../../data-processing/pipeline-steps/index/search-tagging.md#pipeline-steps-search-tagging) 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](../../api/squirro_client/sc-api-permissions.md#sc-api-permissions) 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](../../admin/configuration/config-files/emailsender-ini.md#admin-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](../../admin/configuration/config-files/digestmailer-ini.md#admin-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](../../data-processing/pipeline-steps/index/search-tagging.md#pipeline-steps-search-tagging) 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](../../widgets/built-in/search-bar.md#widgets-bi-search-bar) 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](../../widgets/built-in/favorites.md#widgets-bi-favorites) 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](../../widgets/built-in/actions.md#widgets-bi-actions) 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](query-syntax.md#search-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](#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](#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](../../admin/configuration/email-templates.md#admin-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](../../admin/configuration/config-files/filtering-ini.md#admin-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](../../admin/configuration/config-files/emailsender-ini.md#admin-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](../../admin/operations/services.md#admin-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](../../admin/configuration/config-files/digestmailer-ini.md#admin-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)](../../api/squirro_client/index.md#squirro-client) 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`. |