update_system_alert_prefs

UsersApi.update_system_alert_prefs(action, role_id=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Subscribe or unsubscribe from system alerts

subscribe sends an SNS confirmation email (Cognito email claim). unsubscribe drops a confirmed subscription. Requires users.manage and system-settings.view. Subscribe is not idempotent while pending (5-minute resend window). Already subscribed or already unsubscribed still return 200.

Parameters:

  • action (str) – subscribe or unsubscribe (any case). Missing returns IPV-1052. Other values return IPV-1041 (or API Gateway enum rejection with ValidateAll). (required)

  • role_id (str) – Amorphic role ID the request is authorized against. Must be a role the user belongs to. Also recorded in audit logs.

  • _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

  • _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

  • _content_type (str, Optional) – force content-type for the request.

  • _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

  • _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

UpdateSystemAlertPrefsResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: PUT /system-alert-prefs

Success (HTTP 200)

subscribe: confirmation-email Message, or already subscribed. unsubscribe: success Message, or already unsubscribed.

subscribe, email sent

{
  "Message": "Confirmation email sent to user1@example.com, please click the link in email to complete the subscription."
}

subscribe when already yes

{
  "Message": "User user1 has been already subscribed to system alerts."
}

unsubscribe confirmed

{
  "Message": "Successfully Unsubscribed user user1 from system alerts. You will not receive any system alerts to your email anymore."
}

unsubscribe when status is no

{
  "Message": "User user1 has been already unsubscribed from system alerts."
}

Errors

Documented error codes: AUTH-1001, AUTH-1003, AUTH-1030, IPV-1052, IPV-1041, IPV-1002, GE-1020, GE-1034, GE-1023, RTE-1001.

HTTP 400

{“Message”: “<CODE> - <text>”} except pending unsubscribe. Codes: AUTH-1001, AUTH-1003, AUTH-1030, IPV-1052 (missing action), IPV-1041 (invalid action), IPV-1002, GE-1020, GE-1034 (resubscribe within 5 minutes). Pending unsubscribe is {“Message”: “Cannot unsubscribe a subscription that is pending confirmation.”} with no code. GenericFailure is HTTP 400.

action query missing

{
  "Message": "IPV-1052 - Missing mandatory parameter(s) action in queryStringParameters/pathParameters"
}

action is not subscribe or unsubscribe

{
  "Message": "IPV-1041 - Invalid parameter - action, allowed values/keys are ['subscribe', 'unsubscribe']"
}

unsubscribe while pending

{
  "Message": "Cannot unsubscribe a subscription that is pending confirmation."
}

subscribe again within 5 minutes

{
  "Message": "GE-1034 - Email has already been sent to user1@example.com. Please wait for 5 more minute(s) for another email or complete the existing Verification."
}

Missing users.manage or system-settings.view

{
  "Message": "AUTH-1030 - User is not authorized to update system alert subscription status due to the following missing permission(s) - {'Users': ['manage'], 'System Settings': ['view']}"
}

HTTP 500

Missing SubscriptionArn on unsubscribe is GE-1023 InconsistentMetadata (HTTP 500). Other uncaught errors use {“Message”: “RTE-1001 - <exception>.”} (for example a service user PUT that has no Cognito email claim).

Status set but SubscriptionArn missing

{
  "Message": "GE-1023 - Inconsistent metadata, please clean up and retry."
}

Uncaught handler failure

{
  "Message": "RTE-1001 - name 'claims' is not defined."
}