From 37eeb82b5c7d5f4a0944973f966fa7a5f18ab2ff Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Wed, 8 Oct 2025 05:12:10 +0200 Subject: [PATCH] [release-12.2.1] docs(alerting): Email contact point enhancements (#112121) docs(alerting): Email contact point enhancements (#111944) * docs(alerting): Email contact point enhancements * minor content tweaks (cherry picked from commit 5438df01a1a95a345bc8dab85980f653529b539c) --- .../integrations/configure-email.md | 115 ++++++++---------- 1 file changed, 53 insertions(+), 62 deletions(-) diff --git a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md index b7226283d1b..6e5884e74c0 100644 --- a/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md +++ b/docs/sources/alerting/configure-notifications/manage-contact-points/integrations/configure-email.md @@ -12,9 +12,14 @@ labels: - enterprise - oss menuTitle: Email -title: Configure email for Alerting +title: Configure email for alert notifications weight: 110 refs: + configure-contact-points: + - pattern: /docs/grafana/ + destination: /docs/grafana//alerting/configure-notifications/manage-contact-points/ + - pattern: /docs/grafana-cloud/ + destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/manage-contact-points/ notification-templates: - pattern: /docs/grafana/ destination: /docs/grafana//alerting/configure-notifications/template-notifications/ @@ -22,84 +27,70 @@ refs: destination: /docs/grafana-cloud/alerting-and-irm/alerting/configure-notifications/template-notifications/ --- -# Configure email for Alerting +# Configure email for alert notifications -Use the Grafana Alerting - email integration to send email notifications when your alerts are firing. An email is sent when an alert fires and when an alert gets resolved. +Use the email integration to send alert notifications to one or more addresses. -Note that you can customize the `subject` and `message` of the email using [notification templates](ref:notification-templates). However, you cannot add HTML and CSS to email notifications for visual changes. +You can customize the [subject and main section of the email body](#optional-settings-using-templates). By default, the subject and body are generated from the alert data included in the notification. ## Before you begin +In Grafana OSS, you must configure SMTP settings before you can enable email notifications. + {{}} -This section is for Grafana OSS only. For Grafana Cloud, SMTP configuration is not required. +In Grafana Cloud, SMTP configuration is not required. {{}} -For Grafana OSS, you enable email notifications by first configuring [SMTP settings](https://grafana.com/docs/grafana/next/setup-grafana/configure-grafana/#smtp) in the Grafana configuration settings. +1. Open the [configuration file](/docs/grafana//setup-grafana/configure-grafana/). The file is typically named `grafana.ini` or `custom.ini` and located in the `conf` directory of your Grafana installation. -### SMTP configuration +1. Configure the [SMTP settings](/docs/grafana//setup-grafana/configure-grafana/#smtp) for your email server in the `[smtp]` section. -1. Access the configuration file. +1. Save your changes and restart Grafana. - Locate the Grafana configuration file. This file is typically named `grafana.ini` or `custom.ini` and is located in the `conf` directory within the Grafana installation directory. +1. Test email notifications by creating a contact point. -1. Open the configuration file: +## Configure Email for a contact point - Open the configuration file using a text editor. - -1. Locate SMTP settings section. - - Search for the [SMTP settings section](https://grafana.com/docs/grafana/next/setup-grafana/configure-grafana/#smtp) in the configuration file. It starts with `[smtp]`. - -1. Configure SMTP settings. - - Within the `[smtp]` settings section, specify the following parameters: - - `enabled = true`: Enables SMTP. - - `host`: The hostname or IP address of your SMTP server, and the port number of your SMTP server (commonly 25, 465, or 587). Default is `localhost:25`. - - `user`: Your SMTP username (if authentication is required). - - `password`: Your SMTP password (if authentication is required). - - `from_address`: The email address from which Grafana notifications will be sent. - - `from_name`: The name associated with the from_address. - - `skip_verify = true`: Skip SSL/TLS certificate verification (useful for testing, but not recommended for production). - -1. Save and close the configuration file. - - After configuring the SMTP settings, save the changes to the configuration file and close the text editor. - -1. Restart Grafana. - - Restart the Grafana service to apply the changes made to the configuration file. The method for restarting Grafana depends on your operating system and how Grafana was installed (e.g., `systemctl restart grafana-server` for systems using systemd). - -1. Test email notifications. - - After restarting Grafana, test the email notification functionality by creating an email contact point. - -## Procedure - -To set up email integration, complete the following steps. +To create a contact point with a email integration, complete the following steps. 1. Navigate to **Alerts & IRM** -> **Alerting** -> **Contact points**. -1. Click **+ Add contact point**. -1. Enter a contact point name. -1. From the Integration list, select **Email**. -1. Enter the email addresses you want to send notifications to. - - E-mail addresses are case sensitive. Ensure that the e-mail address entered is correct. - -1. Click **Test** to check that your integration works. - - ** For Grafana Alertmanager only.** - +1. Click **+ Create contact point**. +1. Enter a name for the contact point. +1. From the **Integration** list, select **Email**. +1. Set up the required [settings](#email-settings) for your Email configuration. 1. Click **Save contact point**. -## Next steps +For more details on contact points, including how to test them and enable notifications, refer to [Configure contact points](ref:configure-contact-points). -The email contact point is ready to receive alert notifications. +## Email settings -To add this contact point to your alert, complete the following steps. +| Option | Description | +| --------- | ------------------------------------------------------------------------------------------ | +| Addresses | The list of email addresses to send the notifications. Email addresses are case sensitive. | -1. In Grafana, navigate to **Alerting** > **Alert rules**. -1. Edit or create a new alert rule. -1. Scroll down to the **Configure labels and notifications** section. -1. Under Notifications click **Select contact point**. -1. From the drop-down menu, select the previously created contact point. -1. **Click Save rule and exit**. +#### Optional settings + +| Option | Description | +| ------------ | ------------------------------------------------------------------------- | +| Single email | Send a single email to all email addresses rather than individual emails. | + +#### Optional settings using templates + +{{}} +You can customize the email subject and main section of the email body, but you can't edit HTML or CSS for visual changes. + +In Grafana OSS and Enterprise, you can edit the full email template. However, this is not officially supported because it's an internal API that may change without prior notice. +{{}} + +| Option | Description | +| ------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| Subject | Sets the email subject, replacing the default template. Supports [notification templates](ref:notification-templates). | +| Message | Sets the main section of the email body, replacing the default template. Supports [notification templates](ref:notification-templates). | + +{{< figure src="/media/docs/alerting/custom-email-message5.png" caption="Email notification with custom message." max-width="750px" >}} + +#### Optional notification settings + +| Option | Description | +| ------------------------ | ------------------------------------------------------------------- | +| Disable resolved message | Enable this option to prevent notifications when an alert resolves. |