API reference

Schemas

The published JSON Schemas themselves, served over HTTP for any validator to resolve.

Auth: Public · Base URL: https://api.mailkite.dev

Endpoints

Each row expands to its request and response schema. The address bar follows along, so any endpoint can be linked to directly.

GET /v1/schemas List every published JSON Schema with the URL it is served from.

List every published JSON Schema with the URL it is served from.

Response body

list-schemas-response.json

GET /v1/schemas — every published JSON Schema with the URL it's served from.

Field	Type	Notes
version req	string	The contract version these schemas belong to.
schemas req	object[]	All published schemas, sorted by name.
schemas[].name req	string	Schema id — the filename stem api.json references.
schemas[].title req	string	Human title from the schema.
schemas[].description	string	The schema's description, when it has one.
schemas[].url req	string	Absolute URL the schema is served from.

An actual response, recorded from the conformance suite.

response.json

{
  "version": "0.16.0",
  "schemas": [
    {
      "name": "email-received-event",
      "title": "email.received webhook event",
      "url": "https://api.mailkite.dev/v1/schemas/email-received-event.json"
    },
    {
      "name": "send-request",
      "title": "Send request body",
      "url": "https://api.mailkite.dev/v1/schemas/send-request.json"
    }
  ]
}

list-schemas-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/list-schemas-response.json",
  "title": "List schemas response",
  "description": "GET /v1/schemas — every published JSON Schema with the URL it's served from.",
  "type": "object",
  "required": [
    "version",
    "schemas"
  ],
  "properties": {
    "version": {
      "type": "string",
      "description": "The contract version these schemas belong to.",
      "examples": [
        "0.16.0"
      ]
    },
    "schemas": {
      "type": "array",
      "description": "All published schemas, sorted by name.",
      "items": {
        "type": "object",
        "required": [
          "name",
          "title",
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Schema id — the filename stem api.json references.",
            "examples": [
              "send-request"
            ]
          },
          "title": {
            "type": "string",
            "description": "Human title from the schema.",
            "examples": [
              "Send request body"
            ]
          },
          "description": {
            "type": "string",
            "description": "The schema's description, when it has one."
          },
          "url": {
            "type": "string",
            "description": "Absolute URL the schema is served from.",
            "examples": [
              "https://api.mailkite.dev/v1/schemas/send-request.json"
            ]
          }
        }
      }
    }
  }
}

GET /v1/schemas/:name Fetch one schema as application/schema+json, with an absolute $id a validator can resolve and cache.

Fetch one schema as application/schema+json, with an absolute $id a validator can resolve and cache.

Response body

schema-document.json

GET /v1/schemas/:name — the named JSON Schema itself, served as application/schema+json with an absolute $id a validator can resolve and cache.

No fields to table — switch to JSON for the schema itself.

An actual response, recorded from the conformance suite.

response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/send-response.json",
  "title": "Send response body",
  "type": "object",
  "required": [
    "id",
    "status"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  }
}

schema-document.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/schema-document.json",
  "title": "JSON Schema document",
  "description": "GET /v1/schemas/:name — the named JSON Schema itself, served as application/schema+json with an absolute $id a validator can resolve and cache.",
  "type": "object"
}

Fetching schemas

Every request and response body in this reference is described by a JSON Schema (draft-07) — the same schemas our SDKs and MCP server validate against, so they can't drift from what the API enforces:

fetch the schemas

# every schema, with its URL
curl https://api.mailkite.dev/v1/schemas

# one schema — point a validator straight at it
curl https://api.mailkite.dev/v1/schemas/send-request.json
curl https://api.mailkite.dev/v1/schemas/email-received-event.json

Contract version 0.19.0. Schemas are served as application/schema+json with an absolute $id, and are additive — we add fields, we don't remove or repurpose them.