Configure SMTP settings
In this guide, you learn how to configure SMTP (Simple Mail Transfer Protocol) settings to generate email alerts in Azure Managed Grafana. Notifications alert users when some given scenarios occur on a Grafana dashboard.
SMTP settings can be enabled on an existing Azure Managed Grafana instance via the Azure portal and the Azure CLI. Enabling SMTP settings while creating a new instance is currently not supported.
Prerequisites
To follow the steps in this guide, you must have:
- An Azure account with an active subscription. Create an account for trial.
- An Azure Managed Grafana instance in the Standard plan. If you don't have one yet, create a new instance.
- An SMTP server. If you don't have one yet, you might want to consider using Twilio SendGrid's email API for Azure.
Enable and configure SMTP settings
Follow these steps to activate SMTP settings, enable email notifications and configure an email contact point in Azure Managed Grafana.
In the Azure portal, open your Grafana instance and under Settings, select Configuration.
Select the Email Settings tab.
Toggle SMTP Settings on, so that Enable is displayed.
SMTP settings appear. Fill out the form with the following configuration:
Parameter Example Description Host test.sendgrid.net:587 Enter the SMTP server hostname with port. User admin Enter the name of the user of the SMTP authentication. Password password Enter password of the SMTP authentication. If the password contains "#" or ";" wrap it within triple quotes. From Address user@domain.com Enter the email address used when sending out emails. From Name Azure Managed Grafana Notification Enter the name used when sending out emails. Default is "Azure Managed Grafana Notification" if parameter isn't given or empty. Skip Verify Disable This setting controls whether a client verifies the server's certificate chain and host name. If Skip Verify is Enable, client accepts any certificate presented by the server and any host name in that certificate. In this mode, TLS is susceptible to machine-in-the-middle attacks unless custom verification is used. Default is Disable (toggled off). More information. StartTLS Policy OpportunisticStartTLS There are three options. More information. - OpportunisticStartTLS means that SMTP transactions are encrypted if STARTTLS is supported by the SMTP server. Otherwise, messages are sent in the clear. It's the default setting.
- MandatoryStartTLS means that SMTP transactions must be encrypted. SMTP transactions are aborted unless STARTTLS is supported by the SMTP server.
- NoStartTLS means encryption is disabled and messages are sent in the clear.
Select Save to save the SMTP settings. Updating might take a couple of minutes.
Once the process is complete, the message "Updating the selections. Update successful" is displayed in the Azure Notifications. In the Overview page, the provisioning state of the instance turns to Updating, and then Succeeded once the update is complete.
Tip
Here are some tips for properly configuring SMTP:
- When using a business email account such as Office 365, you may need to contact your email administrator to enable SMTP AUTH (for example, enable-smtp-auth-for-specific-mailboxes). You should be able to create an app password afterwards and use it as the SMTP password setting.
- When using a personal email account such as Outlook or Gmail, you should create an app password and use it as the SMTP password setting. Note that your account won't work for email notification if it's configured with multi-factor authentication.
- It's recommended that you verify the SMTP configurations to be working as expected before applying them to your Managed Grafana workspace. For example, you can use an open source tool such as swaks (Swiss Army Knife for SMTP) to send a test email using the SMTP configurations by running the following command in a terminal window:
# fill in all the empty values for the following parameters host="" # SMTP host name with port separated by a ":", e.g. smtp.office365.com:587 user="" # email address, e.g. team1@contoso.com password="" # password fromAddress="" # source email address (usually the same as user above), e.g. team1@contoso.com toAddress="" # destination email address, e.g. team2@contoso.com ehlo="" # grafana endpoint, e.g. team1-ftbghja6ekeybng8.wcus.grafana.azure.com header="Subject:Test" body="Testing!" # test SMTP connection by sending an email swaks --auth -tls \ --server $host \ --auth-user $user \ --auth-password $password \ --from $fromAddress \ --to $toAddress \ --ehlo $ehlo \ --header $header \ --body $body
Configure Grafana contact points and send a test email
Configuring Grafana contact points is done in the Grafana portal:
In your Azure Managed Grafana workspace, in Overview, select the Endpoint URL.
Go to Alerting > Contact points.
Select New contact point or Edit contact point to update an existing contact point.
Add or update the Name, and Contact point type.
Enter a destination email under Addresses, and select Test.
Select Send test notification to send the notification with the predefined test message or select Custom to first edit the message.
A notification "Test alert sent" is displayed, meaning that the email setup is successfully configured. The test email has been sent to the provided email address. If there's a misconfiguration, an error message is shown instead.
Disable SMTP settings
To disable SMTP settings, follow these steps.
- In the Azure portal, go to Configuration > Email Settings and toggle SMTP Settings off, so that Disable is displayed.
- Select Save to validate and start updating the Azure Managed Grafana instance.
Note
When a users disables SMTP settings, all SMTP credentials are removed from the backend. Azure Managed Grafana will not persist SMTP credentials when disabled.
Grafana alerting error messages
Within the Grafana portal, you can find a list of all Grafana alerting error messages that occurred in Alerting > Notifications.
The following are some common error messages you might encounter:
- "Authentication failed: The provided authorization grant is invalid, expired, or revoked". Grafana couldn't connect to the SMTP server. Check if the password entered in the SMTP settings in the Azure portal is correct.
- "Failed to sent test alert: SMTP not configured". SMTP is disabled. Open the Azure Managed Grafana instance in the Azure portal and enable SMTP settings.
Next steps
In this how-to guide, you learned how to configure Grafana SMTP settings. To learn how to create reports and email them to recipients, see Create dashboards.