Get all destination entries
GET /v1/distribution_lists/{account_id}/destinations
Retrieve all destinations in the distribution list for the specified account.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
notificationapi.accountemails.view
Request
Parameters
accountId
Required *
string
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
Response
200 - Successfully retrieved all destinations from the distribution list.
destinations
array
Array of destination entries.
400 -
403 -
404 -
429 -
500 -
Add a destination entry
POST /v1/distribution_lists/{account_id}/destinations
Add a destination entry to the distribution list. A maximum of 10 destination entries per destination type. In terms of enterprise accounts, you can provide an Event Notifications destination that is from a different account than the distribution list account, provided these two accounts are from the same enterprise and the user has permission to manage the Event Notifications destinations on both accounts.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
notificationapi.accountemails.updateresource-controller.instance.retrieve
Request
Parameters
accountId
Required *
string
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
addDestinationPrototype
Required *
AddDestinationPrototype
Response
201 - Successfully created the destination.
400 - Bad request - maximum limit reached or invalid parameters.
status
integer
HTTP status code.
trace
string
The unique identifier for tracing the request.
errors
array
Array of error details.
403 -
404 -
429 -
500 -
Get a destination entry
GET /v1/distribution_lists/{account_id}/destinations/{destination_id}
Retrieve a specific destination from the distribution list of the account.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
notificationapi.accountemails.view
Request
Parameters
accountId
Required *
string
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
destinationId
Required *
string
The ID of the destination.
Example: 12345678-1234-1234-1234-123456789012
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^([0-9a-zA-Z]{1,100}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/
Response
200 - Successfully retrieved the destination.
400 -
403 -
404 -
429 -
500 -
Delete a destination entry
DELETE /v1/distribution_lists/{account_id}/destinations/{destination_id}
Remove a destination entry.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
notificationapi.accountemails.updateresource-controller.instance.retrieve
Request
Parameters
accountId
Required *
string
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
destinationId
Required *
string
The ID of the destination.
Example: 12345678-1234-1234-1234-123456789012
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^([0-9a-zA-Z]{1,100}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/
Response
204 - Successfully deleted the destination entry.
400 -
403 -
429 -
500 -
Test a destination entry
POST /v1/distribution_lists/{account_id}/destinations/{destination_id}/test
Send a test notification to a destination in the distribution list. This allows you to verify that the destination is properly configured and can receive notifications.
Authorization
To call this method, you must be assigned one or more IAM access roles that include the following action.
notificationapi.accountemails.update
Request
Parameters
accountId
Required *
string
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
destinationId
Required *
string
The ID of the destination.
Example: 12345678-1234-1234-1234-123456789012
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^([0-9a-zA-Z]{1,100}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/
testDestinationRequestBodyPrototype
Required *
TestDestinationRequestBodyPrototype
Response
200 - Test notification sent successfully.
message
string
The status message that indicates the test result.
400 -
403 -
404 -
429 -
500 -
Get user notifications
GET /v1/notifications
Retrieve all notifications for the requested user.
Request
Parameters
accountId
string
The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
start
string
An opaque page token that specifies the resource to start the page on or after. If unspecified, the first page of results is returned.
Example: 3fe78a36b9aa7f26
Constraints:
- Min length: 1
- Max length: 512
- Pattern:
/^[a-zA-Z0-9_-]+$/
limit
number
The maximum number of items to return per page. If unspecified, a default limit of 50 is used.
Example: 50
Default: 50
Response
200 - Successfully retrieved notifications.
limit
integer
The maximum number of items returned in this response.
total_count
integer
The total number of notifications in the collection.
first
PaginationLink
A pagination link object containing the URL to a page.
previous
PaginationLinkWithToken
A pagination link object with a page token. Used for next, previous, and last page links.
next
PaginationLinkWithToken
A pagination link object with a page token. Used for next, previous, and last page links.
last
PaginationLinkWithToken
A pagination link object with a page token. Used for next, previous, and last page links.
notifications
array
Array of notification entries.
400 -
401 -
403 -
429 -
500 -
Get all communication preferences
GET /v1/notifications/{iam_id}/preferences
Retrieve all communication preferences of a user in an account.
Request
Parameters
iamId
Required *
string
The IAM ID of the user. Must match the IAM ID in the bearer token.
Example: IBMid-1234567890
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z-]{1,100}$/
accountId
string
The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
Response
200 - Successfully retrieved all user preferences for the given account.
incident_severity1
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity2
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity3
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity4
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_high
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_medium
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_low
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
announcements_major
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
announcements_minor
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
security_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
account_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_order
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_invoices
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_payments
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_subscriptions_and_promo_codes
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_spending_alerts
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
resourceactivity_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_review
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved_vsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved_server
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_reload_complete
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_complete_vsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_complete_server
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
400 -
403 -
404 -
429 -
500 -
Create communication preferences
POST /v1/notifications/{iam_id}/preferences
Create communication preferences for the specified account.
Request
Parameters
iamId
Required *
string
The IAM ID of the user. Must match the IAM ID in the bearer token.
Example: IBMid-1234567890
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z-]{1,100}$/
incidentSeverity1
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
Example: {"channels":["email"],"updates":true}
incidentSeverity2
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incidentSeverity3
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incidentSeverity4
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenanceHigh
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenanceMedium
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenanceLow
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
announcementsMajor
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
announcementsMinor
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
securityNormal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
accountNormal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageOrder
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageInvoices
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsagePayments
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageSubscriptionsAndPromoCodes
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageSpendingAlerts
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
resourceactivityNormal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
orderingReview
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
Example: {"channels":["email"]}
orderingApproved
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
orderingApprovedVsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
orderingApprovedServer
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioningReloadComplete
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioningCompleteVsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioningCompleteServer
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
accountId
string
The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
Response
201 - Successfully created communication preferences.
incident_severity1
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity2
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity3
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity4
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_high
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_medium
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_low
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
announcements_major
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
announcements_minor
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
security_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
account_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_order
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_invoices
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_payments
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_subscriptions_and_promo_codes
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_spending_alerts
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
resourceactivity_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_review
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved_vsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved_server
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_reload_complete
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_complete_vsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_complete_server
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
400 -
403 -
409 -
429 -
500 -
Replace communication preferences
PUT /v1/notifications/{iam_id}/preferences
Replace the communication preferences for the specified account.
Request
Parameters
iamId
Required *
string
The IAM ID of the user. Must match the IAM ID in the bearer token.
Example: IBMid-1234567890
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z-]{1,100}$/
incidentSeverity1
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
Example: {"channels":["email"],"updates":true}
incidentSeverity2
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incidentSeverity3
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incidentSeverity4
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenanceHigh
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenanceMedium
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenanceLow
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
announcementsMajor
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
announcementsMinor
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
securityNormal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
accountNormal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageOrder
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageInvoices
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsagePayments
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageSubscriptionsAndPromoCodes
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billingAndUsageSpendingAlerts
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
resourceactivityNormal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
orderingReview
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
Example: {"channels":["email"]}
orderingApproved
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
orderingApprovedVsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
orderingApprovedServer
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioningReloadComplete
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioningCompleteVsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioningCompleteServer
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
accountId
string
The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
Response
200 - Successfully updated communication preferences.
incident_severity1
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity2
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity3
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
incident_severity4
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_high
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_medium
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
maintenance_low
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
announcements_major
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
announcements_minor
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
security_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
account_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_order
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_invoices
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_payments
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_subscriptions_and_promo_codes
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
billing_and_usage_spending_alerts
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
resourceactivity_normal
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_review
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved_vsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
ordering_approved_server
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_reload_complete
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_complete_vsi
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
provisioning_complete_server
PreferenceValueWithoutUpdates
Preference settings for notification types that do not support updates.
400 -
403 -
404 -
429 -
500 -
Reset all preferences to their default values
DELETE /v1/notifications/{iam_id}/preferences
Delete all communication preferences for the specified account, and reset all preferences to their default values.
Request
Parameters
iamId
Required *
string
The IAM ID of the user. Must match the IAM ID in the bearer token.
Example: IBMid-1234567890
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z-]{1,100}$/
accountId
string
The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
Response
204 - Successfully deleted all communication preferences.
400 -
403 -
429 -
Get acknowledgement
GET /v1/notifications/acknowledgement
Retrieve the timestamp of the last acknowledgement by the user for a specific account..
Request
Parameters
accountId
string
The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
Response
200 - Successfully retrieved acknowledgement.
has_unread
boolean
Indicates whether the user has unread notifications.
last_acknowledged
integer
The timestamp of the last acknowledgement.
401 -
403 -
404 -
500 -
Update acknowledgement
PUT /v1/notifications/acknowledgement
Update the timestamp of the last acknowledgement by the user for a specific account.
Request
Parameters
lastAcknowledged
Required *
number
The timestamp of the last acknowledgement.
Example: 1772804159452
accountId
string
The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
Response
200 - Successfully updated existing acknowledgement.
has_unread
boolean
Indicates whether the user has unread notifications.
last_acknowledged
integer
The timestamp of the last acknowledgement.
201 - Successfully created new acknowledgement.
has_unread
boolean
Indicates whether the user has unread notifications.
last_acknowledged
integer
The timestamp of the last acknowledgement.