feat(api): 新增开放 API 与 Token 管理

- 新增 API Token 的创建、查询、更新和撤销接口，并支持 Bearer 认证
- 新增 `/api/open` 域名、邮箱、发信与消息查询接口，补充权限校验
- 更新数据库迁移、路由与测试，并新增开放 API 文档

apps/api/internal/app/api_token_handlers.go

@@ -0,0 +1,211 @@
+package app
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+)
+
+const defaultAPITokenTTL = 90 * 24 * time.Hour
+
+func (a *App) handleListAPITokens(w http.ResponseWriter, r *http.Request) {
+	user := currentUser(r)
+	rows, err := a.db.QueryContext(r.Context(), `SELECT id,name,last_used_at,expires_at,disabled,created_at,updated_at
+		FROM api_tokens WHERE user_id=? ORDER BY created_at DESC`, user.ID)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to list api tokens")
+		return
+	}
+	defer rows.Close()
+	items := []APIToken{}
+	for rows.Next() {
+		item, err := scanAPIToken(rows)
+		if err != nil {
+			respondError(w, http.StatusInternalServerError, "failed to scan api tokens")
+			return
+		}
+		items = append(items, item)
+	}
+	if err := rows.Err(); err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to list api tokens")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+func (a *App) handleCreateAPIToken(w http.ResponseWriter, r *http.Request) {
+	user := currentUser(r)
+	var req struct {
+		Name      string `json:"name"`
+		ExpiresAt string `json:"expiresAt"`
+	}
+	if err := decodeJSON(r, &req); err != nil {
+		badRequest(w, err)
+		return
+	}
+	name := strings.TrimSpace(req.Name)
+	if name == "" {
+		badRequest(w, errors.New("name is required"))
+		return
+	}
+	if len([]rune(name)) > 80 {
+		badRequest(w, errors.New("name cannot exceed 80 characters"))
+		return
+	}
+	expiresAt, err := parseOptionalFutureTime(req.ExpiresAt, a.now().UTC())
+	if err != nil {
+		badRequest(w, err)
+		return
+	}
+	if expiresAt == nil {
+		defaultExpiry := a.now().UTC().Add(defaultAPITokenTTL)
+		expiresAt = &defaultExpiry
+	}
+	id := newID("apt")
+	token := "lq_" + randomToken()
+	now := a.now().UTC().Format(time.RFC3339Nano)
+	var expiresValue any
+	if expiresAt != nil {
+		expiresValue = expiresAt.UTC().Format(time.RFC3339Nano)
+	}
+	if _, err := a.db.ExecContext(r.Context(), `INSERT INTO api_tokens(id,user_id,name,token_hash,expires_at,disabled,created_at,updated_at)
+		VALUES(?,?,?,?,?,?,?,?)`, id, user.ID, name, hashToken(token), expiresValue, 0, now, now); err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to create api token")
+		return
+	}
+	item, err := a.apiTokenByID(r.Context(), user.ID, id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load api token")
+		return
+	}
+	respondJSON(w, http.StatusCreated, map[string]any{"token": token, "item": item})
+}
+
+func (a *App) handleUpdateAPIToken(w http.ResponseWriter, r *http.Request) {
+	user := currentUser(r)
+	id := strings.TrimSpace(chi.URLParam(r, "id"))
+	if id == "" {
+		respondError(w, http.StatusNotFound, "api token not found")
+		return
+	}
+	var req struct {
+		Name      *string `json:"name"`
+		ExpiresAt *string `json:"expiresAt"`
+		Disabled  *bool   `json:"disabled"`
+	}
+	if err := decodeJSON(r, &req); err != nil {
+		badRequest(w, err)
+		return
+	}
+	current, err := a.apiTokenByID(r.Context(), user.ID, id)
+	if err != nil {
+		respondError(w, http.StatusNotFound, "api token not found")
+		return
+	}
+	name := current.Name
+	if req.Name != nil {
+		name = strings.TrimSpace(*req.Name)
+		if name == "" {
+			badRequest(w, errors.New("name is required"))
+			return
+		}
+		if len([]rune(name)) > 80 {
+			badRequest(w, errors.New("name cannot exceed 80 characters"))
+			return
+		}
+	}
+	var expiresValue any
+	if current.ExpiresAt != nil {
+		expiresValue = current.ExpiresAt.UTC().Format(time.RFC3339Nano)
+	}
+	if req.ExpiresAt != nil {
+		expiresAt, err := parseOptionalFutureTime(*req.ExpiresAt, a.now().UTC())
+		if err != nil {
+			badRequest(w, err)
+			return
+		}
+		expiresValue = nil
+		if expiresAt != nil {
+			expiresValue = expiresAt.UTC().Format(time.RFC3339Nano)
+		}
+	}
+	disabled := current.Disabled
+	if req.Disabled != nil {
+		disabled = *req.Disabled
+	}
+	res, err := a.db.ExecContext(r.Context(), `UPDATE api_tokens SET name=?,expires_at=?,disabled=?,updated_at=? WHERE id=? AND user_id=?`,
+		name, expiresValue, boolInt(disabled), a.now().UTC().Format(time.RFC3339Nano), id, user.ID)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to update api token")
+		return
+	}
+	if affected, _ := res.RowsAffected(); affected == 0 {
+		respondError(w, http.StatusNotFound, "api token not found")
+		return
+	}
+	item, err := a.apiTokenByID(r.Context(), user.ID, id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load api token")
+		return
+	}
+	respondJSON(w, http.StatusOK, item)
+}
+
+func (a *App) handleDeleteAPIToken(w http.ResponseWriter, r *http.Request) {
+	user := currentUser(r)
+	res, err := a.db.ExecContext(r.Context(), `DELETE FROM api_tokens WHERE id=? AND user_id=?`, chi.URLParam(r, "id"), user.ID)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to delete api token")
+		return
+	}
+	if affected, _ := res.RowsAffected(); affected == 0 {
+		respondError(w, http.StatusNotFound, "api token not found")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]any{"ok": true})
+}
+
+func (a *App) apiTokenByID(ctx context.Context, userID, id string) (APIToken, error) {
+	row := a.db.QueryRowContext(ctx, `SELECT id,name,last_used_at,expires_at,disabled,created_at,updated_at
+		FROM api_tokens WHERE id=? AND user_id=?`, id, userID)
+	return scanAPIToken(row)
+}
+
+type apiTokenScanner interface{ Scan(dest ...any) error }
+
+func scanAPIToken(row apiTokenScanner) (APIToken, error) {
+	var item APIToken
+	var lastUsed, expires sql.NullString
+	var disabled int
+	var created, updated string
+	if err := row.Scan(&item.ID, &item.Name, &lastUsed, &expires, &disabled, &created, &updated); err != nil {
+		return item, err
+	}
+	item.LastUsedAt = nullableTime(lastUsed)
+	item.ExpiresAt = nullableTime(expires)
+	item.Disabled = intBool(disabled)
+	item.CreatedAt = parseTime(created)
+	item.UpdatedAt = parseTime(updated)
+	return item, nil
+}
+
+func parseOptionalFutureTime(value string, now time.Time) (*time.Time, error) {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return nil, nil
+	}
+	t, err := time.Parse(time.RFC3339Nano, value)
+	if err != nil {
+		return nil, errors.New("expiresAt must be an RFC3339 timestamp")
+	}
+	t = t.UTC()
+	if !t.After(now) {
+		return nil, errors.New("expiresAt must be in the future")
+	}
+	return &t, nil
+}

