{
  "openapi": "3.1.0",
  "info": {
    "title": "Mail API",
    "version": "1.60",
    "description": "The Mail Developer API powers inbox control, smart email triage, transactional data extraction, search, and draft management.\n\nHosted at `dev.txnal.com` and powering integrations, mobile shells, and autonomous AI agents.",
    "contact": {
      "name": "Mail API Support",
      "url": "https://dev.txnal.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://mail.txnal.com",
      "description": "Production API Server"
    },
    {
      "url": "https://dev.txnal.com",
      "description": "Developer Portal & Gateway"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local Development Server"
    }
  ],
  "tags": [
    {
      "name": "Authentication",
      "description": "Token exchange, rotation, and session revocation"
    },
    {
      "name": "User Profile",
      "description": "Current user profile, preferences, permissions, and email accounts"
    },
    {
      "name": "Emails",
      "description": "Query, view, thread, triage, and send emails"
    },
    {
      "name": "Drafts",
      "description": "Draft creation, modification, deletion, and sending"
    },
    {
      "name": "Bundles",
      "description": "Inbox bundle organization and unseen counts"
    },
    {
      "name": "Search",
      "description": "Full-text email search and auto-complete suggestions"
    }
  ],
  "paths": {
    "/api/v1/auth/token": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Mint or rotate access token",
        "description": "Exchanges an active refresh token for a newly minted 5-minute access token and a rotated 7-day refresh token. Implements standard OAuth 2.0 refresh_token grant.",
        "operationId": "createAuthToken",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthTokenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token successfully minted and rotated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported grant type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid, expired, or revoked refresh token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/tokens": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Mint or rotate access token (alias)",
        "description": "Backward-compatible alias for `/api/v1/auth/token`.",
        "operationId": "createAuthTokensAlias",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthTokenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token successfully minted and rotated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/rotate": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Rotate refresh and access token (alias)",
        "description": "Backward-compatible alias for `/api/v1/auth/token`.",
        "operationId": "rotateAuthTokenAlias",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthTokenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token successfully rotated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/auth/revoke": {
      "post": {
        "tags": [
          "Authentication"
        ],
        "summary": "Revoke client session",
        "description": "Revokes the active client session matching the provided access token or refresh token.",
        "operationId": "revokeAuthSession",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthRevokeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session successfully revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Client session successfully revoked"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing token parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Session record not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Authentication"
        ],
        "summary": "Revoke client session",
        "description": "Revokes the active client session matching the provided access token or refresh token.",
        "operationId": "deleteAuthSession",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthRevokeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session successfully revoked",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Client session successfully revoked"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing token parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Session record not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "tags": [
          "User Profile"
        ],
        "summary": "Get current user profile & session",
        "description": "Returns the authenticated user's details, timezone/theme preferences, permission flags (including `user_api`), active email accounts, and current client session metadata.",
        "operationId": "getCurrentUser",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "User profile information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User lacks user_api permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/emails": {
      "get": {
        "tags": [
          "Emails"
        ],
        "summary": "List emails",
        "description": "Returns a paginated list of emails belonging to the user's active email accounts, ordered by received date descending. Supports filtering by bundle, seen status, snoozed state, category, and starred status.",
        "operationId": "listEmails",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "bundle_id",
            "in": "query",
            "description": "Filter by bundle ID",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "seen",
            "in": "query",
            "description": "Filter by read/seen status",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "include_snoozed",
            "in": "query",
            "description": "Set to 'true' to include currently snoozed messages (unsnoozed by default)",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by email category",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "starred",
            "in": "query",
            "description": "Filter by starred status",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (1-indexed)",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "description": "Results per page (1 to 100)",
            "schema": {
              "type": "integer",
              "default": 25,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of emails",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/emails/{id}": {
      "get": {
        "tags": [
          "Emails"
        ],
        "summary": "Get email detail with transactional extractions",
        "description": "Returns the complete email message details, RFC headers, body HTML/text, and extracted transactional structured data fields.",
        "operationId": "getEmail",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Email Message ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Email details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "$ref": "#/components/schemas/EmailDetail"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Email not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/emails/{id}/thread": {
      "get": {
        "tags": [
          "Emails"
        ],
        "summary": "Get full conversation thread",
        "description": "Retrieves all conversation messages in chronological order belonging to the specified email message's thread.",
        "operationId": "getEmailThread",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Email Message ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Thread details and conversation history",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadResponse"
                }
              }
            }
          },
          "404": {
            "description": "Email or thread not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/emails/{id}/triage": {
      "patch": {
        "tags": [
          "Emails"
        ],
        "summary": "Triage an email message",
        "description": "Performs triage updates on an email: mark seen/unseen, star/unstar, snooze thread until a specific datetime with soft/hard wake rules, update bundle assignments, or re-categorize.",
        "operationId": "triageEmail",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Email Message ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TriageRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Triage action successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "email": {
                      "$ref": "#/components/schemas/EmailSummary"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Email not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/emails/send": {
      "post": {
        "tags": [
          "Emails"
        ],
        "summary": "Send or queue an email for delivery",
        "description": "Queues an email message for delivery through Gmail API using the specified or default active email account.",
        "operationId": "sendEmailMessage",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailSendRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email queued for delivery",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Email queued for delivery"
                    },
                    "draft_id": {
                      "type": "integer",
                      "example": 42
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing required recipient or parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/drafts": {
      "get": {
        "tags": [
          "Drafts"
        ],
        "summary": "List active email drafts",
        "description": "Returns all pending email drafts for the current user across active email accounts, ordered by last update descending.",
        "operationId": "listDrafts",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of drafts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "drafts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EmailDraft"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Drafts"
        ],
        "summary": "Create a new email draft",
        "description": "Creates an email draft in 'draft' status.",
        "operationId": "createDraft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DraftCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Draft created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "draft": {
                      "$ref": "#/components/schemas/EmailDraft"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/drafts/{id}": {
      "get": {
        "tags": [
          "Drafts"
        ],
        "summary": "Get email draft details",
        "operationId": "getDraft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Draft ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Draft details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "draft": {
                      "$ref": "#/components/schemas/EmailDraft"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Draft not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Drafts"
        ],
        "summary": "Update an existing email draft",
        "operationId": "updateDraft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Draft ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DraftUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated draft",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "draft": {
                      "$ref": "#/components/schemas/EmailDraft"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Draft not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Drafts"
        ],
        "summary": "Delete an email draft",
        "operationId": "deleteDraft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Draft ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Draft successfully deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Draft successfully deleted"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Draft not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/drafts/{id}/send": {
      "post": {
        "tags": [
          "Drafts"
        ],
        "summary": "Send a saved email draft",
        "description": "Transitions the draft status to 'queued' and enqueues SendGmailMessageJob for delivery.",
        "operationId": "sendDraft",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Draft ID",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Draft queued for sending",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Draft queued for sending"
                    },
                    "draft_id": {
                      "type": "integer",
                      "example": 101
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Draft lacks valid recipients",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Draft not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/bundles": {
      "get": {
        "tags": [
          "Bundles"
        ],
        "summary": "List user bundles",
        "description": "Returns all organizational bundles defined for the user with calculated counts of unsnoozed, unseen messages.",
        "operationId": "listBundles",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "List of bundles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bundles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Bundle"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Search emails and entities",
        "description": "Executes full-text and entity search across the user's emails and bundles via SearchService.",
        "operationId": "searchEmails",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query term",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return (1 to 100)",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search/suggestions": {
      "get": {
        "tags": [
          "Search"
        ],
        "summary": "Get search autocomplete suggestions",
        "description": "Returns fast prefix-based search suggestions for senders, bundles, and keywords.",
        "operationId": "getSearchSuggestions",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "prefix",
            "in": "query",
            "required": true,
            "description": "Prefix characters entered by user",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of suggestion strings",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prefix": {
                      "type": "string",
                      "example": "ord"
                    },
                    "suggestions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "order",
                        "orders",
                        "order confirmation"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Short-lived JWT Access Token minted via `/api/v1/auth/token`. Include in HTTP header: `Authorization: Bearer <access_token>`."
      }
    },
    "schemas": {
      "AuthTokenRequest": {
        "type": "object",
        "required": [
          "refresh_token"
        ],
        "properties": {
          "grant_type": {
            "type": "string",
            "default": "refresh_token",
            "enum": [
              "refresh_token"
            ],
            "example": "refresh_token"
          },
          "refresh_token": {
            "type": "string",
            "description": "JWT refresh token previously minted by client session",
            "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
          }
        }
      },
      "AuthTokenResponse": {
        "type": "object",
        "properties": {
          "token_type": {
            "type": "string",
            "example": "Bearer"
          },
          "access_token": {
            "type": "string",
            "description": "Short-lived 5-minute JWT Access Token",
            "example": "eyJhbGciOi..."
          },
          "expires_in": {
            "type": "integer",
            "description": "Access token lifetime in seconds (default: 300)",
            "example": 300
          },
          "refresh_token": {
            "type": "string",
            "description": "Rotated 7-day JWT Refresh Token for next rotation",
            "example": "eyJhbGciOi..."
          },
          "refresh_token_expires_in": {
            "type": "integer",
            "description": "Refresh token lifetime in seconds (default: 604800)",
            "example": 604800
          },
          "token_id": {
            "type": "integer",
            "description": "Internal client session ID",
            "example": 12
          },
          "client_name": {
            "type": "string",
            "example": "iPhone Native Client"
          }
        }
      },
      "AuthRevokeRequest": {
        "type": "object",
        "properties": {
          "refresh_token": {
            "type": "string",
            "description": "Optional raw refresh token to revoke if not revoking via Authorization header"
          }
        }
      },
      "MeResponse": {
        "type": "object",
        "properties": {
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 1
              },
              "email": {
                "type": "string",
                "example": "user@example.com"
              },
              "admin": {
                "type": "boolean",
                "example": false
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "preferences": {
            "type": "object",
            "nullable": true,
            "properties": {
              "timezone": {
                "type": "string",
                "example": "America/Chicago"
              },
              "theme": {
                "type": "string",
                "example": "system"
              },
              "time_format": {
                "type": "string",
                "example": "12h"
              },
              "date_format": {
                "type": "string",
                "example": "MM/DD/YYYY"
              },
              "start_of_day": {
                "type": "string",
                "example": "08:00"
              },
              "start_of_week": {
                "type": "string",
                "example": "sunday"
              }
            }
          },
          "permissions": {
            "type": "object",
            "nullable": true,
            "properties": {
              "admin": {
                "type": "boolean",
                "example": false
              },
              "user_ui": {
                "type": "boolean",
                "example": true
              },
              "user_api": {
                "type": "boolean",
                "example": true
              }
            }
          },
          "email_accounts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer",
                  "example": 5
                },
                "provider": {
                  "type": "string",
                  "example": "google"
                },
                "email_address": {
                  "type": "string",
                  "example": "user@gmail.com"
                },
                "sync_status": {
                  "type": "string",
                  "example": "idle"
                }
              }
            }
          },
          "client_session": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer",
                "example": 14
              },
              "client_name": {
                "type": "string",
                "example": "Mobile Client"
              },
              "client_type": {
                "type": "string",
                "example": "ios"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "EmailSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 101
          },
          "email_account_id": {
            "type": "integer",
            "example": 2
          },
          "email_thread_id": {
            "type": "integer",
            "example": 88
          },
          "sender_address": {
            "type": "string",
            "example": "receipts@order.amazon.com"
          },
          "sender_name": {
            "type": "string",
            "example": "Amazon.com Orders"
          },
          "to_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "user@example.com"
            ]
          },
          "subject": {
            "type": "string",
            "example": "Your Amazon.com order #112-9876543-1234567"
          },
          "snippet": {
            "type": "string",
            "example": "Thank you for your order! Your items will arrive tomorrow..."
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "seen": {
            "type": "boolean",
            "example": false
          },
          "starred": {
            "type": "boolean",
            "example": false
          },
          "category": {
            "type": "string",
            "example": "Orders & Delivery"
          },
          "subcategory": {
            "type": "string",
            "example": "receipt"
          },
          "snoozed_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "bundle_ids": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              3
            ]
          }
        }
      },
      "EmailDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 101
          },
          "email_account_id": {
            "type": "integer",
            "example": 2
          },
          "email_thread_id": {
            "type": "integer",
            "example": 88
          },
          "sender_address": {
            "type": "string",
            "example": "receipts@order.amazon.com"
          },
          "sender_name": {
            "type": "string",
            "example": "Amazon.com Orders"
          },
          "to_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "user@example.com"
            ]
          },
          "subject": {
            "type": "string",
            "example": "Your Amazon.com order #112-9876543-1234567"
          },
          "snippet": {
            "type": "string",
            "example": "Thank you for your order! Your items will arrive tomorrow..."
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "seen": {
            "type": "boolean",
            "example": false
          },
          "starred": {
            "type": "boolean",
            "example": false
          },
          "category": {
            "type": "string",
            "example": "Orders & Delivery"
          },
          "subcategory": {
            "type": "string",
            "example": "receipt"
          },
          "snoozed_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "bundle_ids": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "example": [
              3
            ]
          },
          "body_text": {
            "type": "string"
          },
          "body_html": {
            "type": "string"
          },
          "rfc_message_id": {
            "type": "string"
          },
          "extractions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExtractedField"
            }
          }
        }
      },
      "ThreadMessage": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 101
          },
          "sender_address": {
            "type": "string",
            "example": "sender@domain.com"
          },
          "sender_name": {
            "type": "string",
            "example": "Sender Name"
          },
          "to_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "seen": {
            "type": "boolean"
          },
          "snippet": {
            "type": "string"
          },
          "body_text": {
            "type": "string"
          },
          "body_html": {
            "type": "string"
          },
          "extractions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExtractedField"
            }
          }
        }
      },
      "ExtractedField": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "total_price"
          },
          "value": {
            "type": "string",
            "example": "$49.99"
          },
          "is_pinned": {
            "type": "boolean",
            "example": true
          }
        }
      },
      "EmailListResponse": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "example": 1
          },
          "per_page": {
            "type": "integer",
            "example": 25
          },
          "total_count": {
            "type": "integer",
            "example": 142
          },
          "emails": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailSummary"
            }
          }
        }
      },
      "ThreadResponse": {
        "type": "object",
        "properties": {
          "thread_id": {
            "type": "integer",
            "example": 44
          },
          "gmail_thread_id": {
            "type": "string",
            "example": "18e192a9ef0234a1"
          },
          "subject": {
            "type": "string",
            "example": "Discussion on API design"
          },
          "snoozed_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "snooze_type": {
            "type": "string",
            "enum": [
              "soft",
              "hard"
            ],
            "nullable": true
          },
          "message_count": {
            "type": "integer",
            "example": 3
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ThreadMessage"
            }
          }
        }
      },
      "TriageRequest": {
        "type": "object",
        "properties": {
          "seen": {
            "type": "boolean",
            "description": "Update read/seen state"
          },
          "starred": {
            "type": "boolean",
            "description": "Star or unstar message"
          },
          "snoozed_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "Snooze thread until datetime. Pass null to unsnooze."
          },
          "snooze_type": {
            "type": "string",
            "enum": [
              "soft",
              "hard"
            ],
            "default": "soft",
            "description": "Soft snooze wakes on new incoming messages; hard snooze remains asleep until time."
          },
          "bundle_ids": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "List of bundle IDs to assign to this message"
          },
          "category": {
            "type": "string",
            "description": "Category name"
          },
          "subcategory": {
            "type": "string",
            "description": "Subcategory name"
          }
        }
      },
      "EmailSendRequest": {
        "type": "object",
        "required": [
          "to_recipients"
        ],
        "properties": {
          "email_account_id": {
            "type": "integer",
            "description": "Account ID to send from. Defaults to primary active account."
          },
          "to_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "client@example.com"
            ]
          },
          "cc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bcc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "subject": {
            "type": "string",
            "example": "Meeting Follow-up"
          },
          "body_text": {
            "type": "string",
            "example": "Thanks for speaking earlier today!"
          },
          "body_html": {
            "type": "string",
            "description": "Optional HTML representation; auto-generated from body_text if omitted."
          },
          "reply_to_message_id": {
            "type": "integer",
            "description": "Message ID this is in reply to."
          }
        }
      },
      "EmailDraft": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 12
          },
          "email_account_id": {
            "type": "integer",
            "example": 2
          },
          "email_thread_id": {
            "type": "integer",
            "nullable": true
          },
          "reply_to_message_id": {
            "type": "integer",
            "nullable": true
          },
          "subject": {
            "type": "string",
            "example": "Quarterly Review"
          },
          "to_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bcc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "body_text": {
            "type": "string"
          },
          "body_html": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "queued",
              "sent",
              "failed"
            ],
            "example": "draft"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DraftCreateRequest": {
        "type": "object",
        "properties": {
          "email_account_id": {
            "type": "integer"
          },
          "subject": {
            "type": "string"
          },
          "body_text": {
            "type": "string"
          },
          "body_html": {
            "type": "string"
          },
          "to_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bcc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reply_to_message_id": {
            "type": "integer"
          }
        }
      },
      "DraftUpdateRequest": {
        "type": "object",
        "properties": {
          "subject": {
            "type": "string"
          },
          "body_text": {
            "type": "string"
          },
          "body_html": {
            "type": "string"
          },
          "to_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "bcc_recipients": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reply_to_message_id": {
            "type": "integer"
          }
        }
      },
      "Bundle": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 4
          },
          "name": {
            "type": "string",
            "example": "Amazon"
          },
          "bundle_type": {
            "type": "string",
            "enum": [
              "standard",
              "dont_extract"
            ],
            "example": "standard"
          },
          "pinned": {
            "type": "boolean",
            "example": true
          },
          "unseen_count": {
            "type": "integer",
            "example": 2
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "example": "invoice"
          },
          "total": {
            "type": "integer",
            "example": 8
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "integer"
                },
                "subject": {
                  "type": "string"
                },
                "sender_name": {
                  "type": "string"
                },
                "snippet": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "unauthorized"
          },
          "message": {
            "type": "string",
            "example": "Detailed reason for the error"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          }
        }
      }
    }
  }
}