{
  "openapi": "3.1.0",
  "info": {
    "title": "KY MailCloud API",
    "version": "1.0.0",
    "description": "Server-to-server API for integrating a KY MailCloud client account. Create and manage API keys in the client portal. API keys must never be embedded in public browser code."
  },
  "servers": [
    {
      "url": "https://mailcloud.ky-sms.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/index.php": {
      "get": {
        "summary": "API information",
        "security": [],
        "responses": {
          "200": { "$ref": "#/components/responses/Success" }
        }
      }
    },
    "/health.php": {
      "get": {
        "summary": "API health",
        "security": [],
        "responses": {
          "200": { "$ref": "#/components/responses/Success" }
        }
      }
    },
    "/profile.php": {
      "get": {
        "summary": "Get client profile",
        "x-required-scope": "profile.read",
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/balance.php": {
      "get": {
        "summary": "Get wallet balance, email price and estimated credits",
        "x-required-scope": "balance.read",
        "responses": {
          "200": {
            "description": "Wallet information",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    { "$ref": "#/components/schemas/Envelope" },
                    {
                      "type": "object",
                      "properties": {
                        "data": { "$ref": "#/components/schemas/Wallet" }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/logs.php": {
      "get": {
        "summary": "List API logs",
        "x-required-scope": "api_logs.read",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "name": "status", "in": "query", "schema": { "type": "string" } },
          { "name": "endpoint", "in": "query", "schema": { "type": "string" } },
          { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/suppressions.php": {
      "get": {
        "summary": "List email suppressions",
        "x-required-scope": "suppressions.read",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "name": "email", "in": "query", "schema": { "type": "string", "format": "email" } },
          { "name": "reason", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/delivery-events.php": {
      "get": {
        "summary": "List email delivery events",
        "x-required-scope": "delivery_events.read",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "name": "event_type", "in": "query", "schema": { "type": "string" } },
          { "name": "recipient", "in": "query", "schema": { "type": "string", "format": "email" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/engagement-events.php": {
      "get": {
        "summary": "List open and click tracking events",
        "x-required-scope": "tracking_events.read",
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "name": "event_type", "in": "query", "schema": { "type": "string", "enum": ["open", "click"] } },
          { "name": "bot_status", "in": "query", "schema": { "type": "string" } },
          { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/campaign-analytics.php": {
      "get": {
        "summary": "Get campaign analytics",
        "x-required-scope": "analytics.read",
        "parameters": [
          { "name": "campaign_reference", "in": "query", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/campaign-links.php": {
      "get": {
        "summary": "Get campaign link analytics",
        "x-required-scope": "analytics.read",
        "parameters": [
          { "name": "campaign_reference", "in": "query", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/payments.php": {
      "get": {
        "summary": "List client payments",
        "x-required-scope": "payments.read",
        "parameters": [
          { "$ref": "#/components/parameters/PerPage" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/payment.php": {
      "get": {
        "summary": "Get a payment",
        "x-required-scope": "payments.read",
        "parameters": [
          { "name": "reference", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/zainpay-status.php": {
      "get": {
        "summary": "Get available ZainPay environments and limits",
        "x-required-scope": "payments.read",
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/system-status.php": {
      "get": {
        "summary": "Get platform and maintenance status",
        "x-required-scope": "support.read",
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/tickets.php": {
      "get": {
        "summary": "List support tickets",
        "x-required-scope": "support.read",
        "parameters": [
          { "$ref": "#/components/parameters/PerPage" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/ticket.php": {
      "get": {
        "summary": "Get a support ticket and replies",
        "x-required-scope": "support.read",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "integer" } }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" } }
      }
    },
    "/create-ticket.php": {
      "post": {
        "summary": "Create a support ticket",
        "x-required-scope": "support.write",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["subject", "message"],
                "properties": {
                  "subject": { "type": "string" },
                  "message": { "type": "string" },
                  "priority": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/Success" },
          "422": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/reply-ticket.php": {
      "post": {
        "summary": "Reply to a support ticket",
        "x-required-scope": "support.write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["ticket_id", "message"],
                "properties": {
                  "ticket_id": { "type": "integer" },
                  "message": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "$ref": "#/components/responses/Success" },
          "422": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/sms/status.php": {
      "get": {
        "summary": "Get SMS placeholder status",
        "description": "Reports whether SMS delivery is configured. It currently returns available=false.",
        "x-required-scope": "sms.read",
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/sms/send.php": {
      "post": {
        "summary": "Send an SMS (placeholder only)",
        "description": "Reserved contract. Currently always returns HTTP 503 SERVICE_NOT_CONFIGURED after authentication. It never queues a message or debits the wallet.",
        "x-required-scope": "sms.send",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to", "message"],
                "properties": {
                  "to": { "type": "string", "example": "+2348012345678" },
                  "message": { "type": "string" },
                  "sender_id": { "type": "string" },
                  "client_reference": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "503": {
            "description": "SMS provider is not configured; no wallet debit occurs.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Envelope" }
              }
            }
          }
        }
      }
    },
    "/certificates/status.php": {
      "get": {
        "summary": "Get e-Certificate placeholder status",
        "description": "Reports whether certificate generation is configured. It currently returns available=false.",
        "x-required-scope": "certificates.read",
        "responses": {
          "200": { "$ref": "#/components/responses/Success" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/certificates/issue.php": {
      "post": {
        "summary": "Issue an e-Certificate (placeholder only)",
        "description": "Reserved contract. Currently always returns HTTP 503 SERVICE_NOT_CONFIGURED after authentication. It never generates a certificate or debits the wallet.",
        "x-required-scope": "certificates.issue",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["recipient_name", "certificate_title"],
                "properties": {
                  "recipient_name": { "type": "string" },
                  "recipient_email": { "type": "string", "format": "email" },
                  "certificate_title": { "type": "string" },
                  "template_reference": { "type": "string" },
                  "issue_date": { "type": "string", "format": "date" },
                  "client_reference": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "503": {
            "description": "Certificate generator is not configured; no wallet debit occurs.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Envelope" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Full API key generated in Client Portal > API Keys."
      }
    },
    "parameters": {
      "Page": {
        "name": "page",
        "in": "query",
        "schema": { "type": "integer", "minimum": 1, "default": 1 }
      },
      "PerPage": {
        "name": "per_page",
        "in": "query",
        "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "required": ["success", "message", "data", "request_id", "timestamp"],
        "properties": {
          "success": { "type": "boolean" },
          "message": { "type": "string" },
          "data": {},
          "error_code": { "type": ["string", "null"] },
          "request_id": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Wallet": {
        "type": "object",
        "required": ["currency", "wallet_status", "balance", "email_unit_price", "estimated_email_credits"],
        "properties": {
          "currency": { "type": "string", "example": "NGN" },
          "wallet_status": { "type": "string", "example": "active" },
          "balance": { "type": "string", "example": "10000.00" },
          "email_unit_price": { "type": "string", "example": "150.0000" },
          "estimated_email_credits": { "type": "integer", "example": 66 }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Successful API envelope",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Envelope" }
          }
        }
      },
      "Error": {
        "description": "Error API envelope",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Envelope" }
          }
        }
      }
    }
  }
}
