Customizing email and SMS providers

You can customize the email sender and the SMS provider for the IBM® Verify notification messages.

Before you begin

If you want to integrate your own SMS provider for IBM Verify OTP notifications, you must configure an external webhook endpoint that accepts POST requests from IBM Verify. If you also wants to customize the email sender address so that notifications appear to come from your own domain, you must have your email domain authenticated.

Email domain authentication

To authenticate your email domain, use the Email Domain Authentication APIs. For more information about the APIs, see Email Domain Authentication.

Example

curl --request POST \
     --url https://tenant_url/config/v1.0/email-domain-auth \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

Get the DNS records for your email domain. https://{tenanturl}/config/v1.0/email-domain-auth/{domain}

Example

curl --request GET \
     --url https://tenant_url/config/v1.0/email-domain-auth/domain \
     --header 'accept: application/json'

Verify the status of your email domain. https://{tenanturl}/config/v1.0/email-domain-auth/{domain}/verify

Example

curl --request POST \
     --url https://tenant_url/config/v1.0/email-domain-auth/domain/verify \
     --header 'accept: application/json'

To change or update your custom email domain, you must delete the existing custom email domain from the notification and then register your new one.
Delete your email authentication domain. https://{tenanturl}/config/v1.0/email-domain-auth/{domain}
Example
```
curl --request DELETE \
     --url https://tenant_url/config/v1.0/email-domain-auth/domain \
     --header 'accept: application/json'
```

External webhook setup requirements

The external SMS provider must expose an HTTP POST webhook endpoint to receive OTP notification requests from IBM Verify.
The endpoint must immediately queue requests and return an HTTP response.

Sample JSON request payload

{
  "destinationPhoneNumber": "18005551212",
  "content": "Your passcode is 6439-123456. It expires in 5 minutes.",
  "category": "OTP",
  "language": "en-US",
  "otp": "123456",
  "correlation": "6439",
  "expiry": 5
}

Field-level descriptions

destinationPhoneNumber: The recipient’s phone number in E.164 format.
content: The complete SMS text that is shown to the user.
category: OTP
language: The locale or language code, for example en-US.
otp: The one-time passcode value.
correlation: The ID to correlate OTP with a verification flow; typically shown in message.
expiry: The validity duration in minutes.

Webhook response requirements

202 Accepted: Request successfully queued.
400 Bad Request: Payload format invalid.
500 Internal Server Error: Provider unable to process.

Example of a success response

{
"status": "accepted",
"statusMessage": "Message accepted by provider"
}

Example of a failure response

{
"status": "failed",
"statusMessage": "The destination phone number is invalid."
}

About this task

IBM is the default email sender and SMS provider for Verify.

Procedure

Navigate to Global configuration > Communication and select the Senders tab.

To change the email sender, click the pencil

icon on the Email tile.

Change the default values for the following email options.

Table 1.
The table describes the attributes for email notifications.
Attribute	Description
From sender address	Change this field to reflect the email address that you want listed as the sender of the notification.
From email name	Change this field to reflect the person or organization that is sending the notification. For example, your company.

Optional: Select the Use custom SMTP email server checkbox.
For your custom SMTP server, specify the following information:
- SMTP host
- Port
- Username
- Password
- Select the connection protocol, either TLS or SSL.
Click Save.

If your tenant is using IBM SMS services, and you want to change the SMS sender ID, click the pencil

icon on the SMS Provider tile.

You can modify the attribute to reflect your company or organization.

Change the default value for the following option.

Table 2.
The table describes the attribute for SMS notifications.
Attribute	Description
Alphanumeric sender ID	Change this field to reflect the alphanumeric identifier (A-Z, a-z, 0-9) that identifies the sender of the message. The value must start with an alphabetic character, cannot include spaces or special characters, and has a maximum length of 11 characters. Note: Verify does not support SMS messaging.

Click Save changes.

If your tenant is not using IBM SMS services, and you want to use an external SMS provider, click Add external SMS Provider on the SMS Provider tile.
1. Provide a name for the SMS provider.
  You can also specify an owner and email contact information.
2. Specify the request URL.
  The URL points to the external SMS provider endpoint that the Notification Service calls to send an SMS.
3. Select the type of authentication.
  
  Basic
  
  Specify the username and password.
  
  Header
  
  Specify the header name and authentication secret. If the secret is case-sensitive, select the Sensitive checkbox.
  
  None
  
  No authentication information is needed.
  
  OAuth
  
  Specify the token endpoint. Select whether the client secret is post or basic. Enter the client ID and secret.
  Note: Client post indicates that the secret is stored as an attribute. Client basic indicates that the secret is stored in the header.
  
  JSON Web Token (JWT)
  
  Specify the HTTP header value, Sub claim, Maximum valid lifetime of the JWT, and Signing algorithm. If you want, you can also specify a JWT header value prefix, a JWT header keys, and claim names.
  
  Mutual TLS (mTLS)
  
  Specify the MTLS certificate label.
1. Click Save.
  The SMS provider is created, but disabled by default.
2. Test whether your tenant is connected to you SMS provider, click Test connection.
  You can send a test payload to your SMS provider to test the connection.
3. After a successful connection test and when you are ready to use your external SMS provider, click the Configuration toggle to enable it.
4. Optional: To check on the status of your SMS provider, click View health stats.
  The health status provides a connection summary and a connection history and statistics for the URL of the SMS provider