Custom SMTP email notifications

Splunk Cloud Platform lets administrators configure a custom SMTP server for alert and scheduled-report email notifications.

In Splunk Cloud Platform 10.6, administrators can configure a custom SMTP server for alert and scheduled-report email notifications.

Custom SMTP supports username and password authentication and OAuth 2.0 client credentials. Both methods support SSL or TLS encryption.

Administrators can switch between the default mail delivery service and a custom SMTP server at any time. Existing alerts and scheduled reports continue to work without changes.

Authentication methods

  • Username and password
  • OAuth 2.0 client credentials

Configure a custom SMTP server for email notifications

Configure outbound access and mail server settings for custom SMTP email notifications in Splunk Cloud Platform.

Gather the following information from your SMTP provider:

  • The SMTP server host name and port
  • The security method: SSL or TLS
  • Credentials: a username and password, or OAuth 2.0 client credentials
  • The sender address
  • The IP address ranges used by the SMTP server, in CIDR notation

You must have sc_admin permission to configure email settings. To configure outbound ports, you must have the ACS capabilities required for the outbound-port operation. See Define roles on the Splunk platform with capabilities.

Before enabling custom SMTP, configure outbound access to the SMTP server.

  1. Configure outbound access to the SMTP server using either the ACS API or the ACS CLI.

    Splunk Cloud Platform blocks the unencrypted SMTP port 25 for outbound connections. Use port 587 for TLS or port 465 for SSL.

    The following example shows how to configure an outbound port using the ACS API:

    JSON 
    curl -X POST 'https://<acs-server>/<stack>/adminconfig/v2/access/outbound-ports'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <token>'
--data '{
  "outboundPorts": [
    {
      "port": 587,
      "subnets": ["203.0.113.0/24"]
    }
  ],
  "reason": "Allow outbound connections to custom SMTP server"
}'

    Use the destination IP ranges published by your SMTP provider. Update the outbound-port configuration if the provider changes those ranges.

    After submitting the request, wait for the ACS configuration change to complete before continuing.

  2. In Splunk Web, go to Settings > Server settings > Email settings.
  3. Select the Custom Mail Server tab.
  4. Turn on custom SMTP.
  5. Enter the mail server settings for the selected authentication method.

    Username and password

    Field Description
    Mail server The SMTP server host name and port, for example smtp.gmail.com:587
    Security SSL or TLS
    Username The SMTP account username
    Password The SMTP account password
    From address The sender email address for outgoing alerts and scheduled reports

    OAuth 2.0

    Field Description
    Mail server The SMTP server host name and port
    Security SSL or TLS
    OAuth client ID The client ID issued by the mail provider
    OAuth client secret The client secret issued by the mail provider
    OAuth scope The permission scope for the token request
    OAuth URL The token endpoint URL for the OAuth provider
    From address The sender email address for outgoing alerts and scheduled reports

    Splunk Cloud Platform stores the password and OAuth client secret in encrypted form. Splunk Web does not display these values in full after you save the configuration.

  6. Add each domain that the custom SMTP server is authorized to use as a sender.
  7. Select Save.

    Confirm the mail server, port, security method, credentials, sender address, and sender domains before saving.

Alerts and scheduled reports use the new mail server immediately. You do not need to change existing alert or report definitions.

To switch back to the default mail delivery service, select the Default Configuration tab.

Splunk Cloud Platform does not automatically fall back to the default mail delivery service if the custom mail server fails.

Splunk Cloud Platform logs SMTP connection attempts and delivery results in splunkd.log. Configuration changes are recorded in the audit log. Splunk Cloud Platform does not monitor the custom mail server on your behalf. You are responsible for monitoring delivery through your SMTP infrastructure.

To view sendemail logs in Splunk Web, run the following search:

CODE 
index=_internal sourcetype=splunk_python *sendemail*

Troubleshoot custom SMTP email notifications

Use this reference to identify causes and solutions for custom SMTP email notification problems.

Symptom Likely cause
Connection timeout The SMTP server IP range or port is not included in the outbound-port allow list. Return to Step 1.
Connection refused The SMTP server rejected the connection. Confirm the port and security method with your SMTP provider.
Authentication failure The SMTP credentials, OAuth scope, or OAuth URL are incorrect.
Emails stop after a working configuration The SMTP provider changed its published IP ranges. Confirm the current ranges with the provider and update the outbound-port allow list.

If the issue persists, open a Splunk Support ticket. Do not include passwords, OAuth client secrets, or other credentials in the ticket.