apps/api/internal/app/app.go

@@ -163,6 +163,19 @@ func (a *App) migrate(ctx context.Context) error {
 			expires_at TEXT NOT NULL,
 			created_at TEXT NOT NULL
 		)`,
+		`CREATE TABLE IF NOT EXISTS api_tokens (
+			id TEXT PRIMARY KEY,
+			user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+			name TEXT NOT NULL,
+			token_hash TEXT NOT NULL UNIQUE,
+			last_used_at TEXT,
+			expires_at TEXT,
+			disabled INTEGER NOT NULL DEFAULT 0,
+			created_at TEXT NOT NULL,
+			updated_at TEXT NOT NULL
+		)`,
+		`CREATE INDEX IF NOT EXISTS idx_api_tokens_user ON api_tokens(user_id, created_at DESC)`,
+		`CREATE INDEX IF NOT EXISTS idx_api_tokens_hash ON api_tokens(token_hash)`,
 		`CREATE TABLE IF NOT EXISTS system_settings (
 			key TEXT PRIMARY KEY,
 			value TEXT NOT NULL,

apps/api/internal/app/app_test.go

@@ -218,6 +218,7 @@ type testClient struct {
 	t      *testing.T
 	server *httptest.Server
 	cookie *http.Cookie
+	bearer string
 }
 
 func (c *testClient) do(method, path string, body any, out any) int {
@@ -237,6 +238,9 @@ func (c *testClient) do(method, path string, body any, out any) int {
 	if c.cookie != nil {
 		req.AddCookie(c.cookie)
 	}
+	if c.bearer != "" {
+		req.Header.Set("Authorization", "Bearer "+c.bearer)
+	}
 	resp, err := http.DefaultClient.Do(req)
 	if err != nil {
 		c.t.Fatal(err)
@@ -279,6 +283,21 @@ func createTestMailbox(t *testing.T, admin *testClient, domainID, localPart, dis
 	return mailbox
 }
 
+func createTestAPIToken(t *testing.T, client *testClient, name string) string {
+	t.Helper()
+	var resp struct {
+		Token string   `json:"token"`
+		Item  APIToken `json:"item"`
+	}
+	if code := client.do("POST", "/api/me/api-tokens", map[string]string{"name": name}, &resp); code != http.StatusCreated {
+		t.Fatalf("create api token code=%d resp=%+v", code, resp)
+	}
+	if resp.Token == "" || resp.Item.ID == "" || resp.Item.Name != name {
+		t.Fatalf("api token response=%+v", resp)
+	}
+	return resp.Token
+}
+
 func updateRegularPermissionGroup(t *testing.T, admin *testClient, permissions []string) PermissionGroup {
 	t.Helper()
 	var group PermissionGroup
@@ -1649,6 +1668,246 @@ func TestMailSendRollsBackSentCopyWhenQueueInsertFails(t *testing.T) {
 	}
 }
 
+func TestAPITokenManagementStoresHashAndRevokes(t *testing.T) {
+	a := newTestApp(t)
+	ts := httptest.NewServer(a.Router())
+	defer ts.Close()
+	admin := &testClient{t: t, server: ts}
+
+	if code := admin.do("POST", "/api/auth/login", map[string]string{"email": "admin@lanqin.local", "password": "ChangeMe123!"}, nil); code != http.StatusOK {
+		t.Fatalf("login code=%d", code)
+	}
+	var created struct {
+		Token string   `json:"token"`
+		Item  APIToken `json:"item"`
+	}
+	if code := admin.do("POST", "/api/me/api-tokens", map[string]string{"name": "integration-test"}, &created); code != http.StatusCreated {
+		t.Fatalf("create api token code=%d resp=%+v", code, created)
+	}
+	if !strings.HasPrefix(created.Token, "lq_") || created.Item.ID == "" || created.Item.Name != "integration-test" || created.Item.ExpiresAt == nil {
+		t.Fatalf("created token response=%+v", created)
+	}
+	if remaining := time.Until(*created.Item.ExpiresAt); remaining < 89*24*time.Hour || remaining > 91*24*time.Hour {
+		t.Fatalf("created token default expiry=%s, remaining=%s", created.Item.ExpiresAt, remaining)
+	}
+	var storedHash string
+	if err := a.db.QueryRow(`SELECT token_hash FROM api_tokens WHERE id=?`, created.Item.ID).Scan(&storedHash); err != nil {
+		t.Fatal(err)
+	}
+	if storedHash == created.Token || storedHash != hashToken(created.Token) {
+		t.Fatalf("stored token hash=%q token=%q", storedHash, created.Token)
+	}
+
+	openAdmin := &testClient{t: t, server: ts, bearer: created.Token}
+	var domains struct {
+		Items []Domain `json:"items"`
+	}
+	if code := openAdmin.do("GET", "/api/open/domains", nil, &domains); code != http.StatusOK {
+		t.Fatalf("open api with bearer token code=%d", code)
+	}
+	var listed struct {
+		Items []APIToken `json:"items"`
+	}
+	if code := admin.do("GET", "/api/me/api-tokens", nil, &listed); code != http.StatusOK {
+		t.Fatalf("list api tokens code=%d", code)
+	}
+	if len(listed.Items) != 1 || listed.Items[0].ID != created.Item.ID || listed.Items[0].LastUsedAt == nil {
+		t.Fatalf("listed tokens=%+v", listed.Items)
+	}
+
+	disabled := true
+	var updated APIToken
+	if code := admin.do("POST", "/api/me/api-tokens/"+created.Item.ID, map[string]any{"disabled": disabled}, &updated); code != http.StatusOK {
+		t.Fatalf("disable api token code=%d item=%+v", code, updated)
+	}
+	if !updated.Disabled {
+		t.Fatalf("updated token should be disabled: %+v", updated)
+	}
+	if code := openAdmin.do("GET", "/api/open/domains", nil, &map[string]any{}); code != http.StatusUnauthorized {
+		t.Fatalf("disabled bearer token code=%d", code)
+	}
+	if code := admin.do("DELETE", "/api/me/api-tokens/"+created.Item.ID, nil, &map[string]any{}); code != http.StatusOK {
+		t.Fatalf("delete api token code=%d", code)
+	}
+}
+
+func TestPublicAPIDomainAndMailboxCRUD(t *testing.T) {
+	a := newTestApp(t)
+	ts := httptest.NewServer(a.Router())
+	defer ts.Close()
+	admin := &testClient{t: t, server: ts}
+
+	var login map[string]any
+	if code := admin.do("POST", "/api/auth/login", map[string]string{"email": "admin@lanqin.local", "password": "ChangeMe123!"}, &login); code != http.StatusOK {
+		t.Fatalf("login code=%d body=%v", code, login)
+	}
+	adminToken := createTestAPIToken(t, admin, "admin-open-api")
+	openAdmin := &testClient{t: t, server: ts, bearer: adminToken}
+
+	var authErr map[string]any
+	if code := admin.do("GET", "/api/open/domains", nil, &authErr); code != http.StatusUnauthorized {
+		t.Fatalf("cookie-only open api code=%d body=%v", code, authErr)
+	}
+
+	var domain Domain
+	if code := openAdmin.do("POST", "/api/open/domains", map[string]string{"name": "api.example.test"}, &domain); code != http.StatusCreated {
+		t.Fatalf("create public api domain code=%d domain=%+v", code, domain)
+	}
+	if domain.Name != "api.example.test" || domain.DKIMPublicKey == "" {
+		t.Fatalf("domain=%+v", domain)
+	}
+	var domains struct {
+		Items []Domain `json:"items"`
+	}
+	if code := openAdmin.do("GET", "/api/open/domains", nil, &domains); code != http.StatusOK {
+		t.Fatalf("list public api domains code=%d", code)
+	}
+	if len(domains.Items) < 2 {
+		t.Fatalf("domains=%+v", domains.Items)
+	}
+	var disabled Domain
+	if code := openAdmin.do("POST", "/api/open/domains/"+domain.ID, map[string]string{"status": "disabled"}, &disabled); code != http.StatusOK {
+		t.Fatalf("update public api domain code=%d domain=%+v", code, disabled)
+	}
+	if disabled.Status != "disabled" {
+		t.Fatalf("domain status=%q", disabled.Status)
+	}
+	if code := openAdmin.do("POST", "/api/open/domains/"+domain.ID, map[string]string{"status": "active"}, &domain); code != http.StatusOK {
+		t.Fatalf("reactivate public api domain code=%d domain=%+v", code, domain)
+	}
+
+	var mailbox Mailbox
+	if code := openAdmin.do("POST", "/api/open/mailboxes", map[string]any{
+		"domainId":    domain.ID,
+		"localPart":   "api-user",
+		"displayName": "API User",
+		"password":    "Password123!",
+		"quotaMb":     256,
+	}, &mailbox); code != http.StatusCreated {
+		t.Fatalf("create public api mailbox code=%d mailbox=%+v", code, mailbox)
+	}
+	if mailbox.Address != "api-user@api.example.test" || mailbox.QuotaMB != 256 {
+		t.Fatalf("mailbox=%+v", mailbox)
+	}
+	var mailboxes struct {
+		Items []Mailbox `json:"items"`
+	}
+	if code := openAdmin.do("GET", "/api/open/mailboxes", nil, &mailboxes); code != http.StatusOK {
+		t.Fatalf("list public api mailboxes code=%d", code)
+	}
+	if len(mailboxes.Items) < 2 {
+		t.Fatalf("mailboxes=%+v", mailboxes.Items)
+	}
+	var updated Mailbox
+	if code := openAdmin.do("POST", "/api/open/mailboxes/"+mailbox.ID, map[string]any{"displayName": "Renamed API User", "quotaMb": 512, "status": "disabled"}, &updated); code != http.StatusOK {
+		t.Fatalf("update public api mailbox code=%d mailbox=%+v", code, updated)
+	}
+	if updated.DisplayName != "Renamed API User" || updated.QuotaMB != 512 || updated.Status != "disabled" {
+		t.Fatalf("updated mailbox=%+v", updated)
+	}
+	var ok map[string]any
+	if code := openAdmin.do("DELETE", "/api/open/mailboxes/"+mailbox.ID, nil, &ok); code != http.StatusOK {
+		t.Fatalf("delete public api mailbox code=%d body=%v", code, ok)
+	}
+	if code := openAdmin.do("DELETE", "/api/open/domains/"+domain.ID, nil, &ok); code != http.StatusOK {
+		t.Fatalf("delete public api domain code=%d body=%v", code, ok)
+	}
+}
+
+func TestPublicAPISendStatusAndMailboxMessages(t *testing.T) {
+	a := newTestApp(t)
+	stopTestWorkers(a)
+	ts := httptest.NewServer(a.Router())
+	defer ts.Close()
+	admin := &testClient{t: t, server: ts}
+
+	var login map[string]any
+	if code := admin.do("POST", "/api/auth/login", map[string]string{"email": "admin@lanqin.local", "password": "ChangeMe123!"}, &login); code != http.StatusOK {
+		t.Fatalf("admin login code=%d body=%v", code, login)
+	}
+	domainID := mustDefaultDomainID(t, a)
+	sender := createTestMailbox(t, admin, domainID, "public-sender", "Public Sender", "Password123!", nil)
+	recipient := createTestMailbox(t, admin, domainID, "public-recipient", "Public Recipient", "Password123!", nil)
+	other := createTestMailbox(t, admin, domainID, "public-other", "Public Other", "Password123!", nil)
+
+	senderClient := &testClient{t: t, server: ts}
+	if code := senderClient.do("POST", "/api/auth/login", map[string]string{"email": sender.Address, "password": "Password123!"}, &login); code != http.StatusOK {
+		t.Fatalf("sender login code=%d body=%v", code, login)
+	}
+	senderToken := createTestAPIToken(t, senderClient, "sender-open-api")
+	senderOpen := &testClient{t: t, server: ts, bearer: senderToken}
+	if code := senderClient.do("POST", "/api/open/send", map[string]any{
+		"mailboxId": sender.ID,
+		"to":        []string{recipient.Address},
+		"subject":   "cookie-only public api send",
+		"text":      "this should not authenticate",
+	}, &map[string]any{}); code != http.StatusUnauthorized {
+		t.Fatalf("cookie-only public api send code=%d", code)
+	}
+	var sent struct {
+		ID             string    `json:"id"`
+		QueueID        string    `json:"queueId"`
+		Status         string    `json:"status"`
+		MessageID      string    `json:"messageId"`
+		RFCMessageID   string    `json:"rfcMessageId"`
+		MailboxID      string    `json:"mailboxId"`
+		MailboxAddress string    `json:"mailboxAddress"`
+		Subject        string    `json:"subject"`
+		CreatedAt      time.Time `json:"createdAt"`
+	}
+	if code := senderOpen.do("POST", "/api/open/send", map[string]any{
+		"mailboxId": sender.ID,
+		"to":        []string{recipient.Address},
+		"subject":   "public api send",
+		"text":      "hello from public api",
+	}, &sent); code != http.StatusCreated {
+		t.Fatalf("public api send code=%d body=%+v", code, sent)
+	}
+	if sent.ID == "" || sent.Status != sendAuditAccepted || sent.MessageID == "" || sent.MailboxAddress != sender.Address {
+		t.Fatalf("sent response=%+v", sent)
+	}
+
+	var status struct {
+		ID             string `json:"id"`
+		QueueID        string `json:"queueId"`
+		Status         string `json:"status"`
+		MessageID      string `json:"messageId"`
+		RFCMessageID   string `json:"rfcMessageId"`
+		MailboxID      string `json:"mailboxId"`
+		MailboxAddress string `json:"mailboxAddress"`
+		Subject        string `json:"subject"`
+	}
+	if code := senderOpen.do("GET", "/api/open/send/"+sent.ID, nil, &status); code != http.StatusOK {
+		t.Fatalf("public api send status code=%d status=%+v", code, status)
+	}
+	if status.ID != sent.ID || status.MessageID != sent.MessageID || status.Status != sendAuditAccepted {
+		t.Fatalf("status=%+v sent=%+v", status, sent)
+	}
+
+	recipientClient := &testClient{t: t, server: ts}
+	if code := recipientClient.do("POST", "/api/auth/login", map[string]string{"email": recipient.Address, "password": "Password123!"}, &login); code != http.StatusOK {
+		t.Fatalf("recipient login code=%d body=%v", code, login)
+	}
+	recipientToken := createTestAPIToken(t, recipientClient, "recipient-open-api")
+	recipientOpen := &testClient{t: t, server: ts, bearer: recipientToken}
+	var inbox struct {
+		Items      []MailMessage `json:"items"`
+		NextCursor string        `json:"nextCursor"`
+	}
+	if code := recipientOpen.do("GET", "/api/open/mailboxes/"+recipient.ID+"/messages?folder=Inbox", nil, &inbox); code != http.StatusOK {
+		t.Fatalf("public api mailbox messages code=%d inbox=%+v", code, inbox)
+	}
+	if len(inbox.Items) != 1 || inbox.Items[0].Subject != "public api send" || inbox.Items[0].From != sender.Address {
+		t.Fatalf("inbox=%+v", inbox.Items)
+	}
+	if code := recipientOpen.do("GET", "/api/open/mailboxes/"+other.ID+"/messages?folder=Inbox", nil, &map[string]any{}); code != http.StatusNotFound {
+		t.Fatalf("cross-user mailbox read code=%d", code)
+	}
+	if code := recipientOpen.do("GET", "/api/open/send/"+sent.ID, nil, &map[string]any{}); code != http.StatusNotFound {
+		t.Fatalf("cross-user send status code=%d", code)
+	}
+}
+
 func TestSendQueueRecoversStaleSendingItems(t *testing.T) {
 	a := newTestApp(t)
 	stopTestWorkers(a)

apps/api/internal/app/public_api_handlers.go

@@ -0,0 +1,659 @@
+package app
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/go-chi/chi/v5"
+	"golang.org/x/crypto/bcrypt"
+)
+
+func (a *App) handlePublicAPIListDomains(w http.ResponseWriter, r *http.Request) {
+	rows, err := a.db.QueryContext(r.Context(), `SELECT id,name,status,dkim_selector,dkim_public_key,dns_status,dns_checked_at,created_at FROM domains ORDER BY name`)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to list domains")
+		return
+	}
+	defer rows.Close()
+	items := []Domain{}
+	for rows.Next() {
+		item, err := scanDomain(rows)
+		if err != nil {
+			respondError(w, http.StatusInternalServerError, "failed to scan domains")
+			return
+		}
+		items = append(items, item)
+	}
+	if err := rows.Err(); err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to list domains")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+func (a *App) handlePublicAPICreateDomain(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		Name string `json:"name"`
+	}
+	if err := decodeJSON(r, &req); err != nil {
+		badRequest(w, err)
+		return
+	}
+	id, err := a.createDomainTx(r.Context(), nil, req.Name)
+	if err != nil {
+		badRequest(w, err)
+		return
+	}
+	domain, err := a.domainByID(r.Context(), id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load domain")
+		return
+	}
+	respondJSON(w, http.StatusCreated, domain)
+}
+
+func (a *App) handlePublicAPIGetDomain(w http.ResponseWriter, r *http.Request) {
+	domain, err := a.domainByID(r.Context(), chi.URLParam(r, "id"))
+	if err != nil {
+		respondError(w, http.StatusNotFound, "domain not found")
+		return
+	}
+	respondJSON(w, http.StatusOK, domain)
+}
+
+func (a *App) handlePublicAPIUpdateDomain(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		Status string `json:"status"`
+	}
+	if err := decodeJSON(r, &req); err != nil {
+		badRequest(w, err)
+		return
+	}
+	status := strings.TrimSpace(req.Status)
+	if status != "active" && status != "disabled" {
+		badRequest(w, errors.New("invalid status"))
+		return
+	}
+	id := chi.URLParam(r, "id")
+	res, err := a.db.ExecContext(r.Context(), `UPDATE domains SET status=?, updated_at=? WHERE id=?`, status, a.now().UTC().Format(time.RFC3339Nano), id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to update domain")
+		return
+	}
+	if affected, _ := res.RowsAffected(); affected == 0 {
+		respondError(w, http.StatusNotFound, "domain not found")
+		return
+	}
+	domain, err := a.domainByID(r.Context(), id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load domain")
+		return
+	}
+	respondJSON(w, http.StatusOK, domain)
+}
+
+func (a *App) handlePublicAPIDeleteDomain(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	var count int
+	if err := a.db.QueryRowContext(r.Context(), `SELECT COUNT(*) FROM mailboxes WHERE domain_id=?`, id).Scan(&count); err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to check domain")
+		return
+	}
+	if count > 0 {
+		badRequest(w, errors.New("domain still has mailboxes"))
+		return
+	}
+	res, err := a.db.ExecContext(r.Context(), `DELETE FROM domains WHERE id=?`, id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to delete domain")
+		return
+	}
+	if affected, _ := res.RowsAffected(); affected == 0 {
+		respondError(w, http.StatusNotFound, "domain not found")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]any{"ok": true})
+}
+
+func (a *App) handlePublicAPIListMailboxes(w http.ResponseWriter, r *http.Request) {
+	rows, err := a.db.QueryContext(r.Context(), `SELECT mb.id,mb.user_id,u.email,mb.domain_id,mb.local_part,mb.address,mb.display_name,mb.quota_mb,mb.status,mb.created_at
+		FROM mailboxes mb JOIN users u ON u.id=mb.user_id ORDER BY mb.address`)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to list mailboxes")
+		return
+	}
+	defer rows.Close()
+	items := []Mailbox{}
+	for rows.Next() {
+		item, err := scanMailbox(rows)
+		if err != nil {
+			respondError(w, http.StatusInternalServerError, "failed to scan mailboxes")
+			return
+		}
+		items = append(items, item)
+	}
+	if err := rows.Err(); err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to list mailboxes")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]any{"items": items})
+}
+
+func (a *App) handlePublicAPICreateMailbox(w http.ResponseWriter, r *http.Request) {
+	var req struct {
+		DomainID    string `json:"domainId"`
+		LocalPart   string `json:"localPart"`
+		DisplayName string `json:"displayName"`
+		Password    string `json:"password"`
+		QuotaMB     int    `json:"quotaMb"`
+		OwnerEmail  string `json:"ownerEmail"`
+		UserID      string `json:"userId"`
+	}
+	if err := decodeJSON(r, &req); err != nil {
+		badRequest(w, err)
+		return
+	}
+	if err := requireString("domainId", req.DomainID); err != nil {
+		badRequest(w, err)
+		return
+	}
+	if err := requireString("localPart", req.LocalPart); err != nil {
+		badRequest(w, err)
+		return
+	}
+	if len(req.Password) < 8 {
+		badRequest(w, errors.New("password must be at least 8 characters"))
+		return
+	}
+	domain, err := a.domainByID(r.Context(), req.DomainID)
+	if err != nil {
+		respondError(w, http.StatusNotFound, "domain not found")
+		return
+	}
+	localPart := normalizeLocalPart(req.LocalPart)
+	if localPart == "" {
+		badRequest(w, errors.New("localPart is required"))
+		return
+	}
+	address := localPart + "@" + domain.Name
+	displayName := strings.TrimSpace(req.DisplayName)
+	if displayName == "" {
+		displayName = address
+	}
+	userID, err := a.resolveMailboxOwner(r, req.UserID, req.OwnerEmail, address, displayName, req.Password)
+	if err != nil {
+		respondMailboxOwnerError(w, err)
+		return
+	}
+	mailboxID, err := a.createMailbox(r.Context(), userID, req.DomainID, localPart, displayName, req.Password, req.QuotaMB, "active")
+	if err != nil {
+		badRequest(w, err)
+		return
+	}
+	mailbox, err := a.mailboxByID(r.Context(), mailboxID)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load mailbox")
+		return
+	}
+	respondJSON(w, http.StatusCreated, mailbox)
+}
+
+func (a *App) handlePublicAPIGetMailbox(w http.ResponseWriter, r *http.Request) {
+	mailbox, err := a.mailboxByID(r.Context(), chi.URLParam(r, "id"))
+	if err != nil {
+		respondError(w, http.StatusNotFound, "mailbox not found")
+		return
+	}
+	respondJSON(w, http.StatusOK, mailbox)
+}
+
+func (a *App) handlePublicAPIUpdateMailbox(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	current, err := a.mailboxByID(r.Context(), id)
+	if err != nil {
+		respondError(w, http.StatusNotFound, "mailbox not found")
+		return
+	}
+	var req struct {
+		DisplayName string `json:"displayName"`
+		QuotaMB     int    `json:"quotaMb"`
+		Status      string `json:"status"`
+		UserID      string `json:"userId"`
+	}
+	if err := decodeJSON(r, &req); err != nil {
+		badRequest(w, err)
+		return
+	}
+	displayName := strings.TrimSpace(req.DisplayName)
+	if displayName == "" {
+		displayName = current.DisplayName
+	}
+	quotaMB := req.QuotaMB
+	if quotaMB <= 0 {
+		quotaMB = current.QuotaMB
+	}
+	status := strings.TrimSpace(req.Status)
+	if status == "" {
+		status = current.Status
+	}
+	if status != "active" && status != "disabled" {
+		badRequest(w, errors.New("invalid status"))
+		return
+	}
+	userID := strings.TrimSpace(req.UserID)
+	if userID == "" {
+		userID = current.UserID
+	}
+	if err := a.ensureActiveUserExists(r.Context(), userID); err != nil {
+		respondMailboxOwnerError(w, err)
+		return
+	}
+	res, err := a.db.ExecContext(r.Context(), `UPDATE mailboxes SET user_id=?,display_name=?,quota_mb=?,status=?,updated_at=? WHERE id=?`,
+		userID, displayName, quotaMB, status, a.now().UTC().Format(time.RFC3339Nano), id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to update mailbox")
+		return
+	}
+	if affected, _ := res.RowsAffected(); affected == 0 {
+		respondError(w, http.StatusNotFound, "mailbox not found")
+		return
+	}
+	mailbox, err := a.mailboxByID(r.Context(), id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load mailbox")
+		return
+	}
+	respondJSON(w, http.StatusOK, mailbox)
+}
+
+func (a *App) handlePublicAPIDeleteMailbox(w http.ResponseWriter, r *http.Request) {
+	id := chi.URLParam(r, "id")
+	var owner string
+	if err := a.db.QueryRowContext(r.Context(), `SELECT user_id FROM mailboxes WHERE id=?`, id).Scan(&owner); err != nil {
+		respondError(w, http.StatusNotFound, "mailbox not found")
+		return
+	}
+	current := currentUser(r)
+	if current != nil && owner == current.ID {
+		var count int
+		if err := a.db.QueryRowContext(r.Context(), `SELECT COUNT(*) FROM mailboxes WHERE user_id=?`, owner).Scan(&count); err != nil {
+			respondError(w, http.StatusInternalServerError, "failed to check mailbox")
+			return
+		}
+		if count <= 1 {
+			badRequest(w, errors.New("cannot delete your last mailbox"))
+			return
+		}
+	}
+	rows, err := a.db.QueryContext(r.Context(), `SELECT id FROM messages WHERE mailbox_id=?`, id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load mailbox messages")
+		return
+	}
+	messageIDs := []string{}
+	for rows.Next() {
+		var messageID string
+		if rows.Scan(&messageID) == nil {
+			messageIDs = append(messageIDs, messageID)
+		}
+	}
+	rows.Close()
+	for _, messageID := range messageIDs {
+		a.deleteMessage(r.Context(), messageID)
+	}
+	res, err := a.db.ExecContext(r.Context(), `DELETE FROM mailboxes WHERE id=?`, id)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to delete mailbox")
+		return
+	}
+	if affected, _ := res.RowsAffected(); affected == 0 {
+		respondError(w, http.StatusNotFound, "mailbox not found")
+		return
+	}
+	respondJSON(w, http.StatusOK, map[string]any{"ok": true})
+}
+
+func (a *App) handlePublicAPISendMail(w http.ResponseWriter, r *http.Request) {
+	var req mailComposeInput
+	if err := decodeJSON(r, &req); err != nil {
+		badRequest(w, err)
+		return
+	}
+	mb, err := a.mailboxForCurrentUserWithID(r, req.MailboxID)
+	if err != nil {
+		respondError(w, http.StatusNotFound, "mailbox not found")
+		return
+	}
+	msg, err := a.sendMailNow(r.Context(), currentUser(r), mb, req)
+	if err != nil {
+		respondSendError(w, err)
+		return
+	}
+	status := publicAPISendStatusFromMessage(msg, mb.Address)
+	if msg.SendQueueID != "" {
+		if item, err := a.loadSendQueueEntryForUser(r.Context(), msg.SendQueueID, mb.UserID); err == nil {
+			status = publicAPISendStatusFromQueue(item, mb.Address)
+		}
+	} else {
+		item, err := a.loadLatestSendQueueForMailboxMessage(r.Context(), msg.ID, mb.ID)
+		if err == nil {
+			status = publicAPISendStatusFromQueue(item, mb.Address)
+		}
+	}
+	respondJSON(w, http.StatusCreated, status)
+}
+
+func (a *App) handlePublicAPISendStatus(w http.ResponseWriter, r *http.Request) {
+	user := currentUser(r)
+	id := strings.TrimSpace(chi.URLParam(r, "id"))
+	item, err := a.loadSendQueueEntryForUser(r.Context(), id, user.ID)
+	if err != nil {
+		item, err = a.loadSendQueueEntryForSentMessage(r.Context(), id, user.ID)
+	}
+	if err == nil {
+		mailboxAddress := ""
+		if mb, mbErr := a.mailboxByID(r.Context(), item.MailboxID); mbErr == nil {
+			mailboxAddress = mb.Address
+		}
+		respondJSON(w, http.StatusOK, publicAPISendStatusFromQueue(item, mailboxAddress))
+		return
+	}
+	msg, err := a.loadPublicAPISentMessageForUser(r.Context(), id, user.ID)
+	if err != nil {
+		respondError(w, http.StatusNotFound, "send item not found")
+		return
+	}
+	mailboxAddress := ""
+	if mb, mbErr := a.mailboxByID(r.Context(), msg.MailboxID); mbErr == nil {
+		mailboxAddress = mb.Address
+	}
+	respondJSON(w, http.StatusOK, publicAPISendStatusFromMessage(msg, mailboxAddress))
+}
+
+func (a *App) handlePublicAPIMailboxMessages(w http.ResponseWriter, r *http.Request) {
+	user := currentUser(r)
+	mailboxID := strings.TrimSpace(chi.URLParam(r, "id"))
+	if _, err := a.mailboxForUserByID(r.Context(), user.ID, mailboxID); err != nil {
+		respondError(w, http.StatusNotFound, "mailbox not found")
+		return
+	}
+	limit := parsePublicAPILimit(r, 30, 100)
+	offset := parsePublicAPIOffset(r)
+	folder := strings.TrimSpace(r.URL.Query().Get("folder"))
+	if folder == "" {
+		folder = "Inbox"
+	}
+	where := "m.mailbox_id=?"
+	args := []any{mailboxID}
+	if folder != "" && !strings.EqualFold(folder, "all") {
+		where += " AND lower(f.name)=lower(?)"
+		args = append(args, folder)
+	}
+	if q := strings.TrimSpace(r.URL.Query().Get("q")); q != "" {
+		where += " AND (m.subject LIKE ? OR m.from_addr LIKE ? OR m.from_name LIKE ? OR m.to_addrs LIKE ? OR m.snippet LIKE ? OR m.body_text LIKE ?)"
+		like := "%" + q + "%"
+		args = append(args, like, like, like, like, like, like)
+	}
+	args = append(args, limit+1, offset)
+	rows, err := a.db.QueryContext(r.Context(), `SELECT m.id,m.mailbox_id,m.folder_id,f.name,m.message_uid,m.imap_uid,m.imap_modseq,m.message_id,m.subject,m.from_addr,COALESCE(m.from_name,''),m.to_addrs,m.cc_addrs,m.bcc_addrs,m.sent_at,m.received_at,m.snippet,m.is_read,m.is_starred,m.has_attachments,m.size_bytes
+		FROM messages m JOIN folders f ON f.id=m.folder_id
+		WHERE `+where+`
+		ORDER BY m.received_at DESC LIMIT ? OFFSET ?`, args...)
+	if err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load messages")
+		return
+	}
+	defer rows.Close()
+	items := []MailMessage{}
+	for rows.Next() {
+		item, err := scanMessageSummary(rows)
+		if err != nil {
+			respondError(w, http.StatusInternalServerError, "failed to scan messages")
+			return
+		}
+		items = append(items, item)
+	}
+	if err := rows.Err(); err != nil {
+		respondError(w, http.StatusInternalServerError, "failed to load messages")
+		return
+	}
+	nextCursor := ""
+	if len(items) > limit {
+		items = items[:limit]
+		nextCursor = strconv.Itoa(offset + limit)
+	}
+	respondJSON(w, http.StatusOK, map[string]any{"items": items, "nextCursor": nextCursor})
+}
+
+type domainScanner interface{ Scan(dest ...any) error }
+
+func scanDomain(row domainScanner) (Domain, error) {
+	var item Domain
+	var checked sql.NullString
+	var created string
+	err := row.Scan(&item.ID, &item.Name, &item.Status, &item.DKIMSelector, &item.DKIMPublicKey, &item.DNSStatus, &checked, &created)
+	if err != nil {
+		return item, err
+	}
+	item.DNSCheckedAt = nullableTime(checked)
+	item.CreatedAt = parseTime(created)
+	return item, nil
+}
+
+type mailboxScanner interface{ Scan(dest ...any) error }
+
+func scanMailbox(row mailboxScanner) (Mailbox, error) {
+	var item Mailbox
+	var created string
+	err := row.Scan(&item.ID, &item.UserID, &item.UserEmail, &item.DomainID, &item.LocalPart, &item.Address, &item.DisplayName, &item.QuotaMB, &item.Status, &created)
+	if err != nil {
+		return item, err
+	}
+	item.CreatedAt = parseTime(created)
+	return item, nil
+}
+
+type publicAPISendStatus struct {
+	ID             string     `json:"id"`
+	QueueID        string     `json:"queueId,omitempty"`
+	Status         string     `json:"status"`
+	MessageID      string     `json:"messageId"`
+	RFCMessageID   string     `json:"rfcMessageId"`
+	MailboxID      string     `json:"mailboxId"`
+	MailboxAddress string     `json:"mailboxAddress,omitempty"`
+	Subject        string     `json:"subject,omitempty"`
+	Recipients     []string   `json:"recipients,omitempty"`
+	AttemptCount   int        `json:"attemptCount,omitempty"`
+	MaxAttempts    int        `json:"maxAttempts,omitempty"`
+	NextAttemptAt  *time.Time `json:"nextAttemptAt,omitempty"`
+	LastError      string     `json:"lastError,omitempty"`
+	CreatedAt      time.Time  `json:"createdAt"`
+	UpdatedAt      *time.Time `json:"updatedAt,omitempty"`
+	DeliveredAt    *time.Time `json:"deliveredAt,omitempty"`
+}
+
+func publicAPISendStatusFromQueue(item SendQueueEntry, mailboxAddress string) publicAPISendStatus {
+	return publicAPISendStatus{
+		ID:             item.ID,
+		QueueID:        item.ID,
+		Status:         item.Status,
+		MessageID:      item.SentMessageID,
+		RFCMessageID:   item.MessageID,
+		MailboxID:      item.MailboxID,
+		MailboxAddress: mailboxAddress,
+		Subject:        item.Subject,
+		Recipients:     item.Recipients,
+		AttemptCount:   item.AttemptCount,
+		MaxAttempts:    item.MaxAttempts,
+		NextAttemptAt:  timePtr(item.NextAttemptAt),
+		LastError:      item.LastError,
+		CreatedAt:      item.CreatedAt,
+		UpdatedAt:      timePtr(item.UpdatedAt),
+		DeliveredAt:    item.DeliveredAt,
+	}
+}
+
+func publicAPISendStatusFromMessage(msg *MailMessage, mailboxAddress string) publicAPISendStatus {
+	recipients := append(append([]string{}, msg.To...), msg.CC...)
+	recipients = append(recipients, msg.BCC...)
+	return publicAPISendStatus{
+		ID:             msg.ID,
+		Status:         sendAuditAccepted,
+		MessageID:      msg.ID,
+		RFCMessageID:   msg.MessageID,
+		MailboxID:      msg.MailboxID,
+		MailboxAddress: mailboxAddress,
+		Subject:        msg.Subject,
+		Recipients:     dedupeEmails(recipients),
+		CreatedAt:      msg.ReceivedAt,
+	}
+}
+
+func timePtr(t time.Time) *time.Time {
+	if t.IsZero() {
+		return nil
+	}
+	return &t
+}
+
+func (a *App) resolveMailboxOwner(r *http.Request, userID, ownerEmail, address, displayName, password string) (string, error) {
+	userID = strings.TrimSpace(userID)
+	if userID != "" {
+		if err := a.ensureActiveUserExists(r.Context(), userID); err != nil {
+			return "", err
+		}
+		return userID, nil
+	}
+	email := normalizeEmail(ownerEmail)
+	if email == "" {
+		email = address
+	}
+	if !strings.Contains(email, "@") {
+		return "", errors.New("invalid owner email")
+	}
+	var existing string
+	err := a.db.QueryRowContext(r.Context(), `SELECT id FROM users WHERE email=? AND disabled=0`, email).Scan(&existing)
+	if err == nil {
+		return existing, nil
+	}
+	if !errors.Is(err, sql.ErrNoRows) {
+		return "", err
+	}
+	return a.createMailboxOwnerUser(r, email, displayName, password)
+}
+
+func (a *App) createMailboxOwnerUser(r *http.Request, email, displayName, password string) (string, error) {
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return "", err
+	}
+	userID := newID("usr")
+	now := a.now().UTC().Format(time.RFC3339Nano)
+	if displayName == "" {
+		displayName = email
+	}
+	_, err = a.db.ExecContext(r.Context(), `INSERT INTO users(id,email,display_name,role,password_hash,disabled,created_at,updated_at)
+		VALUES(?,?,?,?,?,?,?,?)`, userID, email, displayName, "user", string(hash), 0, now, now)
+	if err != nil {
+		return "", err
+	}
+	return userID, nil
+}
+
+func (a *App) ensureActiveUserExists(ctx context.Context, userID string) error {
+	var disabled int
+	if err := a.db.QueryRowContext(ctx, `SELECT disabled FROM users WHERE id=?`, userID).Scan(&disabled); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return errNotFound
+		}
+		return err
+	}
+	if intBool(disabled) {
+		return errors.New("owner user is disabled")
+	}
+	return nil
+}
+
+func respondMailboxOwnerError(w http.ResponseWriter, err error) {
+	if errors.Is(err, errNotFound) {
+		respondError(w, http.StatusNotFound, "owner user not found")
+		return
+	}
+	if err != nil {
+		badRequest(w, err)
+		return
+	}
+}
+
+func respondSendError(w http.ResponseWriter, err error) {
+	switch {
+	case errors.Is(err, errNoRecipients), errors.Is(err, errInvalidMIME), errors.Is(err, errAttachmentTooLarge):
+		badRequest(w, err)
+	case errors.Is(err, errSMTPRateLimited):
+		respondError(w, http.StatusTooManyRequests, err.Error())
+	case errors.Is(err, errSenderNotAuthorized):
+		respondError(w, http.StatusForbidden, err.Error())
+	case errors.Is(err, errMailboxQuotaExceeded):
+		respondError(w, http.StatusInsufficientStorage, err.Error())
+	default:
+		respondError(w, http.StatusInternalServerError, err.Error())
+	}
+}
+
+func (a *App) loadLatestSendQueueForMessage(ctx context.Context, sentMessageID, userID string) (SendQueueEntry, error) {
+	row := a.db.QueryRowContext(ctx, `SELECT sq.id,sq.mailbox_id,sq.sent_message_id,sq.message_id,COALESCE(m.subject,''),sq.source,sq.mail_from,sq.header_from,sq.recipients_json,sq.status,sq.attempt_count,sq.max_attempts,sq.next_attempt_at,sq.last_error,sq.created_at,sq.updated_at,sq.delivered_at
+		FROM send_queue sq JOIN mailboxes mb ON mb.id=sq.mailbox_id LEFT JOIN messages m ON m.id=sq.sent_message_id
+		WHERE sq.sent_message_id=? AND mb.user_id=? ORDER BY sq.created_at DESC, sq.id DESC LIMIT 1`, sentMessageID, userID)
+	return scanSendQueueEntry(row)
+}
+
+func (a *App) loadLatestSendQueueForMailboxMessage(ctx context.Context, sentMessageID, mailboxID string) (SendQueueEntry, error) {
+	row := a.db.QueryRowContext(ctx, `SELECT sq.id,sq.mailbox_id,sq.sent_message_id,sq.message_id,COALESCE(m.subject,''),sq.source,sq.mail_from,sq.header_from,sq.recipients_json,sq.status,sq.attempt_count,sq.max_attempts,sq.next_attempt_at,sq.last_error,sq.created_at,sq.updated_at,sq.delivered_at
+		FROM send_queue sq LEFT JOIN messages m ON m.id=sq.sent_message_id
+		WHERE sq.sent_message_id=? AND sq.mailbox_id=? ORDER BY sq.created_at DESC, sq.id DESC LIMIT 1`, sentMessageID, mailboxID)
+	return scanSendQueueEntry(row)
+}
+
+func (a *App) loadSendQueueEntryForSentMessage(ctx context.Context, sentMessageID, userID string) (SendQueueEntry, error) {
+	return a.loadLatestSendQueueForMessage(ctx, sentMessageID, userID)
+}
+
+func (a *App) loadPublicAPISentMessageForUser(ctx context.Context, id, userID string) (*MailMessage, error) {
+	var messageID string
+	err := a.db.QueryRowContext(ctx, `SELECT m.id
+		FROM messages m JOIN mailboxes mb ON mb.id=m.mailbox_id JOIN folders f ON f.id=m.folder_id
+		WHERE (m.id=? OR m.message_id=?) AND mb.user_id=? AND lower(f.name)='sent'
+		ORDER BY m.received_at DESC LIMIT 1`, id, id, userID).Scan(&messageID)
+	if err != nil {
+		return nil, err
+	}
+	return a.messageByID(ctx, messageID, false)
+}
+
+func parsePublicAPILimit(r *http.Request, defaultLimit, maxLimit int) int {
+	limit, err := strconv.Atoi(r.URL.Query().Get("limit"))
+	if err != nil || limit <= 0 {
+		return defaultLimit
+	}
+	if limit > maxLimit {
+		return maxLimit
+	}
+	return limit
+}
+
+func parsePublicAPIOffset(r *http.Request) int {
+	cursor := strings.TrimSpace(r.URL.Query().Get("cursor"))
+	if cursor == "" {
+		return 0
+	}
+	offset, err := strconv.Atoi(cursor)
+	if err != nil || offset < 0 {
+		return 0
+	}
+	return offset
+}

