API reference

Mailbox

The Mailbox endpoints.

Auth: App password · 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 /api/mailbox/messages List a mailbox's messages, newest first. Authenticated with an app password granting `api` — this is how an agent reads its own inbox without an IMAP client.

List a mailbox's messages, newest first. Authenticated with an app password granting `api` — this is how an agent reads its own inbox without an IMAP client.

Response body

mailbox-messages-response.json

One page of a mailbox's messages, newest first. Read with an app password that grants `api`.

Field	Type	Notes
messages req	object[]	The page, newest first.
messages[].uid req	number	Stable per-mailbox id — also the IMAP UID, so both protocols name a message the same way.
messages[].flags req	string	Space-separated IMAP flags WITHOUT the leading backslash, e.g. `Seen Flagged`.
messages[].internaldate req	string	When the message arrived, ISO-8601.
messages[].from_addr req	string	Envelope sender.
messages[].to_addr req	string	The mailbox address this copy was delivered to.
messages[].subject req	string · null	Subject line, null when absent.
messages[].size req	number · null	Raw message size in bytes, when known.
nextBefore req	number · null	Cursor for the next page — pass as `before`. Null when this is the last page.

An actual response, recorded from the conformance suite.

response.json

{
  "messages": [
    {
      "uid": 42,
      "flags": "Seen",
      "internaldate": "2026-08-03T09:14:22.000Z",
      "from_addr": "customer@example.com",
      "to_addr": "support-billing@acme.dev",
      "subject": "Invoice question",
      "size": 4821
    }
  ],
  "nextBefore": null
}

mailbox-messages-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/mailbox-messages-response.json",
  "title": "Mailbox message page",
  "description": "One page of a mailbox's messages, newest first. Read with an app password that grants `api`.",
  "type": "object",
  "required": [
    "messages",
    "nextBefore"
  ],
  "additionalProperties": false,
  "properties": {
    "messages": {
      "type": "array",
      "description": "The page, newest first.",
      "items": {
        "type": "object",
        "required": [
          "uid",
          "flags",
          "internaldate",
          "from_addr",
          "to_addr",
          "subject",
          "size"
        ],
        "additionalProperties": false,
        "properties": {
          "uid": {
            "type": "number",
            "description": "Stable per-mailbox id — also the IMAP UID, so both protocols name a message the same way.",
            "examples": [
              42
            ]
          },
          "flags": {
            "type": "string",
            "description": "Space-separated IMAP flags WITHOUT the leading backslash, e.g. `Seen Flagged`.",
            "examples": [
              "Seen"
            ]
          },
          "internaldate": {
            "type": "string",
            "description": "When the message arrived, ISO-8601.",
            "examples": [
              "2026-08-03T09:14:22.000Z"
            ]
          },
          "from_addr": {
            "type": "string",
            "description": "Envelope sender.",
            "examples": [
              "customer@example.com"
            ]
          },
          "to_addr": {
            "type": "string",
            "description": "The mailbox address this copy was delivered to.",
            "examples": [
              "support-billing@acme.dev"
            ]
          },
          "subject": {
            "type": [
              "string",
              "null"
            ],
            "description": "Subject line, null when absent.",
            "examples": [
              "Invoice question"
            ]
          },
          "size": {
            "type": [
              "number",
              "null"
            ],
            "description": "Raw message size in bytes, when known.",
            "examples": [
              4821
            ]
          }
        }
      }
    },
    "nextBefore": {
      "type": [
        "number",
        "null"
      ],
      "description": "Cursor for the next page — pass as `before`. Null when this is the last page.",
      "examples": [
        null
      ]
    }
  }
}

GET /api/mailbox/messages/:uid/raw Fetch one message's raw RFC822 bytes from a mailbox. Same app password auth as the list.

Fetch one message's raw RFC822 bytes from a mailbox. Same app password auth as the list.

No request body. The response is JSON; its exact shape isn't schema'd yet — tell us if you need it pinned down.

POST /api/mailbox/messages/:uid/flags Replace a message's IMAP flags (e.g. mark it `Seen`). Flags set here are the same ones an IMAP client sees.

Replace a message's IMAP flags (e.g. mark it `Seen`). Flags set here are the same ones an IMAP client sees.

Request body

set-mailbox-flags-request.json

Field	Type	Notes
flags req	string	The complete flag set to store, space-separated and WITHOUT leading backslashes (e.g. `Seen Flagged`). This replaces the message's flags rather than merging.

set-mailbox-flags-request.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/set-mailbox-flags-request.json",
  "title": "Set mailbox message flags request body",
  "type": "object",
  "required": [
    "flags"
  ],
  "additionalProperties": false,
  "properties": {
    "flags": {
      "type": "string",
      "description": "The complete flag set to store, space-separated and WITHOUT leading backslashes (e.g. `Seen Flagged`). This replaces the message's flags rather than merging.",
      "examples": [
        "Seen"
      ]
    }
  }
}

Response body

ok-response.json

The uniform acknowledgement for deletes and other actions with nothing else to report.

Field	Type	Notes
ok req	true	Always true — a non-2xx error body is returned otherwise.

ok-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/ok-response.json",
  "title": "OK",
  "description": "The uniform acknowledgement for deletes and other actions with nothing else to report.",
  "type": "object",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true,
      "description": "Always true — a non-2xx error body is returned otherwise."
    }
  }
}