---
openapi: "3.0.3"
info:
  title: IETF Mail Archive API
  version: 0.1.0
servers:
  - url: https://mailarchive.ietf.org
    description: server
paths:
  /api/v1/stats/msg_counts/:
    get:
      summary: Number of messages for given list(s), date range 
      parameters:
        - in: query
          name: list
          schema:
            type: string
          description: Email list(s). Optional. Comma separated list of Email Lists. If not provided return counts for all lists
          examples:
            one:
              value: dnsop
              summary: stats for one list
            multi:
              value: dnsop,v6ops
              summary: stats for multiple lists
        - in: query
          name: start 
          schema:
            type: string
            format: date
            example: 20200101
          description: Start Date ISO Format. Optional. Defaults to thirty days ago
        - in: query 
          name: end 
          schema:
            type: string
            format: date
            example: 20201231
          description: End Date ISO Format. Optional. Defaults to today
        - in: query 
          name: duration 
          schema:
            type: string
          description: Time duration. Optional. N(years|months|weeks|days|hours|minutes)
          examples:
            none:
              value:
              summary: no duration
            weeks:
              value: 6weeks
              summary: a duration of 6 weeks
            years:
              value: 2years
              summary: a duration of 2 years
      responses:
        '200':
          description: Returns message counts 
          content:
            application/json:
              schema:
                type: object
                properties:
                  start:
                    type: string
                    description: Start date
                  end:
                    type: string
                    description: End date
                  msg_counts:
                    type: object
                    description: Counts per list
              example:
                start: 20200101
                end: 20201231
                msg_counts:
                  dnsop: 1764

        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description
        
  /api/v1/stats/subscriber_counts/:
    get:
      summary: Number of subscribers for given list(s), for date
      parameters:
        - in: query
          name: list
          schema:
            type: string
          description: Email list(s). Optional. Comma separated list of Email Lists. If not provided return counts for all lists
          examples:
            one:
              value: dnsop
              summary: stats for one list
            multi:
              value: dnsop,v6ops
              summary: stats for multiple lists
        - in: query
          name: date 
          schema:
            type: string
            format: date
            example: 20200101
          description: Start Date ISO Format. Optional. Defaults to first day of last month

      responses:
        '200':
          description: Returns subscriber counts 
          content:
            application/json:
              schema:
                type: object
                properties:
                  date:
                    type: string
                    description: Date
                  subscriber_counts:
                    type: object
                    description: Counts per list
              example:
                date: 20200101
                subscriber_counts:
                  dnsop: 315

        '400':
          description: Error has occured.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error description

  /api/v1/message/import/:
    post:
      summary: Import email message
      security:
        - ApiKeyAuth: []
      requestBody:
        description: base64 encoded email message
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                list_name:
                  type: string
                  minLength: 1
                  description: email list name (no domain)
                list_visibility:
                  type: string
                  enum: [public, private]
                  description: email list visibility
                message:
                  type: string
                  description: base64 encoded message
              required:
                - list_name
                - list_visibility
                - message

      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
        '403':
          description: Forbidden

  /api/v1/message/import-mbox/:
    post:
      summary: Import an mbox file from a URL
      description: >
        Queues a background task to fetch the mbox file at the given URL and
        import all messages into the archive. If the server responds with
        Content-Type application/x-gzip or application/gzip the file is
        decompressed before processing.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                list_name:
                  type: string
                  minLength: 1
                  description: email list name (no domain)
                list_visibility:
                  type: string
                  enum: [public, private]
                  description: email list visibility
                url:
                  type: string
                  description: URL of the mbox file to fetch
              required:
                - list_name
                - list_visibility
                - url
            example:
              list_name: dnsop
              list_visibility: public
              url: https://example.com/lists/dnsop/2024-01.mbox

      responses:
        '202':
          description: Accepted — import task queued
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '415':
          description: Unsupported media type

  /api/v1/message/search/:
    post:
      summary: Search public email messages
      security:
        - ApiKeyAuth: []
      requestBody:
        description: search parameters JSON format
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_list:
                  type: string
                  minLength: 1
                  description: email list name (no domain)
                start_date:
                  type: string
                  format: date
                  description: start date in YYYY-MM-DD format
                query:
                  type: string
                  description: query string (Elasticsearch query_string query type)
                limit:
                  type: string
                  description: limit the results to this amount
              required:
                - email_list

      responses:
        '200':
          description: Returns results of query
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        from:
                          type: string
                          description: message sender
                        subject:
                          type: string
                          description: message subject
                        content:
                          type: string
                          description: message content
                        message_id:
                          type: string
                          description: message ID
                        url:
                          type: string
                          description: message url
                        date:
                          type: string
                          description: message date in isoformat (UTC)
              example:
                results:
                - from: Joe Smith <joesmith@example.com>
                  subject: Please read this document
                  content: "Hello\nThis is an excellent document"
                  message_id: "sdfhf9sdfhj239sdh@example.com"
                  url: https://example.com/msg/sdfjsdfsdflk
                  date: 20200101T12:00:00
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '405':
          description: Method not allowed
        '415':
          description: Unsupported media type

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY