agentmail-clone-v1 0.1.0

package/openapi/openapi.yaml

@@ -0,0 +1,1016 @@
+openapi: 3.0.3
+info:
+  title: EmailAgent API
+  version: 1.0.0
+  license:
+    name: Proprietary
+    url: https://emailagent.dev/legal/terms
+  description: |
+    API for creating agent inboxes, sending emails, managing custom domains,
+    managing API keys, and reading usage metrics.
+
+    Authentication uses API keys via `Authorization: Bearer <api_key>`.
+
+    For mutating endpoints, send an optional `Idempotency-Key` header.
+    - Replaying the same key with the same payload returns the original response.
+    - Reusing a key with a different payload returns `409`.
+servers:
+  - url: http://127.0.0.1:3000
+    description: Local
+  - url: https://api.emailagent.dev
+    description: Production
+tags:
+  - name: Inboxes
+    description: Manage organization inboxes.
+  - name: Emails
+    description: Send and manage inbox email records.
+  - name: Domains
+    description: Create, verify, and delete custom domains.
+  - name: API Keys
+    description: Create and manage API keys and scopes.
+  - name: Metrics
+    description: Read plan usage metrics.
+security:
+  - bearerAuth: []
+paths:
+  /api/v1/inboxes:
+    get:
+      tags: [Inboxes]
+      summary: List inboxes
+      operationId: listInboxes
+      responses:
+        '200':
+          description: Inboxes for the authenticated organization
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InboxListResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+    post:
+      tags: [Inboxes]
+      summary: Create inbox
+      operationId: createInbox
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateInboxRequest'
+      responses:
+        '201':
+          description: Inbox created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InboxResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          description: Plan limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/v1/inboxes/{id}:
+    patch:
+      tags: [Inboxes]
+      summary: Update inbox display name
+      operationId: updateInbox
+      parameters:
+        - $ref: '#/components/parameters/InboxId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateInboxRequest'
+      responses:
+        '200':
+          description: Inbox updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InboxResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Inbox not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+    delete:
+      tags: [Inboxes]
+      summary: Delete inbox
+      operationId: deleteInbox
+      parameters:
+        - $ref: '#/components/parameters/InboxId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '200':
+          description: Inbox deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OkResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Inbox not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /api/v1/emails/send:
+    post:
+      tags: [Emails]
+      summary: Send outbound email from an inbox
+      operationId: sendEmail
+      description: Requires `emails:send` scope.
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendEmailRequest'
+      responses:
+        '201':
+          description: Email send accepted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmailResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          description: Plan limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '429':
+          description: Rate limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Provider or internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/v1/emails:
+    get:
+      tags: [Emails]
+      summary: List emails
+      operationId: listEmails
+      description: Returns inbound and outbound email records. Requires `emails:read` scope.
+      parameters:
+        - in: query
+          name: inboxId
+          required: false
+          schema:
+            type: string
+            format: uuid
+          description: Optional inbox filter.
+      responses:
+        '200':
+          description: Email records for the authenticated organization
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmailListResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+  /api/v1/emails/{id}/read:
+    patch:
+      tags: [Emails]
+      summary: Update email read state
+      operationId: updateEmailRead
+      description: Marks an email as read/unread. Requires `emails:write` scope.
+      parameters:
+        - $ref: '#/components/parameters/EmailId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateEmailReadRequest'
+      responses:
+        '200':
+          description: Email updated
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EmailResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Email not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /api/v1/emails/{id}:
+    delete:
+      tags: [Emails]
+      summary: Delete email
+      operationId: deleteEmail
+      description: Soft-deletes an email record. Requires `emails:write` scope.
+      parameters:
+        - $ref: '#/components/parameters/EmailId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '200':
+          description: Email deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OkResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Email not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /api/v1/domains:
+    get:
+      tags: [Domains]
+      summary: List custom domains
+      operationId: listDomains
+      responses:
+        '200':
+          description: Domains for the authenticated organization
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DomainListResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+    post:
+      tags: [Domains]
+      summary: Create custom domain
+      operationId: createDomain
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateDomainRequest'
+      responses:
+        '201':
+          description: Domain created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DomainResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          description: Domain already exists or idempotency conflict
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: Plan does not allow custom domains or limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '500':
+          description: Provider or internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/v1/domains/{id}/verify:
+    post:
+      tags: [Domains]
+      summary: Refresh DNS verification status for a domain
+      operationId: verifyDomain
+      parameters:
+        - $ref: '#/components/parameters/DomainId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '200':
+          description: Domain verification refreshed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DomainResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Domain not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '500':
+          description: Provider or internal error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/v1/domains/{id}:
+    delete:
+      tags: [Domains]
+      summary: Delete custom domain
+      operationId: deleteDomain
+      parameters:
+        - $ref: '#/components/parameters/DomainId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '200':
+          description: Domain deleted
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OkResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Domain not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /api/v1/api-keys:
+    get:
+      tags: [API Keys]
+      summary: List API keys
+      operationId: listApiKeys
+      responses:
+        '200':
+          description: API keys for the organization
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiKeyListResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+    post:
+      tags: [API Keys]
+      summary: Create API key
+      operationId: createApiKey
+      parameters:
+        - $ref: '#/components/parameters/IdempotencyKey'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateApiKeyRequest'
+      responses:
+        '201':
+          description: API key created (secret shown once)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiKeyCreatedResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          description: Plan key limit exceeded
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
+  /api/v1/api-keys/{id}/revoke:
+    post:
+      tags: [API Keys]
+      summary: Revoke API key
+      operationId: revokeApiKey
+      parameters:
+        - $ref: '#/components/parameters/ApiKeyId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '200':
+          description: API key revoked
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OkResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: API key not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /api/v1/api-keys/{id}/rotate:
+    post:
+      tags: [API Keys]
+      summary: Rotate API key (creates new key and revokes old key)
+      operationId: rotateApiKey
+      parameters:
+        - $ref: '#/components/parameters/ApiKeyId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '201':
+          description: API key rotated (new secret shown once)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApiKeyCreatedResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: API key not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '409':
+          $ref: '#/components/responses/Conflict'
+
+  /api/v1/metrics:
+    get:
+      tags: [Metrics]
+      summary: Get organization metrics snapshot
+      operationId: getMetrics
+      responses:
+        '200':
+          description: Current month metrics and plan limits
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MetricsResponse'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: APIKey
+
+  parameters:
+    IdempotencyKey:
+      in: header
+      name: Idempotency-Key
+      required: false
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 255
+      description: Optional key for safe retries of mutating operations.
+    InboxId:
+      in: path
+      name: id
+      required: true
+      schema:
+        type: string
+        format: uuid
+    DomainId:
+      in: path
+      name: id
+      required: true
+      schema:
+        type: string
+        format: uuid
+    EmailId:
+      in: path
+      name: id
+      required: true
+      schema:
+        type: string
+        format: uuid
+    ApiKeyId:
+      in: path
+      name: id
+      required: true
+      schema:
+        type: string
+        format: uuid
+
+  responses:
+    Unauthorized:
+      description: Missing or invalid bearer token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error: Missing bearer token
+    Forbidden:
+      description: API key lacks required scope
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            error: "Missing scope: inboxes:write"
+    BadRequest:
+      description: Validation error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+    Conflict:
+      description: Idempotency conflict or request in progress
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          examples:
+            differentPayload:
+              value:
+                error: Idempotency key reuse with different payload
+            inProgress:
+              value:
+                error: Request with this idempotency key is already in progress
+
+  schemas:
+    ErrorResponse:
+      type: object
+      additionalProperties: false
+      required: [error]
+      properties:
+        error:
+          type: string
+
+    OkResponse:
+      type: object
+      additionalProperties: false
+      required: [ok]
+      properties:
+        ok:
+          type: boolean
+          enum: [true]
+
+    Inbox:
+      type: object
+      additionalProperties: true
+      required:
+        - id
+        - org_id
+        - local_part
+        - domain_name
+        - email_address
+        - status
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        org_id:
+          type: string
+          format: uuid
+        local_part:
+          type: string
+        domain_name:
+          type: string
+        email_address:
+          type: string
+          format: email
+        display_name:
+          type: string
+          nullable: true
+        status:
+          type: string
+          enum: [active, deleted]
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+        deleted_at:
+          type: string
+          format: date-time
+          nullable: true
+
+    InboxListResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Inbox'
+
+    InboxResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: '#/components/schemas/Inbox'
+
+    CreateInboxRequest:
+      type: object
+      additionalProperties: false
+      required: [localPart]
+      properties:
+        localPart:
+          type: string
+          description: Local part only (e.g. `agent-1`)
+        displayName:
+          type: string
+        domainName:
+          type: string
+          description: Optional domain. Defaults to shared app domain.
+
+    UpdateInboxRequest:
+      type: object
+      additionalProperties: false
+      required: [displayName]
+      properties:
+        displayName:
+          type: string
+          nullable: true
+
+    Email:
+      type: object
+      additionalProperties: true
+      required:
+        - id
+        - org_id
+        - direction
+        - delivery_status
+        - subject
+        - from_address
+        - to_addresses
+        - is_read
+        - status
+        - created_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        org_id:
+          type: string
+          format: uuid
+        inbox_id:
+          type: string
+          format: uuid
+          nullable: true
+        direction:
+          type: string
+          enum: [inbound, outbound]
+        delivery_status:
+          type: string
+          enum: [unknown, queued, sent, failed, received]
+        message_id:
+          type: string
+          nullable: true
+        subject:
+          type: string
+        from_address:
+          type: string
+        to_addresses:
+          type: array
+          items:
+            type: string
+        text_body:
+          type: string
+          nullable: true
+        html_body:
+          type: string
+          nullable: true
+        is_read:
+          type: boolean
+        status:
+          type: string
+          enum: [active, deleted]
+        provider_payload:
+          type: object
+          nullable: true
+          additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+
+    EmailResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: '#/components/schemas/Email'
+
+    EmailListResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Email'
+
+    SendEmailRequest:
+      type: object
+      additionalProperties: false
+      required: [inboxId, to]
+      properties:
+        inboxId:
+          type: string
+          format: uuid
+        to:
+          type: string
+          description: Comma-separated recipient emails
+          example: "alice@example.com,bob@example.com"
+        subject:
+          type: string
+        text:
+          type: string
+
+    UpdateEmailReadRequest:
+      type: object
+      additionalProperties: false
+      required: [isRead]
+      properties:
+        isRead:
+          type: boolean
+
+    Domain:
+      type: object
+      additionalProperties: true
+      required:
+        - id
+        - org_id
+        - name
+        - status
+        - dns_records_json
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        org_id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        provider_domain_id:
+          type: string
+          nullable: true
+        provider_route_id:
+          type: string
+          nullable: true
+        status:
+          type: string
+          enum: [pending, active, failed, deleted]
+        dns_records_json:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+
+    DomainResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: '#/components/schemas/Domain'
+
+    DomainListResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Domain'
+
+    CreateDomainRequest:
+      type: object
+      additionalProperties: false
+      required: [name]
+      properties:
+        name:
+          type: string
+          description: Domain to onboard, e.g. mail.example.com
+
+    CreateApiKeyRequest:
+      type: object
+      additionalProperties: false
+      required: [name]
+      properties:
+        name:
+          type: string
+        scopes:
+          description: Comma-separated scopes string or array of scopes
+          oneOf:
+            - type: string
+            - type: array
+              items:
+                type: string
+
+    ApiKeyListItem:
+      type: object
+      additionalProperties: true
+      required: [id, name, key_prefix, scopes, created_at]
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        key_prefix:
+          type: string
+        scopes:
+          type: array
+          items:
+            type: string
+        last_used_at:
+          type: string
+          format: date-time
+          nullable: true
+        revoked_at:
+          type: string
+          format: date-time
+          nullable: true
+        created_at:
+          type: string
+          format: date-time
+
+    ApiKeyCreated:
+      type: object
+      additionalProperties: true
+      required: [id, org_id, name, key_prefix, scopes, created_at, secret]
+      properties:
+        id:
+          type: string
+          format: uuid
+        org_id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        key_prefix:
+          type: string
+        scopes:
+          type: array
+          items:
+            type: string
+        created_at:
+          type: string
+          format: date-time
+        secret:
+          type: string
+          description: Full API key value, only returned on create/rotate
+
+    ApiKeyListResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/ApiKeyListItem'
+
+    ApiKeyCreatedResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: '#/components/schemas/ApiKeyCreated'
+
+    PlanLimits:
+      type: object
+      additionalProperties: false
+      required: [maxInboxes, maxCustomDomains, maxApiKeys, monthlyEmails]
+      properties:
+        maxInboxes:
+          type: integer
+        maxCustomDomains:
+          type: integer
+        maxApiKeys:
+          type: integer
+        monthlyEmails:
+          type: integer
+
+    MetricsData:
+      type: object
+      additionalProperties: false
+      required:
+        - sentCount
+        - inboundCount
+        - inboxCount
+        - customDomainCount
+        - apiKeyCount
+        - limits
+        - plan
+      properties:
+        sentCount:
+          type: integer
+        inboundCount:
+          type: integer
+        inboxCount:
+          type: integer
+        customDomainCount:
+          type: integer
+        apiKeyCount:
+          type: integer
+        plan:
+          type: string
+          enum: [free, paid]
+        limits:
+          $ref: '#/components/schemas/PlanLimits'
+
+    MetricsResponse:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: '#/components/schemas/MetricsData'