list_mail_servers

ManagementApi.list_mail_servers(role_id, limit=None, offset=None, sortorder=None, sortby=None, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List mail servers

Returns configured mail servers. Requires system-settings.view. Pagination is in-memory after a full table scan; last page when next_available is no. Password is not returned. 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)

  • limit (str) – Page size. Defaults to 100. Maximum 500 (IPV-1050 if higher). Non-numeric values fail with HTTP 500.

  • offset (str) – 1-based item offset (1 is the first server). Omitted starts at item 1. Non-numeric values fail with HTTP 500.

  • sortorder (str) – Sort direction. Defaults to desc. Any other value (including asc) sorts ascending.

  • sortby (str) – Attribute to sort by. Defaults to LastModifiedTime. The attribute must exist on every item or the call fails with HTTP 500.

  • projection_expression (str) – Comma-separated attributes to keep on each item after pagination.

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

ListMailServersResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /mailservers

Success (HTTP 200)

Page of mail servers plus next_available (yes/no), count (this page), and total_count. Continue with offset += limit until next_available is no.

First page

{
  "mailservers": [
    {
      "ServerId": "server-a2f7d3b1-8e5c-4a6f-9d1e-2b3c4d5e6f7a",
      "ServerName": "corp-smtp",
      "ServerDescription": "Corporate SMTP",
      "Port": 587,
      "Enabled": true,
      "UserName": "smtp-user",
      "AccountEmail": "alerts@example.com",
      "LastModifiedTime": "2026-08-13 10:15:00",
      "LastModifiedBy": "jane.doe",
      "CreatedBy": "jane.doe"
    }
  ],
  "next_available": "no",
  "count": 1,
  "total_count": 1
}

Errors

Documented error codes: AUTH-1001, AUTH-1003, AUTH-1030, IPV-1002, IPV-1050, GE-1014, GE-1008.

HTTP 400

Validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AUTH-1001 (missing role_id), AUTH-1003 (user not on role), AUTH-1030 (missing system-settings.view), IPV-1002 (role_id not found), IPV-1050 (limit over 500), GE-1014 (service user).

role_id header missing

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

Caller lacks system-settings.view

{
  "Message": "AUTH-1030 - User is not authorized to list mail servers due to the following missing permission(s) - {'System Settings': ['view']}"
}

limit over 500

{
  "Message": "IPV-1050 - Out of range for items per page, Limit is 500"
}

Service user is not allowed

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

HTTP 500

Uncaught errors use {“Message”: “GE-1008 - Could not complete the request. Please try again.”}. InconsistentMetadataException and GenericFailureException also return 500.

Uncaught handler failure

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