update_mail_server

ManagementApi.update_mail_server(role_id, server_id, update_mail_server_request, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Update a mail server

Updates a mail server. Requires system-settings.manage. Omitted fields are copied from the stored item; omitted Password is copied from SSM. Enabling one server disables the others. Service users are rejected (GE-1014).

Parameters:

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

  • server_id (str) – Mail server id (server-<uuid>). (required)

  • update_mail_server_request (UpdateMailServerRequest) – (required)

  • _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:

UpdateMailServerResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: PUT /mailservers/{server_id}

Request

Request / response example

{
  "ServerName": "corp-smtp",
  "Port": 587,
  "Enabled": true
}

Success (HTTP 200)

Configuration was written. Message notes a skipped enable when the SMTP test failed.

Updated

{
  "Message": "Successfully updated mail server configuration"
}

Updated but SMTP test failed

{
  "Message": "Successfully updated mail server configuration but connection test failed, skipped enabling configuration."
}

Errors

Documented error codes: AUTH-1001, AUTH-1003, AUTH-1030, IPV-1002, GE-1003, GE-1014, IPV-1008, IPV-1001, IPV-1010, IPV-1011, IPV-1012, IPV-1013, IPV-1020, IPV-1018, GE-1012, GE-1011, GE-1008.

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AUTH-1001, AUTH-1003, AUTH-1030 (missing system-settings.manage), IPV-1002 (role_id not found), GE-1003 (server missing in DynamoDB), GE-1014, IPV-1008 (extra or still-missing keys after fill), IPV-1001, IPV-1010, IPV-1011, IPV-1012, IPV-1013, IPV-1020, IPV-1018 (duplicate ServerName). SSM is read before the DynamoDB existence check; a missing SSM parameter is 500, not GE-1003.

Caller lacks system-settings.manage

{
  "Message": "AUTH-1030 - User is not authorized to update the mail server configuration due to the following missing permission(s) - {'System Settings': ['manage']}"
}

Server missing in DynamoDB

{
  "Message": "GE-1003 - Server does not exist."
}

Unexpected body key

{
  "Message": "IPV-1008 - Invalid request body, missing key(s) - HealthStatus"
}

Service user is not allowed

{
  "Message": "GE-1014 - MailServer related operations are not supported for service users"
}

HTTP 500

DynamoDB update failure uses GE-1012. SSM credential store failure uses GE-1011. Missing SSM parameter (read before the DynamoDB check) and other uncaught errors use {“Message”: “GE-1008 - Could not complete the request. Please try again.”}.

Failed to update DynamoDB item

{
  "Message": "GE-1012 - Unable to update server details, please try again later."
}

Uncaught handler failure

{
  "Message": "GE-1008 - Could not complete the request. Please try again."
}