{
  "openapi": "3.0.3",
  "info": {
    "title": "hemo-mail",
    "version": "2.0.0",
    "description": "Self-owned email control plane for the HEMO economy — DKIM-signed on our infrastructure, no third-party providers. Docs: https://hemo-mail.fogeboro.workers.dev/llms.txt"
  },
  "servers": [
    {
      "url": "https://hemo-mail.fogeboro.workers.dev"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      },
      "operatorAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "OPERATOR_TOKEN secret (MTA daemon / operator only)"
      }
    }
  },
  "paths": {
    "/api/v1/send": {
      "post": {
        "summary": "Queue an email on self-owned rails",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "to",
                  "subject",
                  "text"
                ],
                "properties": {
                  "to": {
                    "type": "string"
                  },
                  "subject": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "text": {
                    "type": "string",
                    "maxLength": 20000
                  },
                  "html": {
                    "type": "string",
                    "maxLength": 50000
                  },
                  "agent_id": {
                    "type": "string",
                    "maxLength": 80
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "queued; DKIM-signed, awaiting MTA lease"
          },
          "400": {
            "description": "validation error"
          },
          "401": {
            "description": "invalid helios token"
          },
          "429": {
            "description": "recipient dedupe cap"
          },
          "503": {
            "description": "global runaway fuse hit (2000/day economy-wide)"
          },
          "550": {
            "description": "recipient suppressed (hard bounce history)"
          }
        }
      }
    },
    "/api/v1/status": {
      "get": {
        "summary": "Caller's own usage today",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "usage snapshot incl. transport=self-hosted"
          },
          "401": {
            "description": "invalid helios token"
          }
        }
      }
    },
    "/api/v1/webhooks": {
      "post": {
        "summary": "Register delivery-status webhook",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "registered; secret returned once"
          },
          "400": {
            "description": "bad url"
          },
          "401": {
            "description": "invalid helios token"
          }
        }
      },
      "get": {
        "summary": "Inspect webhook registration",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "registration status"
          },
          "401": {
            "description": "invalid helios token"
          }
        }
      }
    },
    "/api/v1/outbox/claim": {
      "get": {
        "summary": "Lease up to 10 queued messages for SMTP delivery",
        "security": [
          {
            "operatorAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "array of leased messages with message_raw + envelope"
          },
          "401": {
            "description": "operator only"
          }
        }
      }
    },
    "/api/v1/outbox/report": {
      "post": {
        "summary": "Report delivery outcome (delivered|soft|hard)",
        "security": [
          {
            "operatorAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "status updated"
          },
          "400": {
            "description": "bad report"
          },
          "401": {
            "description": "operator only"
          },
          "404": {
            "description": "unknown message_id"
          }
        }
      }
    },
    "/api/v1/outbox/stats": {
      "get": {
        "summary": "Outbox counts by status",
        "security": [
          {
            "operatorAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "counts"
          },
          "401": {
            "description": "operator only"
          }
        }
      }
    },
    "/api/v1/dns-records": {
      "get": {
        "summary": "Exact DKIM/DMARC/SPF records to install",
        "security": [
          {
            "operatorAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "records"
          },
          "401": {
            "description": "operator only"
          }
        }
      }
    }
  }
}