apps/api/internal/app/router_auth.go

@@ -37,6 +37,10 @@ func (a *App) Router() http.Handler {
 		r.With(a.requireAuth).Get("/me", a.handleMe)
 		r.With(a.requireAuth).Post("/me/profile", a.handleUpdateProfile)
 		r.With(a.requireAuth).Post("/me/password", a.handleChangePassword)
+		r.With(a.requireAuth).Get("/me/api-tokens", a.handleListAPITokens)
+		r.With(a.requireAuth).Post("/me/api-tokens", a.handleCreateAPIToken)
+		r.With(a.requireAuth).Post("/me/api-tokens/{id}", a.handleUpdateAPIToken)
+		r.With(a.requireAuth).Delete("/me/api-tokens/{id}", a.handleDeleteAPIToken)
 		r.With(a.requireAuth, a.requirePermission(PermissionMailboxApply)).Get("/me/mailbox-apply-options", a.handleMailboxApplyOptions)
 		r.With(a.requireAuth, a.requirePermission(PermissionMailboxApply)).Post("/me/mailboxes/apply", a.handleApplyMailbox)
 		r.With(a.requireAuth).Post("/me/2fa/setup", a.handleTwoFactorSetup)
@@ -71,6 +75,23 @@ func (a *App) Router() http.Handler {
 		r.With(a.requireExternalIMAPEnabled).Get("/external-imap-oauth/{provider}/callback", a.handleExternalIMAPOAuthCallback)
 		r.With(a.requireAuth).Get("/events", a.handleEvents)
 
+		r.Group(func(r chi.Router) {
+			r.Use(a.requireAPIToken)
+			r.With(a.requireAdminAccess, a.requireAnyPermission(PermissionDomainsView, PermissionDNSView, PermissionMailboxesView, PermissionAliasesView, PermissionSettingsView, PermissionTemplatesView)).Get("/open/domains", a.handlePublicAPIListDomains)
+			r.With(a.requireAdminAccess, a.requirePermission(PermissionDomainsCreate)).Post("/open/domains", a.handlePublicAPICreateDomain)
+			r.With(a.requireAdminAccess, a.requireAnyPermission(PermissionDomainsView, PermissionDNSView, PermissionMailboxesView, PermissionAliasesView, PermissionSettingsView, PermissionTemplatesView)).Get("/open/domains/{id}", a.handlePublicAPIGetDomain)
+			r.With(a.requireAdminAccess, a.requirePermission(PermissionDomainsUpdate)).Post("/open/domains/{id}", a.handlePublicAPIUpdateDomain)
+			r.With(a.requireAdminAccess, a.requirePermission(PermissionDomainsDelete)).Delete("/open/domains/{id}", a.handlePublicAPIDeleteDomain)
+			r.With(a.requireAdminAccess, a.requireAnyPermission(PermissionMailboxesView, PermissionMessagesView)).Get("/open/mailboxes", a.handlePublicAPIListMailboxes)
+			r.With(a.requireAdminAccess, a.requirePermission(PermissionMailboxesCreate)).Post("/open/mailboxes", a.handlePublicAPICreateMailbox)
+			r.With(a.requireAdminAccess, a.requireAnyPermission(PermissionMailboxesView, PermissionMessagesView)).Get("/open/mailboxes/{id}", a.handlePublicAPIGetMailbox)
+			r.With(a.requireAdminAccess, a.requirePermission(PermissionMailboxesUpdate)).Post("/open/mailboxes/{id}", a.handlePublicAPIUpdateMailbox)
+			r.With(a.requireAdminAccess, a.requirePermission(PermissionMailboxesDelete)).Delete("/open/mailboxes/{id}", a.handlePublicAPIDeleteMailbox)
+			r.With(a.requirePermission(PermissionMailSend)).Post("/open/send", a.handlePublicAPISendMail)
+			r.With(a.requirePermission(PermissionMailRead)).Get("/open/send/{id}", a.handlePublicAPISendStatus)
+			r.With(a.requirePermission(PermissionMailRead)).Get("/open/mailboxes/{id}/messages", a.handlePublicAPIMailboxMessages)
+		})
+
 		r.Group(func(r chi.Router) {
 			r.Use(a.requireAuth)
 			r.With(a.requirePermission(PermissionMailAccess)).Get("/mail/mailboxes", a.handleMyMailboxes)
@@ -165,7 +186,7 @@ func (a *App) corsMiddleware(next http.Handler) http.Handler {
 			w.Header().Set("Access-Control-Allow-Origin", origin)
 			w.Header().Set("Vary", "Origin")
 			w.Header().Set("Access-Control-Allow-Credentials", "true")
-			w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
+			w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
 			w.Header().Set("Access-Control-Allow-Methods", "GET,POST,DELETE,OPTIONS")
 		}
 		if r.Method == http.MethodOptions {
@@ -187,6 +208,17 @@ func (a *App) requireAuth(next http.Handler) http.Handler {
 	})
 }
 
+func (a *App) requireAPIToken(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		user, err := a.authenticateAPIToken(r)
+		if err != nil {
+			respondError(w, http.StatusUnauthorized, "api token required")
+			return
+		}
+		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), userContextKey, user)))
+	})
+}
+
 func currentUser(r *http.Request) *User {
 	user, _ := r.Context().Value(userContextKey).(*User)
 	return user
@@ -218,6 +250,43 @@ func (a *App) authenticateRequest(r *http.Request) (*User, error) {
 	return &u, nil
 }
 
+func (a *App) authenticateAPIToken(r *http.Request) (*User, error) {
+	token := bearerToken(r)
+	if token == "" {
+		return nil, errors.New("no api token")
+	}
+	now := a.now().UTC().Format(time.RFC3339Nano)
+	row := a.db.QueryRowContext(r.Context(), `SELECT at.id,u.id,u.email,u.display_name,u.role,u.disabled,u.two_factor_enabled,u.created_at
+		FROM api_tokens at JOIN users u ON u.id=at.user_id
+		WHERE at.token_hash=? AND at.disabled=0 AND (at.expires_at IS NULL OR at.expires_at > ?)`, hashToken(token), now)
+	var tokenID string
+	var u User
+	var disabled, twoFactorEnabled int
+	var created string
+	if err := row.Scan(&tokenID, &u.ID, &u.Email, &u.DisplayName, &u.Role, &disabled, &twoFactorEnabled, &created); err != nil {
+		return nil, err
+	}
+	u.Disabled = intBool(disabled)
+	u.TwoFactorEnabled = intBool(twoFactorEnabled)
+	u.CreatedAt = parseTime(created)
+	if u.Disabled {
+		return nil, errors.New("disabled")
+	}
+	if err := a.attachUserAuthorization(r.Context(), &u); err != nil {
+		return nil, err
+	}
+	_, _ = a.db.ExecContext(r.Context(), `UPDATE api_tokens SET last_used_at=? WHERE id=?`, now, tokenID)
+	return &u, nil
+}
+
+func bearerToken(r *http.Request) string {
+	fields := strings.Fields(strings.TrimSpace(r.Header.Get("Authorization")))
+	if len(fields) != 2 || !strings.EqualFold(fields[0], "Bearer") {
+		return ""
+	}
+	return fields[1]
+}
+
 func (a *App) userByEmail(ctx context.Context, email string) (*User, string, error) {
 	row := a.db.QueryRowContext(ctx, `SELECT id,email,display_name,role,password_hash,disabled,two_factor_enabled,created_at FROM users WHERE email=?`, email)
 	var u User

apps/api/internal/app/types.go

@@ -23,6 +23,16 @@ type AdminUser struct {
 	Mailboxes    []string `json:"mailboxes"`
 }
 
+type APIToken struct {
+	ID         string     `json:"id"`
+	Name       string     `json:"name"`
+	LastUsedAt *time.Time `json:"lastUsedAt,omitempty"`
+	ExpiresAt  *time.Time `json:"expiresAt,omitempty"`
+	Disabled   bool       `json:"disabled"`
+	CreatedAt  time.Time  `json:"createdAt"`
+	UpdatedAt  time.Time  `json:"updatedAt"`
+}
+
 type Domain struct {
 	ID            string     `json:"id"`
 	Name          string     `json:"name"`