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
account_id
Required *
str
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
account_id
Required *
str
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
add_destination_prototype
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
account_id
Required *
str
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
destination_id
Required *
str
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
account_id
Required *
str
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
destination_id
Required *
str
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
account_id
Required *
str
The IBM Cloud account ID.
Example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Constraints:
- Min length: 1
- Max length: 100
- Pattern:
/^[0-9a-zA-Z]{1,100}$/
destination_id
Required *
str
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})$/
test_destination_request_body_prototype
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
account_id
str
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
str
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
int
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
iam_id
Required *
str
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}$/
account_id
str
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
iam_id
Required *
str
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}$/
incident_severity1
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
Example: {"channels":["email"],"updates":true}
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.
Example: {"channels":["email"]}
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.
account_id
str
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
iam_id
Required *
str
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}$/
incident_severity1
PreferenceValueWithUpdates
Preference settings for notification types that support updates.
Example: {"channels":["email"],"updates":true}
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.
Example: {"channels":["email"]}
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.
account_id
str
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
iam_id
Required *
str
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}$/
account_id
str
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
account_id
str
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
last_acknowledged
Required *
int
The timestamp of the last acknowledgement.
Example: 1772804159452
account_id
str
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.