{
  "openapi": "3.0.3",
  "info": {
    "title": "milbox Public API",
    "version": "1.6.0",
    "x-panel-version": "2.2.0",
    "x-api-status": "stable",
    "x-api-compat": [
      "1.0.0",
      "1.1.0",
      "1.2.0",
      "1.3.0",
      "1.4.0",
      "1.5.0",
      "1.6.0"
    ],
    "description": "Domain inventory, temporary addresses, and inbox for products and resellers. One key per account, bound to an IP allowlist and scoped to the addresses it created.",
    "x-human-docs": "https://milbox.dev/developers/api",
    "x-llms-docs": "https://milbox.dev/llms.txt"
  },
  "servers": [
    {
      "url": "https://milbox.dev/api/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "SuccessEnvelope": {
        "type": "object",
        "required": [
          "ok",
          "data",
          "meta"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "description": "Endpoint payload. Shape varies per operation; see the operation example."
          },
          "meta": {
            "$ref": "#/components/schemas/ResponseMeta"
          }
        }
      },
      "ResponseMeta": {
        "type": "object",
        "required": [
          "request_id",
          "timestamp"
        ],
        "properties": {
          "request_id": {
            "type": "string",
            "example": "e7c87866405f3959"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "total": {
            "type": "integer",
            "description": "Present on paginated lists."
          },
          "page": {
            "type": "integer"
          },
          "per_page": {
            "type": "integer"
          },
          "pages": {
            "type": "integer"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "description": "Keyset cursor for the next page. Pass it back as the cursor query parameter."
          },
          "sort": {
            "type": "string",
            "nullable": true
          },
          "quota": {
            "$ref": "#/components/schemas/Quota"
          }
        }
      },
      "Quota": {
        "type": "object",
        "properties": {
          "limit": {
            "type": "integer",
            "nullable": true
          },
          "used": {
            "type": "integer"
          },
          "remaining": {
            "type": "integer",
            "nullable": true
          },
          "unlimited": {
            "type": "boolean"
          }
        }
      },
      "Domain": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Public domain id."
          },
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "platform_pool",
              "custom"
            ]
          },
          "premium": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending_verification",
              "verified",
              "active",
              "suspended"
            ]
          },
          "mail_enabled": {
            "type": "boolean"
          },
          "mail_cap_hours": {
            "type": "integer",
            "nullable": true
          },
          "verified_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "mx_verified_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "mx_target": {
            "type": "string",
            "nullable": true,
            "description": "Resolved MX host for this domain: the Cloudflare trio for mail_mode=cloudflare, the configured receiver for mx_txt."
          },
          "mail_mode": {
            "type": "string",
            "enum": [
              "mx_txt",
              "cloudflare"
            ],
            "description": "mx_txt: MX + TXT point at the milbox receiver. cloudflare: Cloudflare Email Routing owns the MX and a Worker forwards into the ingest API."
          },
          "moderation": {
            "type": "object",
            "description": "Operator moderation state. blocked=true means inbound mail is rejected with 550 and the row is hidden from the public catalog.",
            "properties": {
              "blocked": {
                "type": "boolean"
              },
              "reason": {
                "type": "string",
                "enum": [
                  "none",
                  "suspend",
                  "ban",
                  "spam",
                  "fraud",
                  "abuse",
                  "phishing"
                ]
              },
              "note": {
                "type": "string",
                "nullable": true,
                "description": "Operator-supplied explanation, also sent to the owner as a notification."
              },
              "blocked_at": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "restores_to": {
                "type": "string",
                "nullable": true,
                "description": "Status restored when the block is lifted."
              }
            },
            "required": [
              "blocked",
              "reason"
            ]
          },
          "added_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Verification": {
        "type": "object",
        "properties": {
          "host": {
            "type": "string",
            "example": "_milbox-challenge.example.com"
          },
          "value_prefix": {
            "type": "string",
            "example": "milbox-verify="
          },
          "token": {
            "type": "string",
            "nullable": true
          },
          "value": {
            "type": "string",
            "nullable": true
          },
          "token_hint": {
            "type": "string",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "pending": {
            "type": "boolean"
          }
        }
      },
      "Address": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "api_key_id": {
            "type": "integer"
          },
          "domain_id": {
            "type": "integer"
          },
          "local_part": {
            "type": "string"
          },
          "address": {
            "type": "string",
            "format": "email"
          },
          "label": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "disabled",
              "deleted"
            ]
          },
          "password_protected": {
            "type": "boolean"
          },
          "message_count": {
            "type": "integer"
          },
          "last_message_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "purge_after": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "alias_group": {
            "type": "string",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Party": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "nullable": true
          },
          "address": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "MessageSummary": {
        "type": "object",
        "required": [
          "id",
          "address",
          "from",
          "subject",
          "received_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Public message id. Numeric ids are accepted on every read route."
          },
          "address": {
            "type": "string",
            "format": "email",
            "description": "The mailbox that received this message."
          },
          "from": {
            "type": "string",
            "nullable": true,
            "format": "email",
            "description": "Decoded From address exactly as the sender wrote it."
          },
          "from_name": {
            "type": "string",
            "nullable": true,
            "description": "Decoded From display name."
          },
          "subject": {
            "type": "string",
            "nullable": true
          },
          "preview": {
            "type": "string",
            "description": "First 180 characters of the plain text body, HTML tags stripped."
          },
          "otp": {
            "type": "string",
            "nullable": true,
            "description": "One-time code pulled out of the subject or body, or null when the message carries none. Digits only, 4-8 characters. URLs are stripped before matching and a bare year is never treated as a code, so footers like \"(c) 2026\" do not leak into this field. Present on every list row and on GET /messages/{id}."
          },
          "size_bytes": {
            "type": "integer"
          },
          "attachment_count": {
            "type": "integer"
          },
          "has_html": {
            "type": "boolean"
          },
          "has_attachments": {
            "type": "boolean"
          },
          "spam_status": {
            "type": "string",
            "enum": [
              "clean",
              "spam",
              "unknown"
            ]
          },
          "priority": {
            "type": "string",
            "nullable": true,
            "enum": [
              "high",
              "normal",
              "low",
              null
            ]
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "read_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Null while unread. Written the first time GET /messages/{id} reads it."
          },
          "starred_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "to": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Party"
            }
          },
          "cc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Party"
            }
          }
        }
      },
      "MessageDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MessageSummary"
          },
          {
            "type": "object",
            "properties": {
              "reply_to": {
                "$ref": "#/components/schemas/Party"
              },
              "message_id": {
                "type": "string",
                "nullable": true,
                "description": "Raw Message-ID header, angle brackets included."
              },
              "in_reply_to": {
                "type": "string",
                "nullable": true
              },
              "references": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "headers_date": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "Parsed Date header as ISO-8601. Use this for sorting, not received_at."
              },
              "headers_date_valid": {
                "type": "boolean",
                "description": "True when a Date header was present and parseable."
              },
              "received_chain": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Raw Received header lines, outermost hop first."
              },
              "dkim_signatures": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Raw DKIM-Signature header lines."
              },
              "authentication_results": {
                "type": "string",
                "nullable": true,
                "description": "Authentication-Results header lines joined with \"; \"."
              },
              "raw_available": {
                "type": "boolean",
                "description": "True when GET /messages/{id}/download will return the original RFC 822 bytes."
              },
              "text": {
                "type": "string",
                "nullable": true,
                "description": "Decoded text/plain body."
              },
              "html": {
                "type": "string",
                "nullable": true,
                "description": "Decoded text/html body."
              },
              "attachments": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "filename": {
                      "type": "string"
                    },
                    "content_type": {
                      "type": "string"
                    },
                    "size": {
                      "type": "integer"
                    }
                  }
                }
              },
              "attachments_detail": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "filename": {
                      "type": "string"
                    },
                    "content_type": {
                      "type": "string"
                    },
                    "size": {
                      "type": "integer"
                    },
                    "content_id": {
                      "type": "string",
                      "nullable": true
                    },
                    "disposition": {
                      "type": "string"
                    },
                    "inline": {
                      "type": "boolean"
                    },
                    "checksum_sha256": {
                      "type": "string",
                      "description": "Full sha256 hex. The download route also accepts a unique prefix."
                    },
                    "related": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "delivery_ms": {
                "type": "integer",
                "nullable": true,
                "description": "Milliseconds between the sender Date header and ingest."
              }
            }
          }
        ]
      },
      "Counters": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "unread": {
            "type": "integer"
          },
          "read": {
            "type": "integer"
          },
          "deleted": {
            "type": "integer"
          },
          "attachments": {
            "type": "integer"
          },
          "starred": {
            "type": "integer"
          }
        }
      },
      "Webhook": {
        "type": "object",
        "properties": {
          "public_id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "description": {
            "type": "string",
            "nullable": true
          },
          "events": {
            "type": "string",
            "description": "Comma separated event names."
          },
          "secret": {
            "type": "string",
            "description": "HMAC-SHA256 signing secret."
          },
          "active": {
            "type": "boolean"
          },
          "failure_count": {
            "type": "integer"
          },
          "last_status": {
            "type": "integer",
            "nullable": true
          },
          "last_error": {
            "type": "string",
            "nullable": true
          },
          "last_delivery_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "deliveries": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Present on the single-resource read."
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string"
          },
          "key_prefix": {
            "type": "string"
          },
          "premium_access": {
            "type": "boolean"
          },
          "rate_limit_per_minute": {
            "type": "integer",
            "description": "0 means no budget."
          },
          "ip_allowlist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "last_used_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "request_count": {
            "type": "integer"
          },
          "usage": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "last_24h": {
                "type": "integer"
              },
              "denied_24h": {
                "type": "integer"
              }
            }
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "ok",
          "error",
          "meta"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "ip_not_allowed"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "description": "Structured context when applicable (allowlist, retry_after, validation fields)."
              },
              "links": {
                "type": "array",
                "description": "Machine-followable links. docs points at the relevant reference section.",
                "items": {
                  "type": "object",
                  "properties": {
                    "rel": {
                      "type": "string",
                      "example": "docs"
                    },
                    "href": {
                      "type": "string",
                      "example": "/developers/api#sec-allowlist"
                    },
                    "method": {
                      "type": "string",
                      "example": "GET"
                    }
                  }
                }
              }
            }
          },
          "meta": {
            "type": "object",
            "required": [
              "request_id",
              "timestamp"
            ],
            "properties": {
              "request_id": {
                "type": "string",
                "description": "Unique identifier for this request. Echo it in support inquiries. Also returned as the x-request-id response header."
              },
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "description": "Server time (ISO 8601) at response construction."
              },
              "docs_url": {
                "type": "string",
                "description": "Present on error responses. Canonical reference entry point."
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/account": {
      "get": {
        "operationId": "ep-account",
        "tags": [
          "Account"
        ],
        "summary": "Describe the key itself: label, premium scope, allowlist, budget, and usage counters.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Account\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "label": "reseller-alpha",
                    "key_prefix": "mml_9c1f4a2b",
                    "premium_access": true,
                    "rate_limit_per_minute": 120,
                    "ip_allowlist": [
                      "203.0.113.0/24",
                      "198.51.100.7/32"
                    ],
                    "ip_unrestricted": false,
                    "expires_at": null,
                    "created_at": "2026-10-20T19:43:09.000Z",
                    "last_used_at": "2026-10-20T20:12:55.000Z",
                    "request_count": 4182,
                    "usage": {
                      "total": 4182,
                      "last_24h": 640,
                      "denied_24h": 3
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key: Key hash not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "403": {
            "description": "ip_not_allowed: Caller IP outside the allowlist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl https://milbox.dev/api/v1/account \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/account/quota": {
      "get": {
        "operationId": "ep-account-quota",
        "tags": [
          "Account"
        ],
        "summary": "Address quota, message totals, retention, and the key profile in one call.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "quota": {
                      "domain_limit": 5,
                      "domain_used": 2,
                      "address_limit": 50,
                      "address_used": 12,
                      "message_limit": 1000,
                      "message_used": 42,
                      "unlimited": false,
                      "premium": false
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key: Key hash not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl https://milbox.dev/api/v1/account/quota \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/account/usage": {
      "get": {
        "operationId": "ep-account-usage",
        "tags": [
          "Account"
        ],
        "summary": "Everything a client needs to self-throttle: scopes, request counters for 24h and 7d, the twenty busiest endpoints with their error counts, address quota, message counters, and the effective retention window.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "key": {
                      "label": "reseller-alpha",
                      "key_prefix": "mml_9c1f4a2b",
                      "scopes": [
                        "addresses:read",
                        "inbox:read"
                      ],
                      "premium_access": false,
                      "rate_limit_per_minute": 120,
                      "expires_at": null
                    },
                    "requests": {
                      "total": 4182,
                      "last_24h": 640,
                      "last_7d": 3100,
                      "denied_24h": 3
                    },
                    "endpoints": [
                      {
                        "path": "/api/v1/inbox",
                        "hits": 2200,
                        "errors": 12
                      }
                    ],
                    "addresses": {
                      "limit": 50,
                      "used": 12,
                      "remaining": 38,
                      "unlimited": false
                    },
                    "messages": {
                      "total": 42,
                      "unread": 7,
                      "read": 35,
                      "deleted": 3,
                      "attachments": 5,
                      "starred": 2,
                      "retention_hours": 48
                    },
                    "webhooks": 2
                  },
                  "meta": {
                    "request_id": "e7c87866405f3959",
                    "timestamp": "2026-10-20T19:51:35.267Z",
                    "capabilities": {
                      "retention_hours": 48,
                      "max_message_bytes": 10485760
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key: Key hash not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl https://milbox.dev/api/v1/account/usage \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/meta": {
      "get": {
        "operationId": "ep-account-meta",
        "tags": [
          "Account"
        ],
        "summary": "Machine-readable capabilities document: api version, operation count per group, the full error-code list, request and response headers, pagination style, and the webhook event catalogue. Useful for client bootstrapping without fetching openapi.json.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "api_version": "1.5.0",
                    "operations": 33,
                    "groups": [
                      {
                        "id": "group-inbox",
                        "name": "Inbox",
                        "count": 12
                      }
                    ],
                    "error_codes": [
                      "missing_api_key",
                      "insufficient_scope",
                      "rate_limited"
                    ],
                    "pagination": {
                      "style": "offset + cursor",
                      "cursor_field": "next_cursor",
                      "cursor_param": "cursor"
                    },
                    "webhooks": {
                      "events": [
                        "message.received",
                        "address.created",
                        "address.expired",
                        "message.deleted"
                      ],
                      "signature_header": "x-milbox-signature",
                      "algorithm": "hmac-sha256(timestamp.body)"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/meta\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/keys": {
      "get": {
        "operationId": "ep-keys-self",
        "tags": [
          "Account"
        ],
        "summary": "Introspect the presented key: scopes, premium flag, budgets, quotas, effective retention, status, and the lifetime request counter. Read-only by design, keys are provisioned from the panel.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Account\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Account"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "id": 1,
                    "label": "reseller-alpha",
                    "key_prefix": "mml_9c1f4a2b",
                    "scopes": [
                      "*"
                    ],
                    "premium_access": false,
                    "rate_limit_per_minute": 120,
                    "requests_total": 4182,
                    "status": "active",
                    "expires_at": null,
                    "last_used_at": "2026-10-20T19:51:35.000Z",
                    "created_at": "2026-09-01T08:00:00.000Z"
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed: Keys cannot be created, patched or deleted through the API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/keys\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/keys/rotate": {
      "post": {
        "operationId": "ep-keys-rotate",
        "tags": [
          "Account"
        ],
        "summary": "Roll the presented key: a fresh secret is generated, the old one stops working on the next request. Shown once, in full, in this response only.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "id": 7,
                    "label": "reseller-alpha",
                    "key_prefix": "mml_1a2b3c4d",
                    "secret": "mml_<64 hex>",
                    "status": "active",
                    "rotated_at": "2026-10-22T09:14:02.000Z",
                    "warning": "The previous secret stops working immediately. Persist this value now, it is shown once."
                  }
                }
              }
            }
          },
          "403": {
            "description": "insufficient_scope: Requires the account:write scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "conflict: Only an active key can be rotated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST https://milbox.dev/api/v1/keys/rotate \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/plans": {
      "get": {
        "operationId": "ep-plans",
        "tags": [
          "Account"
        ],
        "summary": "The plan the key resolves to, the hard limits that plan enforces, and the whole assignable catalog so a client can render an upgrade path without guessing.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "current": {
                      "plan": "premium",
                      "display_name": "Premium",
                      "tagline": "Custom domains, Cloudflare routing, real retention.",
                      "source": "inherited",
                      "expired": false,
                      "limits": {
                        "domains": 10,
                        "addresses": 500,
                        "api_keys": 5,
                        "mail_retention_hours": 168,
                        "rate_limit_per_minute": 120
                      },
                      "features": {
                        "custom_domains": true,
                        "premium_domains": true,
                        "cloudflare": true,
                        "catch_all": true
                      }
                    },
                    "key_limits": {
                      "address_quota": 50,
                      "addresses_used": 12,
                      "addresses_remaining": 38,
                      "message_retention_hours": 72,
                      "rate_limit_per_minute": 120,
                      "premium_access": true
                    },
                    "catalog": [
                      {
                        "plan": "free",
                        "display_name": "Free",
                        "tagline": "Read the platform, own nothing.",
                        "limits": {
                          "domains": 0,
                          "addresses": 0,
                          "api_keys": 1,
                          "mail_retention_hours": 24,
                          "rate_limit_per_minute": 30
                        },
                        "features": {
                          "custom_domains": false,
                          "premium_domains": false,
                          "cloudflare": false,
                          "catch_all": false
                        }
                      }
                    ]
                  },
                  "meta": {
                    "plan_registry": "read-only"
                  }
                }
              }
            }
          },
          "401": {
            "description": "invalid_api_key: Key hash not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/plans\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/account/requests": {
      "get": {
        "operationId": "ep-account-requests",
        "tags": [
          "Account"
        ],
        "summary": "Per-request audit trail for this key: method, path, status, outcome, IP, and the request id you also receive in the x-request-id header. Filter it to isolate every denied or throttled call.",
        "description": "What this key is allowed to do. Call it once on boot to fail fast on a bad or moved IP.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"type\":\"object\"}}\n```",
        "parameters": [
          {
            "name": "outcome",
            "in": "query",
            "required": false,
            "description": "ok | denied_key | denied_ip | denied_expired | rate_limited | maintenance_mode",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Exact HTTP status to match, e.g. 404.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 lower bound on created_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Default 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Default 50. Max 200.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "requests": [
                      {
                        "request_id": "b41f9c7d2e8a1065",
                        "method": "GET",
                        "path": "/api/v1/inbox",
                        "status": 429,
                        "outcome": "rate_limited",
                        "ip": "203.0.113.9",
                        "created_at": "2026-10-22T08:59:11.000Z"
                      }
                    ],
                    "filters": {
                      "outcome": "rate_limited",
                      "status": null,
                      "since": null
                    }
                  },
                  "meta": {
                    "total": 1,
                    "page": 1,
                    "per_page": 20,
                    "pages": 1
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/account/requests?outcome=rate_limited&per_page=20\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/addresses": {
      "get": {
        "operationId": "ep-addresses-list",
        "tags": [
          "Addresses"
        ],
        "summary": "List every address this key owns, newest first, with the quota snapshot in meta.",
        "description": "Temporary addresses on an active domain. Each key owns the addresses it creates; quota is per key.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/Address\"}}\n```",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "active | disabled",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Restrict to one domain name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Substring match on the full address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Default 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Default 50. Max 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Address"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": [
                    {
                      "id": "k3n8x2p9q1ab",
                      "api_key_id": 4,
                      "domain_id": 12,
                      "local_part": "swift.otter7f",
                      "address": "swift.otter7f@{PLATFORM_DOMAIN}",
                      "label": null,
                      "status": "active",
                      "password_protected": false,
                      "message_count": 3,
                      "last_message_at": "2026-10-20T18:04:11.000Z",
                      "expires_at": "2026-10-27T17:40:00.000Z",
                      "created_at": "2026-10-20T17:40:00.000Z"
                    }
                  ],
                  "meta": {
                    "total": 1,
                    "page": 1,
                    "per_page": 50,
                    "pages": 1,
                    "quota": {
                      "limit": 10,
                      "used": 1,
                      "remaining": 9,
                      "unlimited": false
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: status outside active or disabled.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/addresses\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "post": {
        "operationId": "ep-addresses-create",
        "tags": [
          "Addresses"
        ],
        "summary": "Create an address. Omit local_part for a random one. Domain must be active with mail enabled.",
        "description": "Temporary addresses on an active domain. Each key owns the addresses it creates; quota is per key.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "address": {
                      "id": "k3n8x2p9q1ab",
                      "address": "signup@{PLATFORM_DOMAIN}",
                      "status": "active",
                      "expires_at": "2026-10-20T20:10:00.000Z",
                      "purge_after": null,
                      "password_protected": true,
                      "alias_group": "9f2c..."
                    },
                    "password": "s3cret",
                    "quota": {
                      "limit": 10,
                      "used": 1,
                      "remaining": 9,
                      "unlimited": false
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found: Domain is not registered.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "address_exists: That exact address is already taken.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "ttl_exceeds_domain: ttl_minutes exceeds the domain mail_cap_hours.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "plan_address_quota_exceeded: The owning account is at its plan mailbox ceiling.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "local_part": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "ttl_minutes": {
                    "type": "integer"
                  },
                  "password": {
                    "type": "string"
                  },
                  "alias_of": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST https://milbox.dev/api/v1/addresses \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"domain\":\"milbox.dev\",\"local_part\":\"signup\",\"ttl_minutes\":30,\"password\":\"s3cret\"}'"
          }
        ]
      }
    },
    "/addresses/{id}": {
      "get": {
        "operationId": "ep-addresses-get",
        "tags": [
          "Addresses"
        ],
        "summary": "One address, its alias group, and its newest messages. Accepts the public id or the full email address.",
        "description": "Temporary addresses on an active domain. Each key owns the addresses it creates; quota is per key.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Required when the address carries a password (wrong or missing password returns 404).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "address": {
                      "id": "k3n8x2p9q1ab",
                      "address": "signup@{PLATFORM_DOMAIN}",
                      "status": "active"
                    },
                    "aliases": [
                      {
                        "id": "k3n8x2p9q1ab",
                        "address": "signup@{PLATFORM_DOMAIN}"
                      }
                    ],
                    "messages": {
                      "rows": [],
                      "total": 0,
                      "per_page": 25
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Address not owned, expired, or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/addresses/signup@milbox.dev?password=s3cret\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "delete": {
        "operationId": "ep-addresses-delete",
        "tags": [
          "Addresses"
        ],
        "summary": "Soft-delete the address and hide its messages from the inbox. purge_after is stamped so the row survives the five minute grace window before the hard delete.",
        "description": "Temporary addresses on an active domain. Each key owns the addresses it creates; quota is per key.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "deleted": true,
                    "address": "signup@example.com",
                    "purge_after": "2026-10-21T18:07:44.000Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Address not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X DELETE \"https://milbox.dev/api/v1/addresses/8f2c1d9a4b6e\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "patch": {
        "operationId": "ep-addresses-patch",
        "tags": [
          "Addresses"
        ],
        "summary": "Relabel, disable, re-enable, extend the lifetime, or rotate the password of an address without changing the address string. Extending ttl_minutes also moves purge_after.",
        "description": "Temporary addresses on an active domain. Each key owns the addresses it creates; quota is per key.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Address\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Address"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "id": "8f2c1d9a4b6e",
                    "address": "signup@example.com",
                    "label": "prod-signup",
                    "status": "active",
                    "expires_at": "2026-10-22T18:02:44.000Z",
                    "purge_after": "2026-10-22T18:07:44.000Z",
                    "message_count": 42
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Address not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "ttl_exceeds_domain: ttl_minutes exceeds the domain lifetime cap.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string"
                  },
                  "ttl_minutes": {
                    "type": "integer"
                  },
                  "password": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X PATCH https://milbox.dev/api/v1/addresses/signup-a1b2 \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"label\":\"prod-signup\",\"ttl_minutes\":1440}'"
          }
        ]
      }
    },
    "/addresses/{id}/messages": {
      "get": {
        "operationId": "ep-addresses-messages",
        "tags": [
          "Addresses"
        ],
        "summary": "The mailbox subresource: every message on one address, with the full /inbox filter grammar still available. Use it when the address is the scope and you do not want to repeat the address on every call.",
        "description": "Temporary addresses on an active domain. Each key owns the addresses it creates; quota is per key.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/MessageSummary\"}}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public id, numeric id, or the full address string.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Required when the address carries a password.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "unread",
            "in": "query",
            "required": false,
            "description": "Only unread messages.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "required": false,
            "description": "true for starred only, false to exclude them.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Full-text query on subject and body.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "newest | oldest | largest",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Default 50. Max 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageSummary"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "address": "alpha@milbox.dev",
                    "messages": [
                      {
                        "id": "8f2c1d9a4b6e",
                        "address": "alpha@milbox.dev",
                        "from": "billing@vendor.io",
                        "from_name": "Vendor Billing",
                        "subject": "Invoice 2291 overdue",
                        "preview": "Invoice 2291 is 14 days overdue.",
                        "otp": null,
                        "size_bytes": 24811,
                        "attachment_count": 1,
                        "has_html": true,
                        "has_attachments": true,
                        "spam_status": "clean",
                        "priority": null,
                        "received_at": "2026-10-21T11:02:44.000Z",
                        "read_at": null,
                        "starred_at": null,
                        "expires_at": "2026-10-22T11:02:44.000Z",
                        "to": [
                          {
                            "name": null,
                            "address": "alpha@milbox.dev"
                          }
                        ],
                        "cc": []
                      }
                    ],
                    "filters": {
                      "page": 1,
                      "per_page": 50,
                      "sort": "newest"
                    }
                  },
                  "meta": {
                    "total": 1,
                    "page": 1,
                    "per_page": 50,
                    "pages": 1,
                    "next_cursor": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Address not owned by this key or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/addresses/alpha@milbox.dev/messages?unread=true&sort=newest\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/inbox": {
      "get": {
        "operationId": "ep-inbox-list",
        "tags": [
          "Inbox"
        ],
        "summary": "Newest messages first. Filter by address, sender, subject, To recipient, sender display name, exact Message-ID, header Date window, size range, priority, attachments, spam state, unread, or poll with since_id.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/MessageSummary\"}}\n```",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "Full email address to scope the list. Password-protected addresses return 404 unless the matching password is supplied.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Address password. Required when the scoped address carries one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since_id",
            "in": "query",
            "required": false,
            "description": "Incremental poll cursor: the message id returned by a previous call (public id or numeric). Only rows newer than it are returned.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Keyset pagination cursor: the meta.next_cursor value from a previous page. Stable while new mail arrives, unlike page offsets.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "unread",
            "in": "query",
            "required": false,
            "description": "true returns only unread messages.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Substring search across subject, from name, from address, and the decoded text body.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Exact From address as sent by the sender (RFC 5322 header, decoded, lowercased).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from_name",
            "in": "query",
            "required": false,
            "description": "Substring match on the decoded From display name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": false,
            "description": "Substring match on the decoded Subject.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Match a full recipient address inside the To header (exact, case-insensitive).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "message_id",
            "in": "query",
            "required": false,
            "description": "Exact Message-ID header value, angle brackets included.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO-8601 lower bound on the Date header written by the sender (not arrival time).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "ISO-8601 upper bound on the sender Date header.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_size",
            "in": "query",
            "required": false,
            "description": "Minimum message size in bytes.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "max_size",
            "in": "query",
            "required": false,
            "description": "Maximum message size in bytes.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "priority",
            "in": "query",
            "required": false,
            "description": "high | normal | low (from X-Priority / Importance / Priority headers).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_attachments",
            "in": "query",
            "required": false,
            "description": "true returns only messages with attachments.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "required": false,
            "description": "true for starred messages only, false to exclude them. Anything else is rejected with 422.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "ids",
            "in": "query",
            "required": false,
            "description": "Comma separated message identifiers, public or numeric. Max 200 per call.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "spam",
            "in": "query",
            "required": false,
            "description": "clean | spam | unknown",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "newest (default) | oldest | largest",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Include soft-deleted messages.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Default 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Default 25. Max 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageSummary"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": [
                    {
                      "id": "8f2c1d9a4b6e",
                      "address": "swift.otter7f@{PLATFORM_DOMAIN}",
                      "from": "noreply@github.com",
                      "from_name": "GitHub",
                      "subject": "Your verification code is 481920",
                      "preview": "Use 481920 to finish signing in. It expires in 10 minutes.",
                      "otp": "481920",
                      "size_bytes": 18422,
                      "attachment_count": 0,
                      "has_html": true,
                      "has_attachments": false,
                      "spam_status": "clean",
                      "priority": null,
                      "received_at": "2026-10-20T18:02:44.000Z",
                      "read_at": null,
                      "starred_at": null,
                      "expires_at": "2026-10-21T18:02:44.000Z",
                      "to": [
                        {
                          "name": null,
                          "address": "swift.otter7f@{PLATFORM_DOMAIN}"
                        }
                      ],
                      "cc": []
                    }
                  ],
                  "meta": {
                    "total": 1,
                    "page": 1,
                    "per_page": 25,
                    "pages": 1
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/inbox?address=swift.otter7f@milbox.dev&unread=true\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/inbox/read": {
      "post": {
        "operationId": "ep-inbox-read",
        "tags": [
          "Inbox"
        ],
        "summary": "Bulk mark messages as read. Every inbox filter is honoured, plus an optional ids array to target specific messages. Send no body to act on the whole filtered scope. Returns the affected row count and the refreshed counters.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "Scope to one owned address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Address password. Required when the scoped address carries one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "unread",
            "in": "query",
            "required": false,
            "description": "true limits the action to currently unread messages.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": false,
            "description": "Also touch soft-deleted messages.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Substring search across subject, from name, and from address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Exact From address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "subject",
            "in": "query",
            "required": false,
            "description": "Substring match on the decoded Subject.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_attachments",
            "in": "query",
            "required": false,
            "description": "Limit to messages carrying attachments.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "spam",
            "in": "query",
            "required": false,
            "description": "clean | spam | unknown",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "seen": true,
                    "marked": 2,
                    "scoped_ids": 2,
                    "counters": {
                      "total": 42,
                      "unread": 5,
                      "read": 37,
                      "deleted": 3,
                      "attachments": 11
                    }
                  },
                  "meta": {
                    "request_id": "e7c87866405f3959",
                    "timestamp": "2026-10-20T19:51:35.267Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Address not owned by this key or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: ids is not an array of message identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "423": {
            "description": "domain_blocked: The owning domain is suspended or blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/inbox/read\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"ids\":[\"8f2c1d9a4b6e\",\"1c4b0e77aa02\"]}'"
          }
        ]
      }
    },
    "/inbox/unread": {
      "post": {
        "operationId": "ep-inbox-unread",
        "tags": [
          "Inbox"
        ],
        "summary": "Bulk mark messages as unread. Identical contract to /inbox/read: same filters, same optional ids array, same response shape.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "Scope to one owned address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Address password. Required when the scoped address carries one.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "seen": false,
                    "marked": 1,
                    "scoped_ids": 1,
                    "counters": {
                      "total": 42,
                      "unread": 6,
                      "read": 36,
                      "deleted": 3,
                      "attachments": 11
                    }
                  },
                  "meta": {
                    "request_id": "e7c87866405f3959",
                    "timestamp": "2026-10-20T19:51:35.267Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Address not owned by this key or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: ids is not an array of message identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "423": {
            "description": "domain_blocked: The owning domain is suspended or blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/inbox/unread\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"ids\":[\"8f2c1d9a4b6e\"]}'"
          }
        ]
      }
    },
    "/inbox/counts": {
      "get": {
        "operationId": "ep-inbox-counts",
        "tags": [
          "Inbox"
        ],
        "summary": "Counter snapshot for the whole filtered scope: total, unread, read, deleted, attachments, starred. Accepts every inbox filter, so you can scope it per address.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Counters\"}\n```",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "Scope the counters to one owned address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Address password when the mailbox is gated.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Counters"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "address": "signup@example.com",
                    "total": 42,
                    "unread": 7,
                    "read": 35,
                    "deleted": 3,
                    "attachments": 5,
                    "starred": 2
                  },
                  "meta": {
                    "request_id": "e7c87866405f3959",
                    "timestamp": "2026-10-20T19:51:35.267Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Address not owned by this key or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "423": {
            "description": "domain_blocked: The owning domain is suspended or blocked.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/inbox/counts?address=signup@example.com\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/inbox/star": {
      "post": {
        "operationId": "ep-inbox-star",
        "tags": [
          "Inbox"
        ],
        "summary": "Mark messages as starred. Same body and filter contract as /inbox/read: optional ids array, otherwise the whole filtered scope.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "action": "star",
                    "affected": 1,
                    "scoped_ids": 1,
                    "counters": {
                      "total": 42,
                      "unread": 7,
                      "read": 35,
                      "deleted": 3,
                      "attachments": 5,
                      "starred": 1
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: ids is not an array of message identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/inbox/star\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"ids\":[\"8f2c1d9a4b6e\"]}'"
          }
        ]
      }
    },
    "/inbox/unstar": {
      "post": {
        "operationId": "ep-inbox-unstar",
        "tags": [
          "Inbox"
        ],
        "summary": "Remove the star flag from messages. Identical contract to /inbox/star.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "action": "unstar",
                    "affected": 1,
                    "scoped_ids": 1,
                    "counters": {
                      "total": 42,
                      "unread": 7,
                      "read": 35,
                      "deleted": 3,
                      "attachments": 5,
                      "starred": 0
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: ids is not an array of message identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/inbox/unstar\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"ids\":[\"8f2c1d9a4b6e\"]}'"
          }
        ]
      }
    },
    "/inbox/delete": {
      "post": {
        "operationId": "ep-inbox-delete",
        "tags": [
          "Inbox"
        ],
        "summary": "Bulk soft delete every message matching the filters or the supplied ids, up to 5000 rows in one call. message_count is recalculated for each touched address.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "action": "delete",
                    "affected": 12,
                    "scoped_ids": null,
                    "counters": {
                      "total": 30,
                      "unread": 4,
                      "read": 26,
                      "deleted": 15,
                      "attachments": 2,
                      "starred": 0
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: ids is not an array of message identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/inbox/delete?address=signup@example.com\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"ids\":[\"8f2c1d9a4b6e\",\"3c7e0f1a2b9d\"]}'"
          }
        ]
      }
    },
    "/inbox/restore": {
      "post": {
        "operationId": "ep-inbox-restore",
        "tags": [
          "Inbox"
        ],
        "summary": "Undo a soft delete. Restores the messages into the inbox and refreshes the per-address message_count.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "action": "restore",
                    "affected": 1,
                    "scoped_ids": 1,
                    "counters": {
                      "total": 43,
                      "unread": 7,
                      "read": 36,
                      "deleted": 2,
                      "attachments": 5,
                      "starred": 1
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: ids is not an array of message identifiers.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "ids": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/inbox/restore\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"ids\":[\"8f2c1d9a4b6e\"]}'"
          }
        ]
      }
    },
    "/inbox/attachments": {
      "get": {
        "operationId": "ep-inbox-attachments",
        "tags": [
          "Inbox"
        ],
        "summary": "Flat attachment index across every message this key can read, newest first. One page of messages in, every attachment on those messages out, each with checksum_sha256 and a ready-to-call download_path pointing at /messages/{id}/attachment/{attachmentId}.",
        "description": "The mailbox router: list, count, mark, star, delete, restore, and index attachments across every address this key owns. Single-message reads and binary downloads live in the Messages group under /messages.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"type\":\"object\"}}\n```",
        "parameters": [
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "Scope to one owned address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Default 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Default 25. Max 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": [
                    {
                      "message_id": "8f2c1d9a4b6e",
                      "address": "signup@example.com",
                      "subject": "Your invoice",
                      "from": "billing@vendor.example",
                      "filename": "invoice-2291.pdf",
                      "content_type": "application/pdf",
                      "size": 184233,
                      "checksum_sha256": "9f2b...",
                      "download_path": "/api/v1/messages/8f2c1d9a4b6e/attachment/9f2b1c4d"
                    }
                  ],
                  "meta": {
                    "total": 1,
                    "page": 1,
                    "per_page": 25,
                    "pages": 1
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/inbox/attachments?address=signup@example.com&per_page=25\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/messages/{id}": {
      "get": {
        "operationId": "ep-message-get",
        "tags": [
          "Messages"
        ],
        "summary": "The full message: envelope-level sender and recipient, header Date with a validity flag, In-Reply-To, References, priority, Received chain, DKIM signatures, Authentication-Results (joined into one string), attachment checksums, raw_available, and the decoded text and html bodies. Marks it read. Password-protected addresses require the password query param.",
        "description": "The single-message router: read one message with full RFC 5322 fidelity, patch its flags, soft-delete it, download the raw .eml, or download one attachment. The attachment index that produces these ids lives at GET /inbox/attachments in the Inbox group.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/MessageDetail\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public id or numeric internal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Required when the owning address carries a password (wrong or missing password returns 404).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/MessageDetail"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "id": "8f2c1d9a4b6e",
                    "address": "signup@{PLATFORM_DOMAIN}",
                    "from": "noreply@vendor.example",
                    "from_name": "Vendor",
                    "subject": "Your verification code is 481920",
                    "preview": "Use 481920 to finish signing in.",
                    "otp": "481920",
                    "size_bytes": 18422,
                    "attachment_count": 1,
                    "has_html": true,
                    "has_attachments": true,
                    "spam_status": "clean",
                    "priority": "normal",
                    "received_at": "2026-10-20T18:02:44.000Z",
                    "read_at": "2026-10-20T18:03:10.000Z",
                    "starred_at": null,
                    "expires_at": "2026-10-21T18:02:44.000Z",
                    "to": [
                      {
                        "name": "Signup",
                        "address": "signup@{PLATFORM_DOMAIN}"
                      }
                    ],
                    "cc": [],
                    "reply_to": null,
                    "message_id": "<a1b2c3@vendor.example>",
                    "in_reply_to": null,
                    "references": [],
                    "headers_date": "2026-10-20T18:02:40.000Z",
                    "headers_date_valid": true,
                    "received_chain": [
                      "from mail.vendor.example by mx.{PLATFORM_DOMAIN}"
                    ],
                    "dkim_signatures": [
                      "v=1; a=rsa-sha256; d=vendor.example; s=sel"
                    ],
                    "authentication_results": "mx.{PLATFORM_DOMAIN}; spf=pass; dkim=pass; dmarc=pass",
                    "raw_available": true,
                    "text": "Use 481920 to finish signing in.",
                    "html": "<p>Use 481920 to finish signing in.</p>",
                    "attachments": [
                      {
                        "filename": "invoice-2291.pdf",
                        "content_type": "application/pdf",
                        "size": 184233
                      }
                    ],
                    "attachments_detail": [
                      {
                        "filename": "invoice-2291.pdf",
                        "content_type": "application/pdf",
                        "size": 184233,
                        "content_id": null,
                        "disposition": "attachment",
                        "inline": false,
                        "checksum_sha256": "9f2b1c4d...",
                        "related": false
                      }
                    ],
                    "delivery_ms": 84
                  },
                  "meta": {
                    "request_id": "e7c87866405f3959",
                    "timestamp": "2026-10-20T19:51:35.267Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Message not owned by this key, deleted, or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/messages/8f2c1d9a4b6e\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "patch": {
        "operationId": "ep-message-patch",
        "tags": [
          "Messages"
        ],
        "summary": "Update the read flag or restore a soft-deleted message. Send seen and/or is_deleted; send neither and the call is rejected with 422.",
        "description": "The single-message router: read one message with full RFC 5322 fidelity, patch its flags, soft-delete it, download the raw .eml, or download one attachment. The attachment index that produces these ids lives at GET /inbox/attachments in the Inbox group.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public id or numeric internal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Required when the owning address carries a password (wrong or missing password returns 404).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "id": "8f2c1d9a4b6e",
                    "seen": true,
                    "is_deleted": false,
                    "read_at": "2026-10-21T00:12:04.000Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Message not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: No updatable field, or a non-boolean value.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "seen": {
                    "type": "boolean"
                  },
                  "is_deleted": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X PATCH \"https://milbox.dev/api/v1/messages/8f2c1d9a4b6e\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"seen\":true}'"
          }
        ]
      },
      "delete": {
        "operationId": "ep-message-delete",
        "tags": [
          "Messages"
        ],
        "summary": "Soft-delete one message.",
        "description": "The single-message router: read one message with full RFC 5322 fidelity, patch its flags, soft-delete it, download the raw .eml, or download one attachment. The attachment index that produces these ids lives at GET /inbox/attachments in the Inbox group.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public id or numeric internal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Required when the owning address carries a password (wrong or missing password returns 404).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "deleted": 1,
                    "addresses": 1
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: Message not owned by this key, already deleted, or password mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X DELETE \"https://milbox.dev/api/v1/messages/8f2c1d9a4b6e\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/messages/{id}/download": {
      "get": {
        "operationId": "ep-message-download",
        "tags": [
          "Messages"
        ],
        "summary": "Download the stored message as raw RFC 822 bytes (message/rfc822, attachment disposition).",
        "description": "The single-message router: read one message with full RFC 5322 fidelity, patch its flags, soft-delete it, download the raw .eml, or download one attachment. The attachment index that produces these ids lives at GET /inbox/attachments in the Inbox group.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"string\",\"format\":\"binary\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public id or numeric internal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Required when the owning address carries a password (wrong or missing password returns 404).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Binary payload (message/rfc822)",
            "content": {
              "message/rfc822": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "not_found: Message not owned by this key, deleted, or captured before raw storage existed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -OJ \"https://milbox.dev/api/v1/messages/8f2c1d9a4b6e/download\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ],
        "x-success-content-type": "message/rfc822"
      }
    },
    "/messages/{id}/attachment/{attachmentId}": {
      "get": {
        "operationId": "ep-message-attachment",
        "tags": [
          "Messages"
        ],
        "summary": "Fetch one attachment by its SHA-256 checksum (full or prefix), its zero-based index, or its att_N label. Content-type and filename come from the MIME part.",
        "description": "The single-message router: read one message with full RFC 5322 fidelity, patch its flags, soft-delete it, download the raw .eml, or download one attachment. The attachment index that produces these ids lives at GET /inbox/attachments in the Inbox group.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"string\",\"format\":\"binary\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Public id or numeric internal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "attachmentId",
            "in": "path",
            "required": true,
            "description": "checksum_sha256 from attachments_detail (full or prefix), zero-based index, or att_N (zero-based).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "description": "Required when the owning address carries a password (wrong or missing password returns 404).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Binary payload (application/octet-stream (actual part content-type))",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "description": "not_found: Attachment index or checksum not present on that message.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -OJ \"https://milbox.dev/api/v1/messages/8f2c1d9a4b6e/attachment/3f9a\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ],
        "x-success-content-type": "application/octet-stream (actual part content-type)"
      }
    },
    "/messages/bulk": {
      "post": {
        "operationId": "ep-messages-bulk",
        "tags": [
          "Messages"
        ],
        "summary": "One call for the whole sweep: delete, read, unread, star or unstar every message that matches an address, a filter, or an explicit id list. Caps at 500 rows per call on purpose so a runaway sweep cannot take the mailbox with it.",
        "description": "The single-message router: read one message with full RFC 5322 fidelity, patch its flags, soft-delete it, download the raw .eml, or download one attachment. The attachment index that produces these ids lives at GET /inbox/attachments in the Inbox group.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "action": "read",
                    "affected": 37,
                    "scoped_ids": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: The address named in the body is not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: action missing, or the id list is over 500 entries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string"
                  },
                  "ids": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  },
                  "address": {
                    "type": "string"
                  },
                  "filter": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/messages/bulk\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"action\":\"read\",\"address\":\"alpha@milbox.dev\",\"filter\":\"unread\"}'"
          }
        ]
      }
    },
    "/messages/search": {
      "get": {
        "operationId": "ep-messages-search",
        "tags": [
          "Messages"
        ],
        "summary": "Full-text search across subject and body for the mail this key owns. Same filter grammar as /inbox, prefix q with +term to require a word and -term to exclude it, quote a phrase to match it literally.",
        "description": "The single-message router: read one message with full RFC 5322 fidelity, patch its flags, soft-delete it, download the raw .eml, or download one attachment. The attachment index that produces these ids lives at GET /inbox/attachments in the Inbox group.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/MessageSummary\"}}\n```",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Full-text query. +required -excluded \"exact phrase\".",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "Restrict to one mailbox.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 lower bound on received_at.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Default 50. Max 100.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/MessageSummary"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": [
                    {
                      "id": "8f2c1d9a4b6e",
                      "address": "alpha@milbox.dev",
                      "from": "billing@vendor.io",
                      "from_name": "Vendor Billing",
                      "subject": "Invoice 2291 overdue",
                      "preview": "Invoice 2291 is 14 days overdue.",
                      "otp": null,
                      "size_bytes": 24811,
                      "attachment_count": 1,
                      "has_html": true,
                      "has_attachments": true,
                      "spam_status": "clean",
                      "priority": null,
                      "received_at": "2026-10-21T11:02:44.000Z",
                      "read_at": null,
                      "starred_at": null,
                      "expires_at": "2026-10-22T11:02:44.000Z",
                      "to": [
                        {
                          "name": null,
                          "address": "alpha@milbox.dev"
                        }
                      ],
                      "cc": []
                    }
                  ],
                  "meta": {
                    "total": 1,
                    "q": "invoice overdue",
                    "page": 1,
                    "per_page": 25,
                    "next_cursor": null,
                    "searched": [
                      "subject",
                      "from_address",
                      "from_name",
                      "text_body"
                    ]
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: q is required and must be 1-120 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/messages/search?q=invoice+overdue&address=alpha@milbox.dev\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/domains": {
      "get": {
        "operationId": "ep-domains-list",
        "tags": [
          "Domains"
        ],
        "summary": "Two views in one route: with no key ownership rows this lists the public catalog; domains this key registered always appear here too. Filters cover status, type, and mail routing state.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/Domain\"}}\n```",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Substring match on the domain name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "platform_pool | custom",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "active | verified",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "premium",
            "in": "query",
            "required": false,
            "description": "true | false",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Default 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Default 50. Max 200.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Domain"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": [
                    {
                      "id": "17717649",
                      "name": "alpha.{PLATFORM_DOMAIN}",
                      "type": "platform_pool",
                      "premium": false,
                      "status": "active",
                      "verified_at": "2026-10-01T08:12:00.000Z",
                      "mx_target": "{MX_TARGET}",
                      "mail_mode": "mx_txt",
                      "added_at": "2026-09-30T22:01:44.000Z"
                    }
                  ],
                  "meta": {
                    "total": 128,
                    "page": 1,
                    "per_page": 100,
                    "pages": 2
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: status or type outside the allowed set.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/domains?type=platform_pool&per_page=100\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "post": {
        "operationId": "ep-domains-create",
        "tags": [
          "Domains"
        ],
        "summary": "Register a custom domain for temp mail. Returns the TXT challenge to publish before verifying.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "domain": {
                      "id": "46547839",
                      "name": "example.com",
                      "type": "custom",
                      "premium": false,
                      "status": "pending_verification",
                      "mail_enabled": true,
                      "verification": {
                        "host": "_milbox-challenge.example.com",
                        "value": "milbox-verify=<token>",
                        "expires_at": "2026-10-23T18:38:58.000Z",
                        "pending": true
                      }
                    },
                    "provisioning": {
                      "provider": "cloudflare",
                      "applied": true,
                      "skipped_reason": null,
                      "txt_created": true,
                      "mx_created": false,
                      "mx_skipped_reason": "mx_present",
                      "zone": "<cf-zone-id>",
                      "error": null
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "plan_custom_domains_disabled: The plan behind this key does not include custom domains.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "domain_exists: Already yours; reuse the existing row.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: Domain missing, malformed, or an IP literal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "domain_quota_exceeded: The owning account is already at its plan domain ceiling.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/domains\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"domain\":\"example.com\"}'"
          }
        ]
      }
    },
    "/domains/{id}": {
      "get": {
        "operationId": "ep-domains-get",
        "tags": [
          "Domains"
        ],
        "summary": "Fetch one domain by public id or by name. One call, no list scan.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Domain\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Domain"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "id": "17717649",
                    "name": "alpha.{PLATFORM_DOMAIN}",
                    "type": "platform_pool",
                    "premium": false,
                    "status": "active",
                    "verified_at": "2026-10-01T08:12:00.000Z",
                    "mx_target": "{MX_TARGET}",
                    "mail_mode": "mx_txt",
                    "added_at": "2026-09-30T22:01:44.000Z"
                  }
                }
              }
            }
          },
          "403": {
            "description": "premium_gated: Row is premium and the key is not.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "not_found: Not registered, or not visible to this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl https://milbox.dev/api/v1/domains/alpha.milbox.dev \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "patch": {
        "operationId": "ep-domains-patch",
        "tags": [
          "Domains"
        ],
        "summary": "Update notes, toggle mail routing, or set mail_cap_hours. mail_enabled only flips while the domain is active.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Domain\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Domain"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "id": "46547839",
                    "name": "example.com",
                    "status": "active",
                    "mail_enabled": true,
                    "mail_cap_hours": 24
                  }
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found: Not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "domain_not_active: mail_enabled flips require status active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "notes": {
                    "type": "string",
                    "nullable": true
                  },
                  "mail_enabled": {
                    "type": "boolean"
                  },
                  "mail_cap_hours": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X PATCH \"https://milbox.dev/api/v1/domains/46547839\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"mail_cap_hours\":24}'"
          }
        ]
      },
      "delete": {
        "operationId": "ep-domains-delete",
        "tags": [
          "Domains"
        ],
        "summary": "Soft-delete your domain and pull it from the MX routing table instantly.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "before": "verified",
                    "deleted": true
                  }
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found: Not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X DELETE \"https://milbox.dev/api/v1/domains/46547839\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/domains/check": {
      "get": {
        "operationId": "ep-domains-check",
        "tags": [
          "Domains"
        ],
        "summary": "Ask whether a domain is registerable before the user commits to it.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Candidate domain, normalised server-side.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "domain": "example.com",
                    "available": false,
                    "reason": "registered",
                    "premium": false,
                    "status": "active"
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: Domain missing, malformed, or an IP literal.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/domains/check?domain=example.com\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/domains/{id}/verify": {
      "post": {
        "operationId": "ep-domains-verify",
        "tags": [
          "Domains"
        ],
        "summary": "Run the TXT + MX check and flip pending_verification to verified on success.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "domain": {
                      "id": "46547839",
                      "status": "verified"
                    },
                    "check": {
                      "txt_ok": true,
                      "mx_ok": true,
                      "mx_found": [
                        "mx.{PLATFORM_DOMAIN}"
                      ]
                    },
                    "verified": true
                  }
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found: Not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "verify_failed: No stored token; rotate first.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/domains/46547839/verify\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{}'"
          }
        ]
      }
    },
    "/domains/{id}/rotate": {
      "post": {
        "operationId": "ep-domains-rotate",
        "tags": [
          "Domains"
        ],
        "summary": "Issue a fresh 72h TXT challenge token; resets verification state.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "domain": {
                      "id": "46547839",
                      "status": "pending_verification"
                    },
                    "verification": {
                      "value": "milbox-verify=<new-token>",
                      "expires_at": "2026-10-23T18:38:58.000Z",
                      "pending": true
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found: Not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/domains/46547839/rotate\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/domains/{id}/check": {
      "get": {
        "operationId": "ep-domains-dns-check",
        "tags": [
          "Domains"
        ],
        "summary": "Live DNS probe without state changes; writes last_check_result for the detail view.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "domain": {
                      "id": "46547839",
                      "status": "pending_verification"
                    },
                    "check": {
                      "txt_ok": false,
                      "txt_found": [],
                      "mx_ok": false,
                      "mx_found": [],
                      "error": null
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found: Not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/domains/46547839/check\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/domains/{id}/transition": {
      "post": {
        "operationId": "ep-domains-transition",
        "tags": [
          "Domains"
        ],
        "summary": "Lifecycle moves plus moderation: activate, resume, block for spam, fraud, abuse, or phishing, and lift the block.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Domain\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Domain"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "domain": {
                      "id": "46547839",
                      "status": "suspended",
                      "moderation": {
                        "blocked": true,
                        "reason": "spam",
                        "note": "Bulk unsolicited mail reported by three recipients.",
                        "blocked_at": "2026-10-21T04:11:02.000Z",
                        "restores_to": "active"
                      }
                    },
                    "moderation": {
                      "action": "spam",
                      "label": "Spam blocked",
                      "reason": "spam",
                      "blocking": true,
                      "before": "active",
                      "after": "suspended",
                      "note": "Bulk unsolicited mail reported by three recipients.",
                      "explanation": "Mail rejected with 550 domain blocked for spam."
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "domain_not_found: Not owned by this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "409": {
            "description": "invalid_transition: Current status does not allow the action.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "423": {
            "description": "domain_blocked: Blocked by moderation. Mail, mailbox creation, and reads are refused until the block is lifted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string"
                  },
                  "note": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/domains/46547839/transition\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"action\":\"spam\",\"note\":\"Bulk unsolicited mail reported by three recipients.\"}'"
          }
        ]
      }
    },
    "/domains/pool": {
      "get": {
        "operationId": "ep-domains-pool",
        "tags": [
          "Domains"
        ],
        "summary": "Per-domain counters for this key only: how many addresses live on each routable domain and how many live messages it holds. Answers \"which of my domains is actually carrying traffic\" without paging the inbox.",
        "description": "The domain inventory for the account behind the key. Premium rows are hidden unless the key carries premium_access.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"type\":\"object\"}}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": [
                    {
                      "domain": "inboxmil.xyz",
                      "type": "platform_pool",
                      "premium": false,
                      "addresses": 4,
                      "messages": 38
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/domains/pool\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "ep-webhooks-list",
        "tags": [
          "Webhooks"
        ],
        "summary": "List the webhooks registered for this key, newest first. The signing secret is returned once at creation and afterwards only as a stored value on this endpoint.",
        "description": "Push instead of poll. Register an HTTPS endpoint, pick events, and every delivery carries an HMAC-SHA256 signature over `${timestamp}.${body}` in the x-milbox-signature header. Failed deliveries retry twice with a 5s then 10s backoff and the per-hook failure counter resets on the next success.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/Webhook\"}}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Webhook"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": [
                    {
                      "public_id": "39396a892a7c2277",
                      "url": "https://example.com/hooks/milbox",
                      "description": "prod ingest",
                      "events": "message.received,address.created",
                      "secret": "whsec_9a1c...",
                      "active": true,
                      "failure_count": 0,
                      "last_status": 200,
                      "last_error": null,
                      "last_delivery_at": "2026-10-20T19:51:35.000Z",
                      "created_at": "2026-10-20T19:40:00.000Z",
                      "updated_at": "2026-10-20T19:51:35.000Z"
                    }
                  ]
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/webhooks\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "post": {
        "operationId": "ep-webhooks-create",
        "tags": [
          "Webhooks"
        ],
        "summary": "Register a webhook. Ten active hooks per key. Honours the idempotency-key header so a retried POST does not double-register.",
        "description": "Push instead of poll. Register an HTTPS endpoint, pick events, and every delivery carries an HMAC-SHA256 signature over `${timestamp}.${body}` in the x-milbox-signature header. Failed deliveries retry twice with a 5s then 10s backoff and the per-hook failure counter resets on the next success.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Webhook\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "public_id": "39396a892a7c2277",
                    "url": "https://example.com/hooks/milbox",
                    "events": "message.received",
                    "secret": "whsec_9a1c4f...",
                    "active": true,
                    "failure_count": 0
                  }
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: url is not a valid absolute URL.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "429": {
            "description": "webhook_limit_reached: Ten active webhooks per key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "events": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST https://milbox.dev/api/v1/webhooks \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"url\":\"https://example.com/hooks/milbox\",\"events\":[\"message.received\"]}'"
          }
        ]
      }
    },
    "/webhooks/{id}": {
      "get": {
        "operationId": "ep-webhooks-get",
        "tags": [
          "Webhooks"
        ],
        "summary": "One webhook plus its recent delivery log: event, HTTP status, duration, attempts, error. Use it to debug a receiver that started refusing payloads.",
        "description": "Push instead of poll. Register an HTTPS endpoint, pick events, and every delivery carries an HMAC-SHA256 signature over `${timestamp}.${body}` in the x-milbox-signature header. Failed deliveries retry twice with a 5s then 10s backoff and the per-hook failure counter resets on the next success.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Webhook\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Deliveries to embed, default 50, max 200.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "public_id": "39396a892a7c2277",
                    "url": "https://example.com/hooks/milbox",
                    "active": true,
                    "deliveries": [
                      {
                        "event": "message.received",
                        "status": 200,
                        "duration_ms": 84,
                        "attempts": 1,
                        "error": null,
                        "delivered_at": "2026-10-20T19:51:35.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: No webhook with that id for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/webhooks/39396a892a7c2277?limit=20\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "patch": {
        "operationId": "ep-webhooks-patch",
        "tags": [
          "Webhooks"
        ],
        "summary": "Change the target URL, description, event list, or flip active on and off. Pausing keeps the delivery log.",
        "description": "Push instead of poll. Register an HTTPS endpoint, pick events, and every delivery carries an HMAC-SHA256 signature over `${timestamp}.${body}` in the x-milbox-signature header. Failed deliveries retry twice with a 5s then 10s backoff and the per-hook failure counter resets on the next success.\n\nResponse `data` shape:\n\n```json\n{\"$ref\":\"#/components/schemas/Webhook\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Webhook"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "public_id": "39396a892a7c2277",
                    "url": "https://example.com/hooks/milbox",
                    "active": false,
                    "failure_count": 0
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: No webhook with that id for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: No supported field supplied, or url is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "events": {
                    "type": "array",
                    "maxItems": 500,
                    "items": {
                      "type": "string"
                    }
                  },
                  "active": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X PATCH \"https://milbox.dev/api/v1/webhooks/39396a892a7c2277\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"active\":false}'"
          }
        ]
      },
      "delete": {
        "operationId": "ep-webhooks-delete",
        "tags": [
          "Webhooks"
        ],
        "summary": "Delete the webhook and its delivery log. Irreversible; pause with PATCH active=false when the receiver is only temporarily broken.",
        "description": "Push instead of poll. Register an HTTPS endpoint, pick events, and every delivery carries an HMAC-SHA256 signature over `${timestamp}.${body}` in the x-milbox-signature header. Failed deliveries retry twice with a 5s then 10s backoff and the per-hook failure counter resets on the next success.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Resource identifier.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "deleted": true,
                    "public_id": "39396a892a7c2277"
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: No webhook with that id for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X DELETE \"https://milbox.dev/api/v1/webhooks/39396a892a7c2277\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/webhooks/{id}/test": {
      "post": {
        "operationId": "ep-webhooks-test",
        "tags": [
          "Webhooks"
        ],
        "summary": "Send a signed webhook.test delivery right now and get the receiver status back synchronously. The fastest way to prove the signature check on your end before a real mail arrives.",
        "description": "Push instead of poll. Register an HTTPS endpoint, pick events, and every delivery carries an HMAC-SHA256 signature over `${timestamp}.${body}` in the x-milbox-signature header. Failed deliveries retry twice with a 5s then 10s backoff and the per-hook failure counter resets on the next success.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Webhook public id.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "webhook": "39396a892a7c2277",
                    "url": "https://example.com/hooks/milbox",
                    "delivered": true,
                    "status": 200,
                    "duration_ms": 184,
                    "error": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: No webhook with that id for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/webhooks/39396a892a7c2277/test\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    },
    "/sender-rules": {
      "get": {
        "operationId": "ep-sender-rules-list",
        "tags": [
          "Sender rules"
        ],
        "summary": "The inbound allow and block list for this key, with counts per kind. Rules are evaluated before a message is stored, so a blocked sender never lands in the mailbox at all.",
        "description": "Inbound allow and block rules evaluated during ingest, before a message is written. A blocked sender is rejected with the SMTP code sender_blocked and never appears in the inbox.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"array\",\"items\":{\"type\":\"object\"}}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "rules": [
                      {
                        "id": 12,
                        "pattern": "*@promo.example",
                        "kind": "block",
                        "created_at": "2026-10-21T09:12:00.000Z"
                      },
                      {
                        "id": 9,
                        "pattern": "@trusted.partner",
                        "kind": "allow",
                        "created_at": "2026-10-20T14:02:11.000Z"
                      }
                    ],
                    "counts": {
                      "allow": 1,
                      "block": 1
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/sender-rules\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "post": {
        "operationId": "ep-sender-rules-create",
        "tags": [
          "Sender rules"
        ],
        "summary": "Add a rule, or flip the kind on an existing pattern. Once a key carries at least one allow rule the list becomes a real allowlist: any sender that matches nothing is treated as blocked.",
        "description": "Inbound allow and block rules evaluated during ingest, before a message is written. A blocked sender is rejected with the SMTP code sender_blocked and never appears in the inbox.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "rule": {
                      "id": 13,
                      "pattern": "*@promo.example",
                      "kind": "block",
                      "created_at": "2026-10-22T01:04:09.000Z"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "conflict: The key already holds 200 sender rules.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "422": {
            "description": "validation_failed: The pattern is not an address, domain, wildcard, or glob.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "pattern": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X POST \"https://milbox.dev/api/v1/sender-rules\" \\\n  -H \"x-api-key: MILBOX_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"pattern\":\"*@promo.example\",\"kind\":\"block\"}'"
          }
        ]
      }
    },
    "/sender-rules/{id}": {
      "get": {
        "operationId": "ep-sender-rules-get",
        "tags": [
          "Sender rules"
        ],
        "summary": "One rule by numeric id.",
        "description": "Inbound allow and block rules evaluated during ingest, before a message is written. A blocked sender is rejected with the SMTP code sender_blocked and never appears in the inbox.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Rule id, integers only.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "rule": {
                      "id": 13,
                      "pattern": "*@promo.example",
                      "kind": "block",
                      "created_at": "2026-10-22T01:04:09.000Z"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: No rule with that id for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl \"https://milbox.dev/api/v1/sender-rules/13\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      },
      "delete": {
        "operationId": "ep-sender-rules-delete",
        "tags": [
          "Sender rules"
        ],
        "summary": "Remove a rule. Mail from that sender flows normally on the next ingest.",
        "description": "Inbound allow and block rules evaluated during ingest, before a message is written. A blocked sender is rejected with the SMTP code sender_blocked and never appears in the inbox.\n\nResponse `data` shape:\n\n```json\n{\"type\":\"object\"}\n```",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Rule id, integers only.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success (envelope: ok/data/meta)",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    }
                  ],
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  }
                },
                "example": {
                  "ok": true,
                  "data": {
                    "deleted": true,
                    "id": 13
                  }
                }
              }
            }
          },
          "404": {
            "description": "not_found: No rule with that id for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Bash",
            "label": "cURL",
            "source": "curl -X DELETE \"https://milbox.dev/api/v1/sender-rules/13\" \\\n  -H \"x-api-key: MILBOX_API_KEY\""
          }
        ]
      }
    }
  },
  "x-error-codes": [
    {
      "status": 400,
      "code": "bad_request",
      "meaning": "The identifier in the path is malformed."
    },
    {
      "status": 401,
      "code": "invalid_api_key",
      "meaning": "The presented key does not match any stored hash."
    },
    {
      "status": 401,
      "code": "invalid_key",
      "meaning": "See the reference documentation."
    },
    {
      "status": 401,
      "code": "key_expired",
      "meaning": "The key passed its expiry timestamp."
    },
    {
      "status": 401,
      "code": "key_revoked",
      "meaning": "The key was revoked from the panel."
    },
    {
      "status": 401,
      "code": "missing_api_key",
      "meaning": "No x-api-key header and no Bearer token."
    },
    {
      "status": 401,
      "code": "no_session",
      "meaning": "See the reference documentation."
    },
    {
      "status": 401,
      "code": "unauthorized",
      "meaning": "No active panel session (panel API surface only)."
    },
    {
      "status": 403,
      "code": "insufficient_scope",
      "meaning": "See the reference documentation."
    },
    {
      "status": 403,
      "code": "ip_not_allowed",
      "meaning": "Caller IP is outside the key allowlist. error.details.ip_allowlist echoes the expected ranges."
    },
    {
      "status": 403,
      "code": "owner_only",
      "meaning": "Only the owner role may rewrite plan limits."
    },
    {
      "status": 403,
      "code": "plan_cloudflare_disabled",
      "meaning": "The plan does not include Cloudflare routing."
    },
    {
      "status": 403,
      "code": "plan_custom_domains_disabled",
      "meaning": "The plan does not include custom domains."
    },
    {
      "status": 403,
      "code": "plan_premium_domains_disabled",
      "meaning": "The plan does not include premium domains."
    },
    {
      "status": 403,
      "code": "plan_subject_missing",
      "meaning": "No owning account could be resolved for the key."
    },
    {
      "status": 403,
      "code": "premium_gated",
      "meaning": "Row requires premium access the key does not carry."
    },
    {
      "status": 404,
      "code": "alias_target_not_found",
      "meaning": "See the reference documentation."
    },
    {
      "status": 404,
      "code": "domain_not_found",
      "meaning": "No domain owned by this key matches the identifier."
    },
    {
      "status": 404,
      "code": "not_found",
      "meaning": "No visible domain, address, or message matches the identifier."
    },
    {
      "status": 405,
      "code": "method_not_allowed",
      "meaning": "See the reference documentation."
    },
    {
      "status": 409,
      "code": "address_exists",
      "meaning": "That local part is already taken on the domain."
    },
    {
      "status": 409,
      "code": "conflict",
      "meaning": "The resource could not be deleted in its current state."
    },
    {
      "status": 409,
      "code": "domain_abuse",
      "meaning": "The domain is blocked for abuse. Inbound mail is rejected with 550."
    },
    {
      "status": 409,
      "code": "domain_ban",
      "meaning": "The domain is banned by an operator. Inbound mail is rejected with 550."
    },
    {
      "status": 409,
      "code": "domain_exists",
      "meaning": "This domain is already registered under your key."
    },
    {
      "status": 409,
      "code": "domain_fraud",
      "meaning": "The domain is blocked for fraud. Inbound mail is rejected with 550."
    },
    {
      "status": 409,
      "code": "domain_not_active",
      "meaning": "This operation requires the domain to be in the active state."
    },
    {
      "status": 409,
      "code": "domain_not_routable",
      "meaning": "Domain exists but is not active or has mail disabled."
    },
    {
      "status": 409,
      "code": "domain_phishing",
      "meaning": "The domain is blocked for phishing. Inbound mail is rejected with 550."
    },
    {
      "status": 409,
      "code": "domain_spam",
      "meaning": "The domain is blocked for spam. Inbound mail is rejected with 550."
    },
    {
      "status": 409,
      "code": "domain_suspend",
      "meaning": "The domain is suspended by an operator. Inbound mail is rejected with 550."
    },
    {
      "status": 409,
      "code": "domain_taken",
      "meaning": "This domain is already registered on the platform."
    },
    {
      "status": 409,
      "code": "email_taken",
      "meaning": "See the reference documentation."
    },
    {
      "status": 409,
      "code": "invalid_transition",
      "meaning": "The requested lifecycle transition is not valid for the current domain status."
    },
    {
      "status": 409,
      "code": "verify_failed",
      "meaning": "No verification token exists. Rotate the token first, then retry."
    },
    {
      "status": 413,
      "code": "message_too_large",
      "meaning": "See the reference documentation."
    },
    {
      "status": 415,
      "code": "unsupported_media_type",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "allowlist_required",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "current_session",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "empty_message",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "empty_patch",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "invalid_ip_entry",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "no_allowed_settings",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "reserved_local_part",
      "meaning": "postmaster, abuse, admin and friends are reserved."
    },
    {
      "status": 422,
      "code": "sender_blocked",
      "meaning": "Inbound mail from that sender matched a block rule on the key, or matched no allow rule while an allowlist exists. Rejected during ingest, before storage."
    },
    {
      "status": 422,
      "code": "status_not_patchable",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "token_invalid",
      "meaning": "The supplied verification token is not 32 hexadecimal characters."
    },
    {
      "status": 422,
      "code": "ttl_exceeds_domain",
      "meaning": "See the reference documentation."
    },
    {
      "status": 422,
      "code": "validation_failed",
      "meaning": "A field or query parameter is outside the accepted set. error.details lists each offending field."
    },
    {
      "status": 423,
      "code": "domain_blocked",
      "meaning": "An operator blocked the domain. 423 on mailbox creation, inbox, address, and message reads; lifecycle moves return 409. Lift the block first."
    },
    {
      "status": 429,
      "code": "address_quota_exceeded",
      "meaning": "Per-key address quota reached. meta.quota shows the limit."
    },
    {
      "status": 429,
      "code": "api_key_quota_exceeded",
      "meaning": "Active API-key ceiling for the plan reached."
    },
    {
      "status": 429,
      "code": "domain_quota_exceeded",
      "meaning": "Account domain ceiling for the plan reached. error.details carries plan, limit, used, remaining."
    },
    {
      "status": 429,
      "code": "plan_address_quota_exceeded",
      "meaning": "Account-wide mailbox ceiling for the plan reached. error.details carries plan, limit, used, remaining."
    },
    {
      "status": 429,
      "code": "rate_limited",
      "meaning": "Per-key budget exhausted. error.details.retry_after holds the wait in seconds; the response also carries the standard Retry-After header."
    },
    {
      "status": 429,
      "code": "webhook_limit_reached",
      "meaning": "See the reference documentation."
    },
    {
      "status": 500,
      "code": "internal_error",
      "meaning": "An unexpected server condition. Retry with backoff; meta.request_id identifies the request in support inquiries."
    },
    {
      "status": 500,
      "code": "settings_write_failed",
      "meaning": "See the reference documentation."
    },
    {
      "status": 503,
      "code": "ingest_disabled",
      "meaning": "See the reference documentation."
    },
    {
      "status": 503,
      "code": "maintenance_mode",
      "meaning": "The public API is paused from the panel maintenance switch. Panel and ingest are unaffected; 503 carries a retry-after header."
    }
  ],
  "x-availability-reasons": [
    {
      "reason": "available",
      "meaning": "Nothing registered under that name. Safe to offer."
    },
    {
      "reason": "registered",
      "meaning": "A live row exists. Do not offer it again."
    },
    {
      "reason": "premium_gated",
      "meaning": "The row is premium and this key cannot see it."
    },
    {
      "reason": "unsupported",
      "meaning": "The row exists but is pending or deleted."
    },
    {
      "reason": "blocked",
      "meaning": "An operator blocked the row for spam, fraud, abuse, or phishing. moderation.reason carries which."
    }
  ]
}