sendmux-ai Connection API

openapi: 3.2.0
info:
  description: Programmatic access to your Sendmux email infrastructure.
  title: Sendmux Connection API
  version: 1.0.0
servers:
- description: API v1
  url: https://app.sendmux.ai/api/v1
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Connection
paths:
  /me:
    get:
      description: Validate this credential and return its team, connection label, permissions and authorised mailboxes. No additional read permission or mailbox selection is required. Mailbox storage and sending availability are not checked. No user profile or secrets are returned.
      operationId: managementGetConnection
      parameters:
      - description: ETag from a previous response. A match returns 304 with no body after rechecking authentication.
        in: header
        name: If-None-Match
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionResponse'
          description: Connection information
          headers:
            Cache-Control:
              description: Always no-store.
              schema:
                type: string
            ETag:
              schema:
                type: string
            X-Request-Id:
              description: Request identifier.
              schema:
                type: string
        '304':
          description: Connection information is unchanged. Authentication is checked on every request.
          headers:
            Cache-Control:
              description: Always no-store.
              schema:
                type: string
            X-Request-Id:
              description: Request identifier.
              schema:
                type: string
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authentication required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Credential is not authorised for this API
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Rate limit exceeded
          headers:
            Retry-After:
              schema:
                type: string
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Unexpected server error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Authentication service temporarily unavailable
          headers:
            Retry-After:
              schema:
                type: string
      security:
      - bearerAuth: []
      - oauth2: []
      summary: Get Management connection
      tags:
      - Connection
