General Purpose APIs

General purpose configuration queries will have the config resource name as part of the query string. You can only retrieve configuration information (GET), and cannot perform any changes (POST, DELETE) in this release. You can specify the device type to indicate the device from which you need the configuration from the email gateway.

This chapter contains the following sections:

Querying for the System Time

Sample Request

GET /esa/api/v2.0/config/system_time? 
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response

HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Apr 2018 18:06:32 GMT
Content-type: application/json
Content-Length: 121
Connection: close
{
    "data": {
        "continent": [
            "Asia",
            "India",
            "Kolkata"
        ],
        "time": "Thu Apr 12 23:38:05 2018 IST",
        "timezone": "Asia/Kolkata"
    }
}

Retrieving APIs Accessible to a User Role

You can retrieve a list of APIs that are available for a currently logged in user.

Synopsis

GET /api/v2.0/login/privileges

Request Headers

Host, Accept, Authorization

Response Headers

Content-Type, Content-Length, Connection

Sample Request

GET /esa/api/v2.0/login/privileges
HTTP/1.1
cache-control: no-cache
Postman-Token: a7eca7b8-0656-43db-b692-812396a86976
Authorization: Basic YWRtaW46SXJvbnBvcnQxMjMk
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response

HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Apr 2018 14:17:44 GMT
Content-type: application/json
Content-Length: 4392
Connection: close
{
    "data": [
        "e_message_tracking_messages",
        "e_message_tracking_detail",
        "e_message_tracking_availability",
        "e_message_tracking_verdict",
        "e_message_tracking_dlp_details",
        "e_message_tracking_amp_details",
...
...
        "e_config_macro_file_types",
        "e_config_geo_countries",
        "e_config_tracking_query_timeout",
        "e_config_spam_quarantine_appearance_details",
        "esa_config_users",
        "e_config_euq_authentication_method",
        "e_config_euq_url_details"
    ]
}

Health API

You can retrieve information about system health using the health API.

Synopsis

GET /api/v2.0/health/

Request Headers

Host, Authorization

Response Headers

Content-Type, Content-Length, Connection

Sample Request

GET /esa/api/v2.0/health
HTTP/1.1
cache-control: no-cache
Postman-Token: a7eca7b8-0656-43db-b692-812396a86976
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response

HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Content-type: application/json; charset=UTF-8
Content-Length: 5782
Connection: close
{
    "meta": {
        "totalCount": -1
    },
    "data": {
        "percentage_ram_utilization": 1,
        "messages_in_pvo_quarantines": 0,
        "resource_conservation": 0,
        "messages_in_workqueue": 0,
        "percentage_swap_utilization": 0.0,
        "percentage_queue_utilization": 0.0,
        "percentage_diskio": 0,
        "percentage_cpu_load": 17
    }
}

Delivery Status API

You can retrieve information about the mail delivery status using the Delivery Status API.

Synopsis

GET /api/v2.0/health/delivery_status

Request Headers

Host, Authorization

Response Headers

Content-Type, Content-Length, Connection

Sample Request

GET /esa/api/v2.0/health/delivery_status
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46SXJvbnBvcnRAMzAu
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate, br
Connection: keep-alive

Sample Response

HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Content-type: application/json; charset=UTF-8
Content-Length: 650
Connection: keep-alive
{
    "meta": {
        "totalCount": -1
    },
    "data": {
        "type": "delivery_status",
        "resultSet": [
            {
                "soft_bounces": 0,
                "latest_host_status": "Unknown",
                "hard_bounces": 0,
                "active_recipients": 0,
                "destination_domain": "the.encryption.queue",
                "connections_out": 0,
                "delivered_recipients": 0
            },
            {
                "soft_bounces": 0,
                "latest_host_status": "Unknown",
                "hard_bounces": 0,
                "active_recipients": 0,
                "destination_domain": "the.euq.queue",
                "connections_out": 0,
                "delivered_recipients": 0
            },
            {
                "soft_bounces": 0,
                "latest_host_status": "Unknown",
                "hard_bounces": 0,
                "active_recipients": 0,
                "destination_domain": "the.euq.release.queue",
                "connections_out": 0,
                "delivered_recipients": 0
            }
        ]
    }
}

System Status API

You can retrieve information about the overall system status using the System Status API.

Synopsis

GET /api/v2.0/health/system_status

Request Headers

Host, Authorization

Response Headers

Content-Type, Content-Length, Connection

Sample Request

GET /esa/api/v2.0/health/system_status
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46SXJvbnBvcnRAMzAu
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate, br
Connection: keep-alive

Sample Response

HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Content-type: application/json; charset=UTF-8
Content-Length: 4014
Connection: keep-alive
{
    "meta": {
        "totalCount": -1
    },
    "data": {
        "type": "system_status",
        "resultSet": {
            "rates": [
                {
                    "total_completed_recipients_rate_five": 0,
                    "delivered_recipients_rate_one": 0,
                    "messages_received_rate_five": 0,
                    "hard_bounced_recipients_rate_one": 0,
                    "hard_bounced_recipients_rate_fifteen": 0,
                    "total_completed_recipients_rate_fifteen": 0,
                    "recipients_received_rate_one": 0,
                    "total_completed_recipients_rate_one": 0,
                    "soft_bounced_events_rate_one": 0,
                    "delivered_recipients_rate_fifteen": 0,
                    "recipients_received_rate_fifteen": 0,
                    "soft_bounced_events_rate_fifteen": 0,
                    "messages_received_rate_one": 0,
                    "soft_bounced_events_rate_five": 0,
                    "messages_received_rate_fifteen": 0,
                    "delivered_recipients_rate_five": 0,
                    "recipients_received_rate_five": 0,
                    "hard_bounced_recipients_rate_five": 0
                }
            ],
            "version_details": [
                {
                    "build_date": "2022-05-12",
                    "operating_system": "14.4.20-008",
                    "install_date": "2022-05-22 19:03:09",
                    "raid_status": "Unknown",
                    "serial_number": "422CBE9B59F1C1EA69CF-34D5DFAB3D39",
                    "model": "C300V"
                }
            ],
            "gauges": [
                {
                    "ram_utilization": "1%",
                    "email_security_appliance": "0%",
                    "msgs_in_work_queue": 0,
                    "disk_io_utilization": "0%",
                    "total_active_recipients": 0,
                    "current_outgoing_connections": 0,
                    "total_queue_utilized": "0.0%",
                    "anti_virus": "0%",
                    "msgs_in_quarantine": 0,
                    "quarantine": "0%",
                    "reporting": "0%",
                    "space_used_by_quarantine": "0B",
                    "unattempted": 0,
                    "logging_disk_utilization": "2%",
                    "attempted": 0,
                    "anti_spam": "0%",
                    "logging_disk_available": "356G",
                    "current_incoming_connections": 1,
                    "total_queue_space_used": "0B",
                    "overall_cpu_load": "3%",
                    "dest_objects_in_memory": 3
                }
            ],
            "mail_system_status": [
                {
                    "up_since": "16d 17h 19m 24s",
                    "system_status": "Online",
                    "oldest_message": "No Messages",
                    "status_as_of": "Sun May 22 19:02:54 2022 GMT"
                }
            ],
            "counters": [
                {
                    "dns_reqs_reset": 933,
                    "dns_hard_bounces_reset": 0,
                    "total_hard_bounces_reset": 0,
                    "dropped_messages_uptime": 0,
                    "deleted_recipients_uptime": 0,
                    "net_reqs_lifetime": 17,
                    "dk_signed_lifetime": 0,
                    "dropped_messages_reset": 0,
                    "messages_received_uptime": 177,
                    "expired_hard_bounces_uptime": 0,
                    "rejected_recipients_reset": 0,
                    "expired_hard_bounces_reset": 0,
                    "rejected_recipients_uptime": 0,
                    "expired_lifetime": 16,
                    "global_unsub_hits_reset": 0,
                    "recipients_received_uptime": 177,
                    "five_xx_hard_bounces_uptime": 0,
                    "cache_misses_reset": 17,
                    "filter_hard_bounces_reset": 0,
                    "five_xx_hard_bounces_lifetime": 0,
                    "other_hard_bounces_reset": 0,
                    "dns_hard_bounces_uptime": 0,
                    "other_hard_bounces_lifetime": 0,
                    "total_hard_bounces_uptime": 0,
                    "cache_hits_reset": 933,
                    "rejected_recipients_lifetime": 0,
                    "dns_reqs_uptime": 933,
                    "net_reqs_uptime": 17,
                    "deleted_recipients_lifetime": 0,
                    "delivered_recipients_uptime": 177,
                    "dns_reqs_lifetime": 933,
                    "exceptions_lifetime": 916,
                    "delivered_recipients_lifetime": 177,
                    "exceptions_reset": 916,
                    "delivered_recipients_reset": 177,
                    "total_completed_recipients_lifetime": 177,
                    "cache_misses_lifetime": 17,
                    "generated_bounce_recipients_uptime": 0,
                    "total_completed_recipients_uptime": 177,
                    "net_reqs_reset": 17,
                    "pending_requests": 0,
                    "global_unsub_hits_uptime": 0,
                    "cache_hits_uptime": 933,
                    "dk_signed_uptime": 0,
                    "other_hard_bounces_uptime": 0,
                    "last_counter_reset_str": "Never",
                    "generated_bounce_recipients_reset": 0,
                    "deleted_recipients_reset": 0,
                    "messages_received_lifetime": 177,
                    "soft_bounced_events_uptime": 0,
                    "recipients_received_reset": 177,
                    "filter_hard_bounces_uptime": 0,
                    "expired_hard_bounces_lifetime": 0,
                    "recipients_received_lifetime": 177,
                    "total_hard_bounces_lifetime": 0,
                    "dk_signed_reset": 0,
                    "filter_hard_bounces_lifetime": 0,
                    "soft_bounced_events_lifetime": 0,
                    "dropped_messages_lifetime": 0,
                    "outstanding_requests": 0,
                    "cache_hits_lifetime": 933,
                    "generated_bounce_recipients_lifetime": 0,
                    "cache_misses_uptime": 17,
                    "soft_bounced_events_reset": 0,
                    "global_unsub_hits_lifetime": 0,
                    "total_completed_recipients_reset": 177,
                    "messages_received_reset": 177,
                    "expired_uptime": 16,
                    "five_xx_hard_bounces_reset": 0,
                    "dns_hard_bounces_lifetime": 0,
                    "expired_reset": 16,
                    "exceptions_uptime": 916
                }
            ]
        }
    }
}