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.update
  • resource-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.update
  • resource-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.

400 -

401 -

403 -

429 -

500 -