Using the Event Notifications SMTP interface

Event Notifications supports SMTP, the most common email protocol on the internet. You can send email by using a variety of clients, software, or programming languages that support SMTP by connecting to the Event Notifications SMTP interface. This topic explains how to set up an SMTP configuration, obtain user credentials, and set up a CBR rule to access the SMTP server.

Creating an SMTP configuration

  1. Create an Event Notifications instance. To learn the process of creating an instance, see Getting Started.

  2. In your Event Notifications instance, click Email > SMTP Configurations.

  3. Click Create.

  4. Enter a Name, an optional Description, and the Domain name in the Create a new SMTP configuration dialog.

  5. Click Create.

Domain name verification

After creating an SMTP configuration in an Event Notifications instance, you need to perform three types of verifications to get the required parameters to send email through the SMTP interface. These verifications are located under the Verify tab, accessible by clicking the Options menu.

  1. Create Sender Policy Framework (SPF), which is used to authenticate the sender of an email. SPF specifies the mail servers that are allowed to send email for your domain.

    • Ensure that the domain already exists as an A record in the DNS records.
    • Open your DNS hosting provider for the domain name configured
    • Create a new TXT record with your domain name registerer with the name and value provided in the configure screen for SPF

  2. Create DomainKeys Identified Mail (DKIM), which allows an organization to take responsibility for transmitting a message by signing it. DKIM allows the receiver to check the email that claimed to have come from a specific domain, is authorized by the owner of that domain.

    • Open your DNS hosting provider for the domain name configured
    • Create a new TXT record with your domain name registerer with the name and value provided in the configure screen for DKIM

  3. For enhanced security, we perform manual verification of SMTP interface requirements. Complete the questionnaire for the common questions (Q1–Q8) described in Email sender verification questionnaire. The additional questions for the opt-out request do not apply here.

    After completing the questionnaire, request enablement of the SMTP interface verification through a support ticket:

    1. From the IBM Cloud console menu bar, click the Help icon > Support center.
    2. From the Contact support section, click Create a case.
    3. Under Category, set Topic to Event Notifications and Subtopic to Others.
    4. Under Subject, enter Requesting for the Authorization to Enable SMTP Interface for Event Notifications.
    5. In the Description section, provide the Event Notifications instance id, region, and a DKIM Name in the format {{uuid}}._domainkey.{{domain}}.
    6. Include your responses to the questionnaire.
    7. Add Attachments if you want to provide supporting evidence.
    8. Add required email addresses in the Watchlist section. For more information about other options, see Creating a support case.

Some of the common verification issues could be:

  1. Ensure that the domain name is spelled correctly.
  2. Verify that the DNS record for the domain is updated correctly, including SPF/DKIM values.
  3. DNS propagation may take up to 72 hours to be updated across the internet.

Event Notifications performs periodic checks on the SPF and DKIM TXT records of the configured domain. To ensure uninterrupted email delivery, keep the records in the DNS even after verifying them. If the SPF or DKIM fails a periodic check, email sending will be suspended.

Requesting a recipient limit increase

Each send request supports up to 50 email recipients. To reach more recipients, split them into batches across multiple requests. If batching does not meet your use case requirements, you can request a higher limit. For more information, see Requesting a recipient limit increase for email destinations.

Enabling context-based restrictions to access the SMTP interface

The legacy IP-based allowlisting for the SMTP interface is now deprecated. It is mandatory to migrate to context-based restrictions when connecting to the SMTP interface. Current allowlisted IPs will remain functional for the next six months, allowing time for this transition.

By default, access to the SMTP interface is restricted from any IP addresses. To allow access to the SMTP interface, you must enable context-based restrictions. Specifically to access the SMTP interface, you must select the API type as SMTP Configuration while setting up the CBR rule.

The set of IPs associated in the network zone selected while setting up the CBR rule will be automatically allowlisted to connect to the SMTP server.

It is mandatory to set up CBR rules for the IBM Cloud Event Notifications instances you intend to use for SMTP interface feature

Requirements to send email over SMTP Interface

