{
  "openapi": "3.0.0",
  "paths": {
    "/api/namespaces": {
      "get": {
        "operationId": "ApiController_listNamespaces",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListNamespacesResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "List namespaces",
        "tags": [
          "Api",
          "Namespaces"
        ]
      }
    },
    "/api/emails/{namespace}/inbox": {
      "get": {
        "description": "This endpoint returns the latest emails from a specific namespace's inbox.\nWhen the `wait` query flag is set to `true` and no emails are found yet, the endpoint waits briefly and redirects back to the same URL so the client can retry the same request automatically.",
        "operationId": "ApiController_searchInbox",
        "parameters": [
          {
            "name": "namespace",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "required": true,
            "in": "query",
            "description": "The maximum number of emails that can be returned in this request. Must be between 1 and 20",
            "schema": {
              "minimum": 1,
              "maximum": 20,
              "default": 10,
              "example": 10,
              "type": "number"
            }
          },
          {
            "name": "offset",
            "required": true,
            "in": "query",
            "description": "The number of emails to skip/ignore, useful for pagination",
            "schema": {
              "minimum": 0,
              "default": 0,
              "example": 0,
              "type": "number"
            }
          },
          {
            "name": "from_timestamp",
            "required": false,
            "in": "query",
            "description": "Filter emails by starting unix timestamp in seconds",
            "schema": {
              "minimum": 0,
              "example": 1714857600,
              "type": "number"
            }
          },
          {
            "name": "to_timestamp",
            "required": false,
            "in": "query",
            "description": "Filter emails by ending unix timestamp in seconds",
            "schema": {
              "minimum": 0,
              "example": 1714857600,
              "type": "number"
            }
          },
          {
            "name": "to_addr_prefix",
            "required": false,
            "in": "query",
            "description": "Filter emails by 'to' address. Address must start with this. Example: 'foo' would return for 'foobar@...' but not 'barfoo@...'",
            "schema": {
              "example": "john@example.com",
              "type": "string"
            }
          },
          {
            "name": "from_addr_includes",
            "required": false,
            "in": "query",
            "description": "Filter emails by 'from' address. Address must contain this. Example: 'foo' would return for 'foobar@...' but not 'barfoo@...'",
            "schema": {
              "example": "john@example.com",
              "type": "string"
            }
          },
          {
            "name": "subject_includes",
            "required": false,
            "in": "query",
            "description": "Filter emails by subject. This is case insensitive. Subject must include this. Example: 'password' would return for 'Password reset', 'Reset password notification' but not 'Reset'",
            "schema": {
              "example": "example",
              "type": "string"
            }
          },
          {
            "name": "wait",
            "required": false,
            "in": "query",
            "description": "If this flag is true then the request will keep waiting till at least one response is returned",
            "schema": {
              "example": true,
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchInboxResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Search inbox",
        "tags": [
          "Api",
          "Emails"
        ]
      }
    },
    "/api/attachments/{id}": {
      "get": {
        "operationId": "ApiController_getAttachment",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "in": "path",
            "description": "Unique identifier of the attachment to retrieve",
            "schema": {
              "format": "uuid",
              "example": "5e0c23bc-dc1c-49f3-8d92-9a0d85527019",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetAttachmentResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Get email attachment",
        "tags": [
          "Api",
          "Emails"
        ]
      }
    },
    "/api/smtp/{namespace}": {
      "get": {
        "operationId": "ApiController_getSmtpSettings",
        "parameters": [
          {
            "name": "namespace",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetSmtpSettingsResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Get namespace settings",
        "tags": [
          "Api",
          "Namespaces"
        ]
      }
    },
    "/api/namespace/{namespace}/settings": {
      "post": {
        "operationId": "ApiController_updateNamespaceSettings",
        "parameters": [
          {
            "name": "namespace",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateNamespaceSettingsDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateNamespaceSettingsResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Update namespace",
        "tags": [
          "Api",
          "Namespaces"
        ]
      }
    },
    "/api/sms/numbers": {
      "get": {
        "operationId": "SmsApiController_listNumbers",
        "parameters": [],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListSmsNumbersResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "List SMS numbers",
        "tags": [
          "SmsApi",
          "SMS"
        ]
      }
    },
    "/api/sms/{phone_number}/messages": {
      "get": {
        "description": "This endpoint returns the latest SMS messages for a specific phone number.\nWhen the `wait` query flag is set to `true` and no messages are found yet, the endpoint waits briefly and redirects back to the same URL so the client can retry the same request automatically.",
        "operationId": "SmsApiController_searchMessages",
        "parameters": [
          {
            "name": "phone_number",
            "required": true,
            "in": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "required": true,
            "in": "query",
            "schema": {
              "minimum": 1,
              "maximum": 100,
              "default": 20,
              "type": "number"
            }
          },
          {
            "name": "offset",
            "required": true,
            "in": "query",
            "schema": {
              "minimum": 0,
              "default": 0,
              "type": "number"
            }
          },
          {
            "name": "body",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from_number",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from_date",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to_date",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "wait",
            "required": false,
            "in": "query",
            "schema": {
              "default": false,
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchSmsMessagesResponseDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Search SMS messages",
        "tags": [
          "SmsApi",
          "SMS"
        ]
      }
    },
    "/api/sms/virtual": {
      "post": {
        "operationId": "SmsApiController_sendVirtualSms",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendVirtualSmsDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": ""
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "summary": "Simulate SMS message",
        "tags": [
          "SmsApi",
          "SMS"
        ]
      }
    }
  },
  "info": {
    "title": "Mailisk REST API",
    "description": "REST API for Mailisk",
    "version": "1.0",
    "contact": {
      "name": "Mailisk",
      "url": "https://mailisk.com",
      "email": "support@mailisk.com"
    }
  },
  "tags": [],
  "servers": [
    {
      "url": "https://api.mailisk.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "ListNamespacesResponseDataDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "namespace": {
            "type": "string"
          },
          "shared": {
            "type": "boolean"
          },
          "shared_organisation_id": {
            "type": "string"
          },
          "settings": {
            "type": "object",
            "properties": {
              "retention_time": {
                "type": "number"
              },
              "quota_limit": {
                "type": "number",
                "nullable": true
              }
            },
            "required": [
              "retention_time"
            ]
          }
        },
        "required": [
          "id",
          "namespace",
          "shared",
          "settings"
        ]
      },
      "ListNamespacesResponseDto": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "number"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListNamespacesResponseDataDto"
            }
          }
        },
        "required": [
          "total_count",
          "data"
        ]
      },
      "SearchInboxResponseOptionsDto": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "number",
            "description": "The maximum number of emails that can be returned in this request",
            "example": 10
          },
          "offset": {
            "type": "number",
            "description": "The number of emails skipped in this response",
            "example": 0
          },
          "from_timestamp": {
            "type": "number",
            "description": "Applied starting unix timestamp filter in seconds",
            "example": 1714857600
          },
          "to_timestamp": {
            "type": "number",
            "description": "Applied ending unix timestamp filter in seconds",
            "example": 1714857600
          },
          "to_addr_prefix": {
            "type": "string",
            "description": "Applied filter for email 'to' address prefix",
            "example": "john@example.com"
          },
          "from_addr_includes": {
            "type": "string",
            "description": "Applied filter for email 'from' address substring",
            "example": "john@example.com"
          },
          "subject_includes": {
            "type": "string",
            "description": "Applied case-insensitive subject filter",
            "example": "password"
          },
          "wait": {
            "type": "boolean",
            "description": "Whether long-poll waiting was enabled for the request",
            "example": true
          }
        },
        "required": [
          "limit",
          "offset"
        ]
      },
      "EmailAddressDto": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "description": "Email address",
            "example": "john@example.com"
          },
          "name": {
            "type": "string",
            "description": "Display name, if one is specified",
            "example": "John Doe"
          }
        },
        "required": [
          "address"
        ]
      },
      "EmailAttachmentDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the attachment",
            "example": "att_123"
          },
          "filename": {
            "type": "string",
            "description": "Filename of the attachment",
            "example": "invoice.pdf"
          },
          "content_type": {
            "type": "string",
            "description": "Content type of the attachment",
            "example": "application/pdf"
          },
          "size": {
            "type": "number",
            "description": "Size in bytes of the attachment",
            "example": 1024
          }
        },
        "required": [
          "id",
          "filename",
          "content_type",
          "size"
        ]
      },
      "EmailDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Namespace scoped ID",
            "example": "email_123"
          },
          "from": {
            "description": "Sender of email",
            "allOf": [
              {
                "$ref": "#/components/schemas/EmailAddressDto"
              }
            ]
          },
          "to": {
            "description": "Recipients of email",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailAddressDto"
            }
          },
          "cc": {
            "description": "Carbon-copied recipients for email message",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailAddressDto"
            }
          },
          "bcc": {
            "description": "Blind carbon-copied recipients for email message",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailAddressDto"
            }
          },
          "subject": {
            "type": "string",
            "description": "Subject of email",
            "example": "Password reset"
          },
          "html": {
            "type": "string",
            "description": "Email content that was sent in HTML format"
          },
          "text": {
            "type": "string",
            "description": "Email content that was sent in plain text format"
          },
          "received_date": {
            "format": "date-time",
            "type": "string",
            "description": "The datetime that this email was received",
            "example": "2026-04-25T08:30:00.000Z"
          },
          "received_timestamp": {
            "type": "number",
            "description": "The timestamp that this email was received",
            "example": 1714857600
          },
          "expires_timestamp": {
            "type": "number",
            "description": "The timestamp when this email will be deleted",
            "example": 1714944000
          },
          "spam_score": {
            "type": "number",
            "description": "Not supported.",
            "example": null
          },
          "headers": {
            "type": "object",
            "description": "The raw email headers",
            "additionalProperties": {
              "type": "string"
            }
          },
          "attachments": {
            "description": "Attachments of the email",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailAttachmentDto"
            }
          }
        },
        "required": [
          "id",
          "from",
          "to",
          "received_date",
          "received_timestamp",
          "expires_timestamp"
        ]
      },
      "SearchInboxResponseDto": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "number",
            "description": "Total number of emails matching the query",
            "example": 1
          },
          "options": {
            "description": "Normalized query options applied to this response",
            "allOf": [
              {
                "$ref": "#/components/schemas/SearchInboxResponseOptionsDto"
              }
            ]
          },
          "data": {
            "description": "Emails returned by the inbox search",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailDto"
            }
          }
        },
        "required": [
          "total_count",
          "options",
          "data"
        ]
      },
      "GetAttachmentResponseDataDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the attachment",
            "example": "5e0c23bc-dc1c-49f3-8d92-9a0d85527019"
          },
          "filename": {
            "type": "string",
            "description": "Filename of the attachment",
            "example": "lorem-ipsum.txt"
          },
          "content_type": {
            "type": "string",
            "description": "Content type of the attachment",
            "example": "text/plain"
          },
          "size": {
            "type": "number",
            "description": "Size in bytes of the attachment",
            "example": 446
          },
          "expires_at": {
            "type": "string",
            "nullable": true,
            "description": "The datetime when this attachment will be deleted",
            "example": "2026-04-28T08:24:58.000Z"
          },
          "download_url": {
            "type": "string",
            "description": "The URL to the attachment",
            "example": "https://example.com/attachments/1777112698913_5e0c23bc-dc1c-49f3-8d92-9a0d85527019.txt"
          }
        },
        "required": [
          "id",
          "filename",
          "content_type",
          "size",
          "expires_at",
          "download_url"
        ]
      },
      "GetAttachmentResponseDto": {
        "type": "object",
        "properties": {
          "data": {
            "description": "Attachment response payload",
            "allOf": [
              {
                "$ref": "#/components/schemas/GetAttachmentResponseDataDto"
              }
            ]
          }
        },
        "required": [
          "data"
        ]
      },
      "GetSmtpSettingsResponseDataDto": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string"
          },
          "port": {
            "type": "number"
          },
          "username": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        },
        "required": [
          "host",
          "port",
          "username",
          "password"
        ]
      },
      "GetSmtpSettingsResponseDto": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/GetSmtpSettingsResponseDataDto"
          }
        },
        "required": [
          "data"
        ]
      },
      "UpdateNamespaceSettingsDto": {
        "type": "object",
        "properties": {
          "retention_time": {
            "type": "number"
          },
          "quota_limit": {
            "type": "number",
            "nullable": true
          }
        }
      },
      "UpdateNamespaceSettingsResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "namespace": {
            "type": "string"
          },
          "shared": {
            "type": "boolean"
          },
          "settings": {
            "type": "object",
            "properties": {
              "retention_time": {
                "type": "number"
              },
              "quota_limit": {
                "type": "number",
                "nullable": true
              }
            },
            "required": [
              "retention_time"
            ]
          }
        },
        "required": [
          "id",
          "namespace",
          "shared",
          "settings"
        ]
      },
      "SmsNumberResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "organisation_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "requested",
              "active",
              "disabled"
            ]
          },
          "country": {
            "type": "string"
          },
          "phone_number": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "is_test_number": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "organisation_id",
          "status",
          "country",
          "created_at",
          "updated_at"
        ]
      },
      "ListSmsNumbersResponseDto": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "number"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SmsNumberResponseDto"
            }
          }
        },
        "required": [
          "total_count",
          "data"
        ]
      },
      "SmsMessageResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "sms_phone_number_id": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "from_number": {
            "type": "string"
          },
          "to_number": {
            "type": "string"
          },
          "provider_message_id": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string"
          },
          "direction": {
            "type": "string",
            "enum": [
              "inbound",
              "outbound"
            ]
          }
        },
        "required": [
          "id",
          "sms_phone_number_id",
          "body",
          "from_number",
          "to_number",
          "created_at",
          "direction"
        ]
      },
      "SearchSmsMessagesResponseDto": {
        "type": "object",
        "properties": {
          "total_count": {
            "type": "number"
          },
          "options": {
            "type": "object"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SmsMessageResponseDto"
            }
          }
        },
        "required": [
          "total_count",
          "options",
          "data"
        ]
      },
      "SendVirtualSmsDto": {
        "type": "object",
        "properties": {
          "from_number": {
            "type": "string"
          },
          "to_number": {
            "type": "string"
          },
          "body": {
            "type": "string"
          }
        },
        "required": [
          "from_number",
          "to_number",
          "body"
        ]
      }
    }
  }
}