{
  "openapi": "3.1.0",
  "info": {
    "title": "WazobiaMail API",
    "version": "1.0.0",
    "description": "Customer-facing WazobiaMail API. Base URL https://app.wazobiamail.com/api/v1. Every response uses the {success, message, data} envelope. This specification covers only the public customer endpoints.",
    "contact": {
      "name": "WazobiaMail Support",
      "url": "https://wazobiamail.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://app.wazobiamail.com/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Auth",
      "description": "Sign up, sign in, tokens and sessions. No credentials needed except where a token is exchanged."
    },
    {
      "name": "Account",
      "description": "Profile, password, two-factor, notifications and account data."
    },
    {
      "name": "Sending",
      "description": "Sending API keys, messages, domains, SMTP access and engagement."
    },
    {
      "name": "Mailboxes",
      "description": "Hosted mailboxes and their credentials."
    },
    {
      "name": "Relays",
      "description": "Customer SMTP relay configurations."
    },
    {
      "name": "Billing",
      "description": "Plans, subscriptions, invoices, payments and email credits."
    },
    {
      "name": "Support",
      "description": "Support tickets."
    },
    {
      "name": "Dashboard",
      "description": "Usage overview and onboarding state."
    }
  ],
  "paths": {
    "/auth/register": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Create an account",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 12,
                    "example": "CorrectHorse!Battery9Staple"
                  },
                  "username": {
                    "type": "string",
                    "example": "you"
                  },
                  "planId": {
                    "type": "string",
                    "example": "starter",
                    "description": "Selected plan id (free, starter, pro, business, enterprise, custom, payg). The account starts active on Free."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Account created; returns tokens and the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthPayload"
                }
              }
            }
          }
        }
      }
    },
    "/auth/login": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Sign in with email and password",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  },
                  "password": {
                    "type": "string",
                    "example": "CorrectHorse!Battery9Staple"
                  },
                  "totp_code": {
                    "type": "string",
                    "description": "Required only when 2FA is on.",
                    "example": "123456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in; returns tokens and the account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthPayload"
                }
              }
            }
          }
        }
      }
    },
    "/auth/refresh": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Exchange a refresh token for new tokens",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "refreshToken"
                ],
                "properties": {
                  "refreshToken": {
                    "type": "string",
                    "example": "REFRESH_TOKEN"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New token pair.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthPayload"
                }
              }
            }
          }
        }
      }
    },
    "/auth/logout": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Revoke a refresh token",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "refreshToken"
                ],
                "properties": {
                  "refreshToken": {
                    "type": "string",
                    "example": "REFRESH_TOKEN"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Logged out.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/me": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Read the current account",
        "responses": {
          "200": {
            "description": "The account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/otp/send": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Email a one-time sign-in code",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code sent if the account can use code login.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/otp/verify": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Sign in with a one-time code",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "code"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  },
                  "code": {
                    "type": "string",
                    "example": "123456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthPayload"
                }
              }
            }
          }
        }
      }
    },
    "/auth/magic-link/send": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Email a sign-in link",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link sent; valid 15 minutes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/magic-link/verify": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Sign in from a magic link",
        "security": [],
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Single-use token from the emailed link."
          }
        ],
        "responses": {
          "200": {
            "description": "Signed in.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthPayload"
                }
              }
            }
          }
        }
      }
    },
    "/auth/password/forgot": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Request a password-reset code",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reset code requested.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/password/reset": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Reset the password with a code",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "otp_code",
                  "new_password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  },
                  "otp_code": {
                    "type": "string",
                    "example": "123456"
                  },
                  "new_password": {
                    "type": "string",
                    "minLength": 12,
                    "example": "NewCorrectHorse!Battery9"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password reset.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/oauth/google": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Start Google sign-in (redirect)",
        "security": [],
        "responses": {
          "302": {
            "description": "Redirects to Google with PKCE and a one-time state."
          }
        }
      }
    },
    "/auth/oauth/github": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "Start GitHub sign-in (redirect)",
        "security": [],
        "responses": {
          "302": {
            "description": "Redirects to GitHub with a one-time state."
          }
        }
      }
    },
    "/auth/oauth/exchange": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Exchange an OAuth code for tokens",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "description": "Single-use code from the provider callback.",
                    "example": "PROVIDER_CODE"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Signed in.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthPayload"
                }
              }
            }
          }
        }
      }
    },
    "/auth/sessions": {
      "get": {
        "tags": [
          "Auth"
        ],
        "summary": "List active sessions",
        "responses": {
          "200": {
            "description": "Session list with an isCurrent flag.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/sessions/{session_id}": {
      "delete": {
        "tags": [
          "Auth"
        ],
        "summary": "Revoke one session",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/auth/sessions/revoke-all": {
      "post": {
        "tags": [
          "Auth"
        ],
        "summary": "Revoke every other session",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Other sessions revoked; the current one is preserved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/profile": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Read the account profile",
        "responses": {
          "200": {
            "description": "Profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountEnvelope"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Account"
        ],
        "summary": "Update the account profile",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Ada"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/password": {
      "put": {
        "tags": [
          "Account"
        ],
        "summary": "Change the password",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "current_password",
                  "new_password"
                ],
                "properties": {
                  "current_password": {
                    "type": "string",
                    "example": "OldCorrectHorse!9"
                  },
                  "new_password": {
                    "type": "string",
                    "minLength": 12,
                    "example": "NewCorrectHorse!Battery9"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Password changed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/otp-login": {
      "put": {
        "tags": [
          "Account"
        ],
        "summary": "Toggle code-based login",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "enabled"
                ],
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preference saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/2fa/setup": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Start authenticator setup",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the provisioning URI and secret.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/2fa/verify": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Confirm authenticator setup",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "example": "123456"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Two-factor enabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/2fa/disable": {
      "post": {
        "tags": [
          "Account"
        ],
        "summary": "Turn off two-factor auth",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Two-factor disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account": {
      "delete": {
        "tags": [
          "Account"
        ],
        "summary": "Delete the account",
        "responses": {
          "200": {
            "description": "Account scheduled for deletion.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/onboarding-profile": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Read onboarding state",
        "responses": {
          "200": {
            "description": "Onboarding profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/activity": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "List account activity",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Activity items with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/account/security-preferences": {
      "put": {
        "tags": [
          "Account"
        ],
        "summary": "Update security preferences",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "sessionTimeoutMinutes": {
                    "type": "integer",
                    "example": 60
                  },
                  "notifyNewSignin": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preferences saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/notifications": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "List notifications",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Notification items with pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/notifications/{id}/read": {
      "put": {
        "tags": [
          "Account"
        ],
        "summary": "Mark one notification read",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Marked read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/notifications/read-all": {
      "put": {
        "tags": [
          "Account"
        ],
        "summary": "Mark all notifications read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "All marked read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/notifications/{id}": {
      "delete": {
        "tags": [
          "Account"
        ],
        "summary": "Delete a notification",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/notifications/unread-count": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Count unread notifications",
        "responses": {
          "200": {
            "description": "Unread count.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/notifications/preferences": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Read notification preferences",
        "responses": {
          "200": {
            "description": "Preferences.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Account"
        ],
        "summary": "Update notification preferences",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "billingNotifications": {
                    "type": "boolean",
                    "example": true
                  },
                  "usageLimitNotifications": {
                    "type": "boolean",
                    "example": true
                  },
                  "frequency": {
                    "type": "string",
                    "example": "instant"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Preferences saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/messages": {
      "post": {
        "tags": [
          "Sending"
        ],
        "summary": "Send an email",
        "security": [
          {
            "sendingApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "envelopeSender",
                  "content"
                ],
                "properties": {
                  "envelopeSender": {
                    "type": "string",
                    "format": "email",
                    "example": "hello@mail.example.com"
                  },
                  "to": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    },
                    "example": [
                      "customer@example.com"
                    ]
                  },
                  "cc": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    }
                  },
                  "bcc": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    }
                  },
                  "content": {
                    "type": "object",
                    "required": [
                      "from",
                      "subject"
                    ],
                    "properties": {
                      "from": {
                        "type": "string",
                        "example": "Example Store <hello@mail.example.com>"
                      },
                      "subject": {
                        "type": "string",
                        "minLength": 1,
                        "example": "Your receipt"
                      },
                      "htmlBody": {
                        "type": "string",
                        "example": "<p>Thanks for your order.</p>"
                      },
                      "textBody": {
                        "type": "string",
                        "example": "Thanks for your order."
                      },
                      "replyTo": {
                        "type": "string",
                        "example": "Support <support@mail.example.com>"
                      }
                    }
                  }
                },
                "description": "At least one recipient across to, cc and bcc. Maximum 10,000 total recipients. Provide a textBody or htmlBody for your message."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted for sending. data.result contains the sending result; this does not confirm inbox delivery.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "429": {
            "description": "Plan quota or send rate exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/attachments/upload": {
      "post": {
        "tags": [
          "Sending"
        ],
        "summary": "Upload an attachment",
        "security": [
          {
            "sendingApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Max 10 MB."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Uploaded; data.file contains key, fileName, contentType, sizeBytes and publicUrl. Send attachments using the multipart with-attachments endpoint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/messages/with-attachments": {
      "post": {
        "tags": [
          "Sending"
        ],
        "summary": "Send an email with attachments",
        "security": [
          {
            "sendingApiKey": []
          },
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "message",
                  "files"
                ],
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "JSON-encoded message using the same envelopeSender, to and content fields as POST /sending/messages."
                  },
                  "files": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "binary"
                    },
                    "description": "Repeat the files field for each attachment. Maximum combined size: 5 MB."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted for sending.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/tracking/messages": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "List tracked messages with opens and clicks",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tracked messages with engagement.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/track/open/{tracking_id}": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Open-tracking pixel",
        "description": "Fetched by email clients from the pixel URL in your HTML. Do not call directly.",
        "security": [],
        "parameters": [
          {
            "name": "tracking_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transparent pixel.",
            "content": {
              "image/gif": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    },
    "/sending/track/click/{tracking_id}": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Click-tracking redirect",
        "description": "Fetched by recipients from rewritten links. Do not call directly.",
        "security": [],
        "parameters": [
          {
            "name": "tracking_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirects to the destination URL."
          }
        }
      }
    },
    "/sending/domains": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "List sending domains",
        "responses": {
          "200": {
            "description": "Domain list with verification status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Sending"
        ],
        "summary": "Add a sending domain",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "mail.example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Domain created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/{domain_id}": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Read a sending domain",
        "parameters": [
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Domain.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Sending"
        ],
        "summary": "Rename a sending domain",
        "parameters": [
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "mail.example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Domain renamed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Sending"
        ],
        "summary": "Remove a sending domain",
        "parameters": [
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Domain removed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/{domain_id}/dns-records": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Read required DNS records",
        "parameters": [
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "SPF, DKIM and tracking records to publish.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/{domain_id}/verify": {
      "post": {
        "tags": [
          "Sending"
        ],
        "summary": "Verify domain DNS",
        "parameters": [
          {
            "name": "domain_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/dns-provider": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Read the DNS provider setup",
        "responses": {
          "200": {
            "description": "Provider setup.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/cloudflare/connect": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Start Cloudflare DNS connect",
        "responses": {
          "200": {
            "description": "Returns the Cloudflare authorization URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/cloudflare/callback": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Finish Cloudflare DNS connect",
        "description": "Redirect target for the Cloudflare OAuth callback.",
        "responses": {
          "200": {
            "description": "Connection finished.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/cloudflare/status": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Read Cloudflare connection status",
        "responses": {
          "200": {
            "description": "Status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/cloudflare/sync": {
      "post": {
        "tags": [
          "Sending"
        ],
        "summary": "Sync DNS records to Cloudflare",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sync result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/domains/cloudflare/disconnect": {
      "delete": {
        "tags": [
          "Sending"
        ],
        "summary": "Disconnect Cloudflare DNS",
        "responses": {
          "200": {
            "description": "Disconnected.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/sending/smtp-access": {
      "get": {
        "tags": [
          "Sending"
        ],
        "summary": "Read SMTP access state",
        "responses": {
          "200": {
            "description": "SMTP access state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": [
          "Sending"
        ],
        "summary": "Enable or rotate SMTP access",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "enabled": {
                    "type": "boolean",
                    "example": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "SMTP access updated with fresh credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/mailboxes": {
      "get": {
        "tags": [
          "Mailboxes"
        ],
        "summary": "List hosted mailboxes",
        "responses": {
          "200": {
            "description": "Mailbox list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Mailboxes"
        ],
        "summary": "Create a hosted mailbox",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domainId",
                  "localPart"
                ],
                "properties": {
                  "domainId": {
                    "type": "string",
                    "minLength": 20,
                    "maxLength": 20,
                    "description": "ID of a domain on your account."
                  },
                  "localPart": {
                    "type": "string",
                    "example": "support"
                  },
                  "displayName": {
                    "type": "string",
                    "example": "Example Support"
                  },
                  "quotaMb": {
                    "type": "integer",
                    "description": "Optional mailbox capacity in MB; account storage limits apply."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mailbox created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/mailboxes/{id}": {
      "get": {
        "tags": [
          "Mailboxes"
        ],
        "summary": "Read a hosted mailbox",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mailbox.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Mailboxes"
        ],
        "summary": "Delete a hosted mailbox",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Mailbox deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/mailboxes/{id}/credentials": {
      "post": {
        "tags": [
          "Mailboxes"
        ],
        "summary": "Issue mailbox SMTP/IMAP credentials",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credentials returned once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/mailboxes/{id}/credentials/rotate": {
      "post": {
        "tags": [
          "Mailboxes"
        ],
        "summary": "Rotate mailbox credentials",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New credentials returned once.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/mailboxes/storage": {
      "get": {
        "tags": [
          "Mailboxes"
        ],
        "summary": "Read mailbox storage usage",
        "responses": {
          "200": {
            "description": "Storage usage against the plan allowance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/smtp-relays": {
      "get": {
        "tags": [
          "Relays"
        ],
        "summary": "List SMTP relays",
        "responses": {
          "200": {
            "description": "Relay list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Relays"
        ],
        "summary": "Add an SMTP relay",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "smtp_host",
                  "smtp_port",
                  "smtp_username",
                  "smtp_password",
                  "smtp_security"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Business relay"
                  },
                  "smtp_host": {
                    "type": "string",
                    "example": "smtp.example.com"
                  },
                  "smtp_port": {
                    "type": "integer",
                    "example": 587
                  },
                  "smtp_username": {
                    "type": "string",
                    "example": "hello@example.com"
                  },
                  "smtp_password": {
                    "type": "string",
                    "format": "password"
                  },
                  "smtp_security": {
                    "type": "string",
                    "enum": [
                      "none",
                      "starttls",
                      "ssl_tls"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "inactive"
                    ]
                  },
                  "is_default": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Relay added.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/smtp-relays/{id}": {
      "get": {
        "tags": [
          "Relays"
        ],
        "summary": "Read an SMTP relay",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Relay (secrets redacted).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Relays"
        ],
        "summary": "Remove an SMTP relay",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Relay removed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Relays"
        ],
        "summary": "Update an SMTP relay",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Business relay"
                  },
                  "smtp_host": {
                    "type": "string",
                    "example": "smtp.example.com"
                  },
                  "smtp_port": {
                    "type": "integer",
                    "example": 587
                  },
                  "smtp_username": {
                    "type": "string",
                    "example": "hello@example.com"
                  },
                  "smtp_password": {
                    "type": "string",
                    "format": "password"
                  },
                  "smtp_security": {
                    "type": "string",
                    "enum": [
                      "none",
                      "starttls",
                      "ssl_tls"
                    ]
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "inactive"
                    ]
                  },
                  "is_default": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Relay updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/plans": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "List subscription plans",
        "security": [],
        "responses": {
          "200": {
            "description": "Active plans with prices and quotas.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/plans/effective": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Read your effective limits",
        "responses": {
          "200": {
            "description": "Quotas and allowances in force for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/current": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Read the current subscription",
        "responses": {
          "200": {
            "description": "Subscription or empty when none.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Start a subscription checkout",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "plan_id"
                ],
                "properties": {
                  "plan_id": {
                    "type": "string",
                    "example": "pro"
                  },
                  "interval": {
                    "type": "string",
                    "enum": [
                      "monthly",
                      "yearly"
                    ],
                    "default": "monthly"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Checkout started with payment details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/activate": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Activate after payment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "transaction_reference"
                ],
                "properties": {
                  "transaction_reference": {
                    "type": "string",
                    "example": "PAYSTACK_REF_123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Subscription activated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/auto-renew": {
      "put": {
        "tags": [
          "Billing"
        ],
        "summary": "Toggle renewal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "auto_renew"
                ],
                "properties": {
                  "auto_renew": {
                    "type": "boolean",
                    "example": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Renewal preference saved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/subscriptions/cancel": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Cancel at term end",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cancellation scheduled; access continues to term end.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/billing/invoices": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "List invoices",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice list.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/billing/invoices/{id}": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Read one invoice",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/payments/initialize": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Start a payment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount",
                  "currency"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "example": 4000
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "NGN",
                      "USD"
                    ],
                    "example": "NGN"
                  },
                  "provider": {
                    "type": "string",
                    "description": "Omit to use the default enabled gateway."
                  },
                  "purpose": {
                    "type": "string",
                    "example": "subscription"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment initialized with a reference and checkout details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/payments/verify": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Confirm a payment by reference",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "transaction_reference"
                ],
                "properties": {
                  "transaction_reference": {
                    "type": "string",
                    "example": "PAYSTACK_REF_123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/payments/methods": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "List enabled payment methods",
        "responses": {
          "200": {
            "description": "Gateways enabled for your currency.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/payments/currency": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Detect billing currency",
        "security": [],
        "description": "Reads the edge country header (NG becomes NGN, anything else USD) with an explicit currency override.",
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "NGN",
                "USD"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detected country and currency.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/units/summary": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Read credit balance",
        "responses": {
          "200": {
            "description": "Balance and allowance.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/units/packs": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "List credit packs",
        "responses": {
          "200": {
            "description": "Purchasable packs with per-1,000 rates.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/units/purchases": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Buy email credits",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pack_id"
                ],
                "properties": {
                  "pack_id": {
                    "type": "string",
                    "example": "pack_10k"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Purchase started with payment details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/units/ledger": {
      "get": {
        "tags": [
          "Billing"
        ],
        "summary": "Read the credit ledger",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ledger entries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/support": {
      "post": {
        "tags": [
          "Support"
        ],
        "summary": "Open a support ticket",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "subject",
                  "category",
                  "message"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Ada"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "you@example.com"
                  },
                  "subject": {
                    "type": "string",
                    "example": "Delivery question"
                  },
                  "category": {
                    "type": "string",
                    "example": "sending"
                  },
                  "priority": {
                    "type": "string",
                    "example": "normal"
                  },
                  "message": {
                    "type": "string",
                    "example": "How do I verify my domain?"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Ticket opened.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/support/my": {
      "get": {
        "tags": [
          "Support"
        ],
        "summary": "List your support tickets",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Your tickets.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/dashboard/overview": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Account usage overview",
        "responses": {
          "200": {
            "description": "Quotas, usage and activity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/onboarding": {
      "get": {
        "tags": [
          "Dashboard"
        ],
        "summary": "Onboarding checklist state",
        "responses": {
          "200": {
            "description": "Checklist state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/payments/webhooks/{provider}": {
      "post": {
        "tags": [
          "Billing"
        ],
        "summary": "Provider payment callback",
        "description": "Called by the payment provider, never by integrators. Deliveries are signature-verified and idempotent; configure the provider dashboard with this URL.",
        "security": [],
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "paystack"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Acknowledged.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "x-default": "ACCESS_TOKEN"
      },
      "sendingApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "x-default": "YOUR_API_KEY"
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "required": [
          "success",
          "message",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Done"
          },
          "data": {
            "description": "Payload; shape depends on the endpoint."
          }
        }
      },
      "AuthPayload": {
        "type": "object",
        "description": "{success, message, data} where data holds accessToken, refreshToken and the account.",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Login successful"
          },
          "data": {
            "type": "object",
            "properties": {
              "accessToken": {
                "type": "string",
                "example": "ACCESS_TOKEN"
              },
              "refreshToken": {
                "type": "string",
                "example": "REFRESH_TOKEN"
              },
              "account": {
                "$ref": "#/components/schemas/Account"
              }
            }
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "accountId": {
            "type": "integer",
            "example": 1
          },
          "email": {
            "type": "string",
            "example": "you@example.com"
          },
          "name": {
            "type": "string",
            "example": "Ada"
          },
          "planId": {
            "type": "string",
            "example": "starter"
          }
        }
      },
      "AccountEnvelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "example": "Account"
          },
          "data": {
            "$ref": "#/components/schemas/Account"
          }
        }
      }
    }
  }
}