After successful verification of a SMTP configuration in an IBM Cloud Event Notifications instance, to send email using the SMTP Interface you need the following parameters:

  1. You can connect to Event Notifications SMTP interface using Public endpoints or Private endpoints via CSE (Cloud Service Endpoint) and VPE (Virtual Private Endpoint) gateway. The SMTP endpoints are available in the us-south (Dallas) and eu-de (Frankfurt) regions.

    Dallas (us-south) SMTP endpoint:

    • SMTP Public Endpoint: smtp.us-south.event-notifications.cloud.ibm.com
    • SMTP Private Endpoint: private.smtp.us-south.event-notifications.cloud.ibm.com
    • Event Notifications instances in the following regions connect to this endpoint: us-south (Dallas), ca-tor (Toronto), jp-tok (Tokyo), jp-osa (Osaka), au-syd (Sydney), eu-gb (London), br-sao (Sao Paulo), ca-mon (Montreal), in-che (Chennai), us-east (Washington DC), in-mum (Mumbai)

    Frankfurt (eu-de) SMTP endpoint:

    • SMTP Public Endpoint: smtp.eu-de.event-notifications.cloud.ibm.com
    • SMTP Private Endpoint: private.smtp.eu-de.event-notifications.cloud.ibm.com
    • Event Notifications instances in the following regions connect to this endpoint: eu-de (Frankfurt), eu-es (Madrid)

  2. The SMTP interface port numbers and encryption methods. Event Notifications supports two ports for SMTP connections:

    Table 1. Supported SMTP ports and encryption methods
    Port Encryption Method Description How It Works
    587 STARTTLS (Explicit TLS) Connection starts unencrypted and upgrades to TLS The initial connection is established in plain text. Your SMTP client issues the STARTTLS command to initiate a TLS handshake, upgrading the connection to an encrypted channel. Also known as "opportunistic TLS."
    465 TLS Wrapper (Implicit TLS/SSL) Connection is encrypted from the start The TLS/SSL handshake occurs immediately upon connection, before any SMTP commands are exchanged. The entire SMTP session is wrapped in a TLS/SSL layer. Also known as SMTPS (SMTP Secure).

    Both ports provide secure email transmission with strong encryption. Choose the port that best fits your SMTP client's configuration requirements and security policies.

  3. The SMTP username and password. A maximum of 5 users can be created in a single SMTP configuration. Event Notifications supports Login and Plain authentication methods from the SMTP protocol.

    When you create an SMTP user, you receive a username and password. However, password-based authentication will be deprecated in the near future. You must migrate to API key-based authentication using Service IDs. For more information, see Using API keys for SMTP authentication.

    After the SMTP username and password are created, you can clone the same credentials across SMTP configurations within the same instance. This is supported through the API, CLI, SDK, and Terraform.

  4. Valid IP addresses or subnets can be allowlisted from CBR through which the client can connect to the SMTP interface.

  5. IBM Cloud Event Notifications SMTP interface supports secure connections using either STARTTLS (port 587) or implicit TLS/SSL (port 465) for secure data transmission over networks.

  6. When accessing IBM Cloud Event Notifications through the SMTP interface, your SMTP client application assembles the message. The information you need to provide may vary depending on the application you are using. The following are the minimum requirements for an SMTP exchange between a client and a server:

    • Source address: The source address must belong to the configured domain; otherwise, the sender address will be rejected.
    • Destination address: The destination address can be any valid email address or set of email addresses.
    • Message data: Ensure that the message data is spam-free, clean, and sensible.

According to the current configurations, attachments are not supported in Event Notifications SMTP interface.

Using API keys for SMTP authentication

To use multiple API keys for SMTP authentication, you must create a Service ID and assign the appropriate SMTP role. The API keys created for the Service ID act as passwords for the SMTP user, providing enhanced security and flexibility.

Creating API keys for SMTP users

To create API keys for SMTP users, complete the following steps:

  1. Create a Service ID and configure your Event Notifications instance as part of access policy. To learn how to create and configure Service IDs, see Creating and working with service IDs and Assigning access in the console.

  2. Assign the SMTP role to the Service ID. This role grants the Service ID permission to authenticate to the SMTP interface. Confirm your access policy, resource, and the role.

  3. Create one or more API keys for the Service ID. To learn how to create and manage API keys, see Managing service ID API keys.

  4. Use the API key as the password when authenticating to the SMTP interface. The username remains the SMTP username you received when creating the SMTP user.