components:
  schemas:
    ResponseMeta:
      additionalProperties: false
      properties:
        request_id:
          example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx
          type: string
      required:
      - request_id
      type: object
    ConnectionResponse:
      allOf:
      - $ref: '#/components/schemas/SuccessEnvelope'
      - properties:
          data:
            $ref: '#/components/schemas/Connection'
          meta:
            $ref: '#/components/schemas/ResponseMeta'
        required:
        - data
        type: object
      unevaluatedProperties: false
    ApiErrorDetail:
      additionalProperties: false
      properties:
        code:
          description: Machine-readable issue code from the validator (e.g. zod issue code).
          example: invalid_string
          type: string
        field:
          description: Dot-path of the offending request field.
          example: recipient.email
          type: string
        message:
          description: Human-readable issue description.
          type: string
      required:
      - field
      - code
      - message
      type: object
    SuccessEnvelope:
      properties:
        meta:
          additionalProperties: {}
          properties: {}
          type: object
        ok:
          enum:
          - true
          type: boolean
      required:
      - ok
      - meta
      type: object
    Connection:
      additionalProperties: false
      properties:
        credential:
          additionalProperties: false
          properties:
            id:
              type: string
            name:
              type:
              - string
              - 'null'
            type:
              enum:
              - api_key
              - oauth
              - agent_token
              example: api_key
              type: string
          required:
          - id
          - type
          - name
          type: object
        label:
          description: Display label for this connection.
          type: string
        mailboxes:
          items:
            additionalProperties: false
            properties:
              email:
                format: email
                type: string
              id:
                type: string
            required:
            - id
            - email
            type: object
          type: array
        permissions:
          items:
            type: string
          type: array
        team:
          additionalProperties: false
          properties:
            id:
              type: string
            name:
              type: string
          required:
          - id
          - name
          type: object
      required:
      - team
      - credential
      - label
      - permissions
      - mailboxes
      type: object
    ApiError:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          properties:
            code:
              description: Machine-readable error code
              enum:
              - invalid_parameter
              - missing_parameter
              - authentication_required
              - insufficient_permissions
              - not_found
              - conflict
              - limit_exceeded
              - idempotency_conflict
              - payload_too_large
              - validation_error
              - rate_limit_exceeded
              - service_unavailable
              - internal_error
              example: invalid_parameter
              type: string
            doc_url:
              description: Link to relevant documentation
              type: string
            errors:
              description: Accumulated per-field issues for validation errors. Only present on 400/422 responses.
              items:
                $ref: '#/components/schemas/ApiErrorDetail'
              type: array
            message:
              description: Human-readable error description
              type: string
            param:
              description: The parameter that caused the error
              type: string
            retryable:
              description: Whether the caller may safely retry this request. 4xx are typically false (except 429); 5xx are typically true.
              example: false
              type: boolean
          required:
          - code
          - message
          - retryable
          type: object
        meta:
          additionalProperties: false
          properties:
            request_id:
              example: req_clxxxxxxxxxxxxxxxxxxxxxxxxx
              type: string
          required:
          - request_id
          type: object
        ok:
          enum:
          - false
          type: boolean
      required:
      - ok
      - error
      - meta
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: API Key
      description: Sendmux API key. Use a root API key for Management API routes, or a mailbox credential for Mailbox API routes. Obtain keys from the dashboard under API Keys.
      scheme: bearer
      type: http
    oauth2:
      description: Use the authorisation-code flow with S256 PKCE and resource=https://sendmux.ai/api. The user selects the team, API access and mailboxes during consent. OAuth access tokens authenticate HTTP API requests; use separate credentials for SMTP and IMAP.
      flows:
        authorizationCode:
          authorizationUrl: https://app.sendmux.ai/oauth/authorize
          refreshUrl: https://app.sendmux.ai/oauth/token
          scopes:
            analytics.*: All analytics operations
            analytics.read: View key usage analytics and verification logs
            billing.*: All billing operations
            billing.auto_topup: Configure auto top-up settings
            billing.read: View balance, transactions, invoices
            billing.topup: Purchase balance top-ups
            calendar.read: Read calendars and events in this mailbox
            calendar.write: Create calendars and create, edit and delete events in this mailbox
            domain.*: All domain operations
            domain.create: Add sending domains
            domain.delete: Remove domains
            domain.read: List/view domains and DNS status
            domain.verify: Trigger domain verification
            email.receive: Authorise email reception
            email.send: Send email through the HTTP API
            key.*: All key management operations
            key.create: Create new API keys (both root and mailbox)
            key.read: List/view API keys and their metadata
            key.revoke: Revoke API keys
            key.rotate: Rotate API keys
            logs.*: All log operations
            logs.read: View delivery logs
            mailbox.admin.*: All mailbox admin operations
            mailbox.admin.create: Create mailboxes (admin-level)
            mailbox.admin.delete: Delete mailboxes (admin-level)
            mailbox.admin.manage: Manage all mailbox settings
            mailbox.admin.read: List/view mailboxes (admin-level)
            mailbox.drafts.write: Create and edit saved mailbox drafts
            mailbox.read: Read mailbox contents (folders, messages)
            mailbox.settings.update: Update own mailbox settings (signature, auto-reply)
            provider.*: All provider operations
            provider.create: Add email provider accounts (Google, Microsoft, SMTP)
            provider.delete: Remove provider accounts
            provider.read: List/view provider accounts and connection status
            provider.update: Update provider settings, refresh tokens
            routing.*: All routing operations
            routing.create: Create delivery groups
            routing.delete: Remove delivery groups
            routing.read: List/view delivery groups and routing rules
            routing.update: Update delivery group configuration
            team.*: All team operations
            team.members.invite: Invite team members
            team.members.remove: Remove team members
            team.members.roles: Change member roles
            team.read: View team settings and members
            team.update: Update team settings
            webhook.*: All webhook operations
            webhook.create: Create webhook subscriptions
            webhook.delete: Delete webhook subscriptions
            webhook.manage: Rotate signing secret + send test events
            webhook.read: List/view webhook subscriptions
            webhook.update: Update webhook URL, event types, enabled flag
          tokenUrl: https://app.sendmux.ai/oauth/token
      type: oauth2