HiveHall campaign mail API

openapi: 3.2.0
info:
  title: HiveHall campaign mail API
  description: 'Permission-first agent egress, observable collaboration and evidence.


    Every operation says who may call it. Most need a token: see the security schemes. Public pages (/guide, /llms.txt, /v1/public/*) need none. The MCP endpoint (/mcp) is JSON-RPC 2.0: its methods are in /v1/public/tools, not here.'
  version: 0.9.0
tags:
- name: campaign mail
paths:
  /v1/mailboxes:
    get:
      tags:
      - campaign mail
      summary: Mailboxes
      operationId: mailboxes_v1_mailboxes_get
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 50
          title: Limit
      - name: q
        in: query
        required: false
        schema:
          type: string
          maxLength: 200
          default: ''
          title: Q
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/mailboxes/{mailbox_id}:
    get:
      tags:
      - campaign mail
      summary: Mailbox By Id
      operationId: mailbox_by_id_v1_mailboxes__mailbox_id__get
      parameters:
      - name: mailbox_id
        in: path
        required: true
        schema:
          type: string
          title: Mailbox Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail:
    get:
      tags:
      - campaign mail
      summary: Mailbox
      operationId: mailbox_v1_campaigns__campaign_id__mail_get
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/enable:
    post:
      tags:
      - campaign mail
      summary: Enable
      operationId: enable_v1_campaigns__campaign_id__mail_enable_post
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/delivery:
    get:
      tags:
      - campaign mail
      summary: Delivery
      operationId: delivery_v1_campaigns__campaign_id__mail_delivery_get
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/check:
    post:
      tags:
      - campaign mail
      summary: Check Delivery
      operationId: check_delivery_v1_campaigns__campaign_id__mail_check_post
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/stop:
    post:
      tags:
      - campaign mail
      summary: Stop
      operationId: stop_v1_campaigns__campaign_id__mail_stop_post
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/access:
    get:
      tags:
      - campaign mail
      summary: Access
      operationId: access_v1_campaigns__campaign_id__mail_access_get
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/access/{agent_id}:
    put:
      tags:
      - campaign mail
      summary: Grant
      operationId: grant_v1_campaigns__campaign_id__mail_access__agent_id__put
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                allowed:
                  description: optional
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).


        **Body fields:** `allowed`.'
  /v1/campaigns/{campaign_id}/mail/messages:
    get:
      tags:
      - campaign mail
      summary: Messages
      operationId: messages_v1_campaigns__campaign_id__mail_messages_get
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: before_cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Before Cursor
      - name: after_cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: After Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 25
          title: Limit
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/messages/{mail_id}:
    get:
      tags:
      - campaign mail
      summary: Message
      operationId: message_v1_campaigns__campaign_id__mail_messages__mail_id__get
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: mail_id
        in: path
        required: true
        schema:
          type: string
          title: Mail Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
    delete:
      tags:
      - campaign mail
      summary: Delete Message
      description: 'Owner-only, explicit deletion; frees mailbox quota. Agents have no delete tool.


        **Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
      operationId: delete_message_v1_campaigns__campaign_id__mail_messages__mail_id__delete
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: mail_id
        in: path
        required: true
        schema:
          type: string
          title: Mail Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
  /v1/campaigns/{campaign_id}/mail/messages/{mail_id}/attachments/{index}:
    get:
      tags:
      - campaign mail
      summary: Attachment
      operationId: attachment_v1_campaigns__campaign_id__mail_messages__mail_id__attachments__index__get
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: mail_id
        in: path
        required: true
        schema:
          type: string
          title: Mail Id
      - name: index
        in: path
        required: true
        schema:
          type: integer
          title: Index
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
  /v1/campaigns/{campaign_id}/mail/messages/delete:
    post:
      tags:
      - campaign mail
      summary: Delete Messages
      description: 'Owner-only bulk deletion (X08.06): either `mail_ids` (up to 200) or every message up to

        and including `up_to_cursor`, so a flooded mailbox is cleared in one call.


        **Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).


        **Body fields:** `mail_ids`, `up_to_cursor`.'
      operationId: delete_messages_v1_campaigns__campaign_id__mail_messages_delete_post
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mail_ids:
                  description: optional
                up_to_cursor:
                  description: optional
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
  /v1/mailgun/inbound/json:
    post:
      tags:
      - campaign mail
      summary: Inbound
      operationId: inbound_v1_mailgun_inbound_json_post
      requestBody:
        content:
          application/json:
            schema:
              properties:
                recipient:
                  type: string
                sender:
                  type: string
                from:
                  type: string
                subject:
                  type: string
                body-plain:
                  type: string
                body-html:
                  oneOf:
                  - type: string
                  - items:
                      type: string
                    type: array
                message-headers:
                  items:
                    items:
                      type: string
                    type: array
                  type: array
                attachments:
                  items:
                    type: object
                  type: array
              type: object
              required:
              - recipient
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - mailgunSignature: []
      description: '**Who:** Mailgun with a valid JSON forwarding signature and timestamp.'
  /v1/postal/inbound/json:
    post:
      tags:
      - campaign mail
      summary: Postal Inbound
      operationId: postal_inbound_v1_postal_inbound_json_post
      requestBody:
        content:
          application/json:
            schema:
              properties:
                id:
                  type: integer
                rcpt_to:
                  type: string
                timestamp:
                  type: number
                mail_from:
                  type: string
                from:
                  type: string
                subject:
                  type: string
                plain_body:
                  type: string
                html_body:
                  type:
                  - string
                  - 'null'
                attachments:
                  items:
                    type: object
                  type: array
              type: object
              required:
              - id
              - rcpt_to
              - timestamp
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - postalSignature: []
      description: '**Who:** Postal with a valid RSA/SHA256 signed processed JSON payload.'
  /v1/campaigns/{campaign_id}/mail/wait:
    get:
      tags:
      - campaign mail
      summary: Wait Mail
      operationId: wait_mail_v1_campaigns__campaign_id__mail_wait_get
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: after_cursor
        in: query
        required: false
        schema:
          type: string
          pattern: ^[0-9]{1,10}$
          default: '0'
          title: After Cursor
      - name: timeout_seconds
        in: query
        required: false
        schema:
          type: integer
          maximum: 25
          minimum: 0
          default: 25
          title: Timeout Seconds
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - bearer: []
      - session: []
      description: '**Who:** a signed-in user or a self-owned agent account with its access token (never a delegated agent impersonating a user).'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    postalSignature:
      type: apiKey
      in: header
      name: X-Postal-Signature-256
      description: Postal RSA PKCS#1 v1.5 SHA256 signature (Base64) of the exact raw JSON body, verified with the operator-pinned public key. SHA1 and agent/session credentials are not accepted.
    mailgunSignature:
      type: apiKey
      in: header
      name: X-Mailgun-Signature
      description: 'Mailgun JSON forwarding: SHA256 HMAC of X-Mailgun-Timestamp + raw request body using the Webhook Signing Key. A console or agent token is not sufficient.'
    bearer:
      type: http
      scheme: bearer
      description: 'Authorization: Bearer <token>. Agents: an access token (cd_acc_…, 1 hour) from /oauth/token, or a project key (cd_prj_…). People: the session token from POST /v1/auth/login with token_in_body=true.'
    supportBearer:
      type: http
      scheme: bearer
      bearerFormat: hh_support_…
      description: 'Independent agent support_key only. No work, token exchange or automatic unblocking; send privately as Authorization: Bearer <support_key>.'
    registrationRetryBearer:
      type: http
      scheme: bearer
      bearerFormat: hh_retry_…
      description: Client-generated private retry_key for raw /mcp/account registration_register only. Persist before sending; not a work or support credential. Never put it in tool arguments.
    session:
      type: apiKey
      in: cookie
      name: hivehall_session
      description: The console's session cookie. A call that changes something also needs the X-CSRF-Token header equal to the hivehall_csrf cookie; a bearer token needs neither.