API key limits

The number of API keys you can create per Service ID is determined by IBM Cloud IAM limits. For current limits and quotas, check IAM limits.

Using SMTP interface for sending emails

  1. Configure SMTP-enabled software, including ServiceNow, Jira, blogging platforms, RSS aggregators, list management software, and workflow systems, using the provided SMTP endpoint, port, and valid username-password credentials.

  2. To send an email using the SMTP interface, you can use an SMTP-enabled programming language, email server, or application. Ensure that you complete all the required steps mentioned above and have the correct SMTP endpoint, port, and credentials to connect to the IBM Cloud Event Notifications SMTP interface.

  3. If you currently administer your own email server, you can use the IBM Cloud SMTP endpoint, port, and credentials to send all your outgoing email through the Event Notifications SMTP configuration, without modifying your existing email clients and applications.

  4. To interact with the IBM Cloud Event Notifications SMTP interface using the command line, see the following examples:

    Example using port 587 with STARTTLS:

    swaks --to recipient@example.com --from sender@yourdomain.com --server smtp.us-south.event-notifications.cloud.ibm.com --port 587 --auth PLAIN --auth-user <your-smtp-username> --auth-password <your-smtp-password> --tls
=== Trying smtp.us-south.event-notifications.cloud.ibm.com:587...
=== Connected to smtp.us-south.event-notifications.cloud.ibm.com.
<- 220 mail.event-notifications.cloud.ibm.com ESMTP Service Ready
 -> EHLO your-hostname.local
<- 250-Hello your-hostname.local
<- 250-PIPELINING
<- 250-8BITMIME
<- 250-ENHANCEDSTATUSCODES
<- 250-CHUNKING
<- 250-STARTTLS
<- 250-SIZE 31457280
<- 250 LIMITS RCPTMAX=100
 -> STARTTLS
<- 220 2.0.0 Ready to start TLS
=== TLS started with cipher TLSv1.3:AEAD-CHACHA20-POLY1305-SHA256:256
=== TLS client certificate not requested and not sent
=== TLS no client certificate set
=== TLS peer[0]  subject=[/CN=smtp.us-south.event-notifications.cloud.ibm.com]
===        commonName=[smtp.us-south.event-notifications.cloud.ibm.com], subjectAltName=[DNS:private.smtp.us-south.event-notifications.cloud.ibm.com, DNS:smtp.us-south.event-notifications.cloud.ibm.com] notAfter=[2026-07-12T14:18:53Z]
=== TLS peer[1]  subject=[/C=US/O=Let's Encrypt/CN=E8]
===        commonName=[E8], subjectAltName=[] notAfter=[2027-03-12T23:59:59Z]
=== TLS peer certificate passed CA verification, passed host verification (using host smtp.us-south.event-notifications.cloud.ibm.com to verify)
 ~> EHLO your-hostname.local
<~ 250-Hello your-hostname.local
<~ 250-PIPELINING
<~ 250-8BITMIME
<~ 250-ENHANCEDSTATUSCODES
<~ 250-CHUNKING
<~ 250-AUTH PLAIN
<~ 250-SIZE 31457280
<~ 250 LIMITS RCPTMAX=100
 ~> AUTH PLAIN <base64-encoded-credentials>
<~ 235 2.0.0 Authentication succeeded
 ~> MAIL FROM:<sender@yourdomain.com>
<~ 250 2.0.0 Roger, accepting mail from <sender@yourdomain.com>
 ~> RCPT TO:<recipient@example.com>
<~ 250 2.0.0 I'll make sure <recipient@example.com> gets this
 ~> DATA
<~ 354 Go ahead. End your data with <CR><LF>.<CR><LF>
 ~> Date: Tue, 14 Apr 2026 15:35:16 +0530
 ~> To: recipient@example.com
 ~> From: sender@yourdomain.com
 ~> Subject: test Tue, 14 Apr 2026 15:35:16 +0530
 ~> Message-Id: <20260414153516.009507@your-hostname.local>
 ~> X-Mailer: swaks v20240103.0 jetmore.org/john/code/swaks/
 ~>
 ~> This is a test mailing
 ~>
 ~>
 ~> .
<~ 250 2.0.0 Ok: queued
 ~> QUIT
<~ 221 2.0.0 Bye

    Example using port 465 with implicit TLS/SSL:

    swaks --to recipient@example.com --from sender@yourdomain.com --server smtp.us-south.event-notifications.cloud.ibm.com --port 465 --auth PLAIN --auth-user <your-smtp-username> --auth-password <your-smtp-password> --tls-on-connect
=== Trying smtp.us-south.event-notifications.cloud.ibm.com:465...
=== Connected to smtp.us-south.event-notifications.cloud.ibm.com.
=== TLS started with cipher TLSv1.3:AEAD-CHACHA20-POLY1305-SHA256:256
=== TLS client certificate not requested and not sent
=== TLS no client certificate set
=== TLS peer[0]  subject=[/CN=smtp.us-south.event-notifications.cloud.ibm.com]
===        commonName=[smtp.us-south.event-notifications.cloud.ibm.com], subjectAltName=[DNS:private.smtp.us-south.event-notifications.cloud.ibm.com, DNS:smtp.us-south.event-notifications.cloud.ibm.com] notAfter=[2026-07-12T14:18:53Z]
=== TLS peer[1]  subject=[/C=US/O=Let's Encrypt/CN=E8]
===        commonName=[E8], subjectAltName=[] notAfter=[2027-03-12T23:59:59Z]
=== TLS peer certificate passed CA verification, passed host verification (using host smtp.us-south.event-notifications.cloud.ibm.com to verify)
<~ 220 mail.event-notifications.cloud.ibm.com ESMTP Service Ready
 ~> EHLO your-hostname.local
<~ 250-Hello your-hostname.local
<~ 250-PIPELINING
<~ 250-8BITMIME
<~ 250-ENHANCEDSTATUSCODES
<~ 250-CHUNKING
<~ 250-AUTH PLAIN
<~ 250-SIZE 31457280
<~ 250 LIMITS RCPTMAX=100
 ~> AUTH PLAIN <base64-encoded-credentials>
<~ 235 2.0.0 Authentication succeeded
 ~> MAIL FROM:<sender@yourdomain.com>
<~ 250 2.0.0 Roger, accepting mail from <sender@yourdomain.com>
 ~> RCPT TO:<recipient@example.com>
<~ 250 2.0.0 I'll make sure <recipient@example.com> gets this
 ~> DATA
<~ 354 Go ahead. End your data with <CR><LF>.<CR><LF>
 ~> Date: Tue, 14 Apr 2026 15:36:25 +0530
 ~> To: recipient@example.com
 ~> From: sender@yourdomain.com
 ~> Subject: test Tue, 14 Apr 2026 15:36:25 +0530
 ~> Message-Id: <20260414153625.009884@your-hostname.local>
 ~> X-Mailer: swaks v20240103.0 jetmore.org/john/code/swaks/
 ~>
 ~> This is a test mailing
 ~>
 ~>
 ~> .
<~ 250 2.0.0 Ok: queued
 ~> QUIT
<~ 221 2.0.0 Bye

Using Virtual Private Endpoint (VPE) to send emails over SMTP Private Endpoint

  1. To send emails via the SMTP Private Endpoint, you need to create or attach a Virtual Private Endpoint (VPE) to your IBM Cloud Virtual Private Cloud (VPC).

  2. Make sure to attach the VPE gateway to the same VPC where your IKS (IBM Kubernetes Service) clusters or VSI (Virtual Service Instance) are deployed.

  3. While creating VPE:

    1. Select the required Region and VPC, from where you want to connect to the SMTP Private Endpoint.
    2. Under Request connection to a service, select Event Notifications.
    3. Enable the endpoint: private.smtp.<region>.event-notifications.cloud.ibm.com
    4. Select the required subnet for the Reserved IP. You can bind only one IP address per VPC zone to an endpoint gateway.

    SMTP Private Endpoint VPE
    SMTP Private Endpoint VPE

  4. Create a Network Zone in Context-Based Restrictions (CBR) for your VPC.

  5. Create a CBR Rule for your Event Notifications instance and add the Network Zone created earlier, or add the Network Zone to an existing CBR Rule for your instance.

  6. Use the SMTP Private Endpoint listed in the SMTP configurations requirements.

Tracking Email Status