
openapi: 3.0.0
info:
  version: 1.0.0
  description: This is the API specifications for interacting with the Pony Mail (Foal) server backend
  title: Apache Pony Mail Foal API
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
components:
  schemas:
    ActionResponse:
      properties:
        message:
          description: Response text in human readable format
          example: Email dispatched
          type: string
        okay:
          description: Boolean indicating whether the desired action was completed or not
          type: boolean
          example: true
      required:
      - message
      - okay
    SearchRequest:
      properties:
        list:
          description: The list part of the mailing list(s) to search. Can be * for wildcard search
          example: dev
          type: string
        domain:
          description: The domain part of the mailing list(s) to search.  Can be * for wildcard search
          type: string
          example: lists.example.org
        date:
          description: Optional year-month date to search within
          type: string
          example: "2020-08"
        s:
          description: Optional start year-month date to search from
          type: string
          example: "2019-01"
        e:
          description: Optional end year-month date to search to
          type: string
          example: "2021-12"
        d:
          description: Optional advanced date parameters. Uses gte (greater than or equal) or lte (less than or equal) to narrow results
          example: "lte=2019-01"
          type: string
        q:
          description: "Free text query to search for. Can use + or - to denote mandatory presence or absence of words"
          type: string
          example: "apples +oranges -bananas"
        header_from:
          description: "Optional From: header search for narrowing down results"
          type: string
          example: janedoe@example.org
        header_subject:
          description: "Optional Subject: header search for narrowing down results"
          type: string
          example: "weekly meeting on friday"
        header_body:
          description: "Optional body-only search parameters"
          type: string
          example: "This was a great idea"
      required:
      - list
      - domain
      - q
    SingleEmailRequest:
      properties:
        id:
          description: The ID (document id or message-id) of the email to fetch
          example: "5wnbldtbbcog0p259jnhvqbkc7nhjt71"
          type: string
      required:
      - id
    SingleEmailResponse:
      properties:
        from:
          description: The sender address of the email
          example: "Asterix build server  <jenkins@asterix-jenkins.ics.uci.edu>"
          type: string
        from_raw:
          description: The sender address of the email (unedited by Foal)
          example: "Asterix build server  <jenkins@asterix-jenkins.ics.uci.edu>"
          type: string
        to:
          description: The recipient address of the email
          example: dev@asterixdb.apache.org
          type: string
        subject:
          description: The email subject
          example: "Jenkins build is still unstable: asterix-integration-tests ab8375ea"
          type: string
        message-id:
          description: The original (user-provided) Message-ID of the email
          example: "<521062724.28.1506761839312.JavaMail.jenkins@unhygienix.ics.uci.edu>"
          type: string
        id:
          description: The internal document ID of the email
          example: r8cmj7vm5n8z5r3xda5ebd
          type: string
        mid:
          description: The internal document ID of the email (backwards compat item)
          example: r8cmj7vm5n8z5r3xda5ebd
          type: string
        epoch:
          description: The timestamp of the email in UNIX epoch format
          example: 1506761839
          type: integer
        list:
          description: The list-ID header value
          example: "<dev.asterixdb.apache.org>"
          type: string
        list_raw:
          description: The unedited list-ID header value
          example: "<dev.asterixdb.apache.org>"
          type: string
        date:
          description: The Datetime of the email
          example: "2017/09/30 08:57:19"
          type: string
        private:
          description: Whether the email is privately archived or not
          example: false
          type: boolean
        references:
          description: "The References: header of the email"
          example: "<1538859253.27.1506747931378.JavaMail.jenkins@unhygienix.ics.uci.edu>"
          type: string
        in-reply-to:
          description: "The In-Reply-To: header of the email"
          example: "<1538859253.27.1506747931378.JavaMail.jenkins@unhygienix.ics.uci.edu>"
          type: string
        body:
          description: The message body of the email
          example: "I like cakes.\nThe joke you made really made me laugh.\nBest,\nJess."
          type: string
        permalinks:
          description: All IDs that this document is filed and accessible under
          type: array
          example: ["r8cmj7vm5n8z5r3xda5ebd","r67a4b2148dcb782e68da95e2601cce677ad9902ecc87d640508ed9be@<dev.asterixdb.apache.org>"]
        dbid:
          description: "The Unique (non-deduplicated) identifier for this email, SHA3-256 digest of the raw message"
          example: "08c4e61930db221d869b186707c7177248d227d7372e8d1e4028880b9d214cf1"
          type: string
        gravatar:
          description: The Gravatar ID (lowercased md5 digest of the sender address) of the sender
          example: "69eea47c5083c2e4945a2704fc7b658c"
          type: string
    CompactEmailResponse:
      properties:
        from:
          description: The sender address of the email
          example: "Asterix build server  <jenkins@asterix-jenkins.ics.uci.edu>"
          type: string
        subject:
          description: The email subject
          example: "Jenkins build is still unstable: asterix-integration-tests ab8375ea"
          type: string
        message-id:
          description: The original (user-provided) Message-ID of the email
          example: "<521062724.28.1506761839312.JavaMail.jenkins@unhygienix.ics.uci.edu>"
          type: string
        id:
          description: The internal document ID of the email
          example: r8cmj7vm5n8z5r3xda5ebd
          type: string
        mid:
          description: The internal document ID of the email (backwards compat item)
          example: r8cmj7vm5n8z5r3xda5ebd
          type: string
        epoch:
          description: The timestamp of the email in UNIX epoch format
          example: 1506761839
          type: integer
        list:
          description: The list-ID header value
          example: "<dev.asterixdb.apache.org>"
          type: string
        list_raw:
          description: The unedited list-ID header value
          example: "<dev.asterixdb.apache.org>"
          type: string
        private:
          description: Whether the email is privately archived or not
          example: false
          type: boolean
        body:
          description: The message body of the email
          example: "I like cakes.\nThe joke you made really made me laugh.\nBest,\nJess."
          type: string
        gravatar:
          description: The Gravatar ID (lowercased md5 digest of the sender address) of the sender
          example: "69eea47c5083c2e4945a2704fc7b658c"
          type: string
        children:
          description: Any child emails (replies)
          items:
            $ref: '#/components/schemas/CompactEmailResponse'
          example: []
          type: array
    ThreadResponse:
      properties:
        thread:
          type: object
          description: The thread as a nested dictionary
          $ref: '#/components/schemas/CompactEmailResponse'
        emails:
          type: array
          description: Every single email in the thread, as an array
          items:
            $ref: '#/components/schemas/CompactEmailResponse'
    StatsResponse:
      properties:
        firstYear:
          description: The first year found in the search results
          type: integer
          example: 2018
        firstMonth:
          description: The first month found in the search results
          type: integer
          example: 1
        lastYear:
          description: The last (most recent) year found within the search results
          type: integer
          example: 2021
        lastMonth:
          description: The last (most recent) month found in the search results
          type: integer
          example: 11
        hits:
          description: The total number of emails found in this search
          type: integer
          example: 134
        numparts:
          description: The total number of participants (authors) within the search result
          type: integer
          example: 28
        no_threads:
          description: The total number of distinct threads found within the search results
          type: integer
          example: 35
        emails:
          description: The emails found in this search, as a list of CompactEmailResponse objects
          type: array
          items:
            $ref: '#/components/schemas/CompactEmailResponse'
        cloud:
          description: Word cloud as a word=count dictionary
          type: object
          example:
            foo: 25
            bar: 10
            baz: 4
        participants:
          description: The participants (authors) within the search results, ranked by number of emails authored
          type: array
          example:
            - 
              email: foo@bar.baz
              name: FOo Bar
              count: 10
              gravatar: "4fa3f0e42e603e5ae1ab627d6690e365"
            -
              email: jane@doe.example.org
              name: Jane Doe
              count: 5
              gravatar: "7ddfb840a4db40a01ac99d29e82267b0"
        search_list:
          description: The raw List-ID (if any) of the search parameters
          type: string
          example: "<dev.lists.example.org>"
        domain:
          description: The domain part of the search parameters
          type: string
          example: lists.example.org
        list:
          description: The full list, in human readable format, of the search parameters
          type: string
          example: dev@lists.example.org
        searchParams:
          description: The search parameters used in this search
          type: object
          example:
            d: "gte=2018-01"
            q: "i like cake"
            list: dev
            domain: lists.example.irg
        thread_struct:
          description: The threaded representation of the search results, as a list of threads
          type: array
          example:
            -
              children: []
              tid: "1ng5htgrhkbzwzzb"
              subject: "Errored: apache/httpd#1037 (trunk - bafd719)"
              tsubject: "apache/httpd#1037 (trunk…_<dev.httpd.apache.org>"
              epoch: 1596279300
              nest: 1
    ErrorResponse:
      properties:
        okay:
          description: Whether the action completed (will be false)
          example: false
          type: boolean
        message:
          description: Response text in human readable format
          example: The requested action could not be completed...
          type: string
      required:
      - error
    EmailComposition:
      properties:
        to:
          description: Recipient address
          example: dev@lists.example.org
          type: string
        subject:
          description: Email subject
          type: string
          example: "RE: advanced debugging"
        body:
          description: Email message body
          type: string
          example: |
            I think this is a great idea.
            Let's chat on Monday.
            With regards, Charles.
        references:
          description: Message ID of email this reply references (if not direct reply)
          type: string
          example: "<foo1234@dev.lists.example.org>"
        in-reply-to:
          description: Message ID of the email this is a direct reply to (if any)
          type: string
          example: "<foo1234@dev.lists.example.org>"
      required:
      - to
      - subject
      - body
  securitySchemes:
    cookieAuth:
      in: cookie
      name: ponymail
      type: apiKey
paths:
  /api/compose.json:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailComposition'
        description: Email details
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
          description: 200 response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unexpected error
      summary: Compose and dispatch an email to a list
      security:
      - cookieAuth: []
  /api/email.json:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleEmailRequest'
        description: Email details
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleEmailResponse'
          description: 200 Response
        '404':
          content:
            text/plain:
              example: "Email not found!"
          description: 404 response if email not found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Fetches a single email and returns it as a JSON object
  /api/mbox.json:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        description: Search parameters
        required: true
      responses:
        '200':
          content:
            text/plain:
              example: "[mbox file contents]"
          description: 200 Response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Returns a list or a search result in mbox file format
  # /api/mgmt.json:
  #   TBA
  # /api/oauth.json:
  #   TBA
  # /api/pminfo.json:
  #   TBA
  # /api/preferences.json:
  #   TBA
  /api/source.json:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleEmailRequest'
        description: Email details
        required: true
      responses:
        '200':
          content:
            text/plain:
              example: |
                From dev-return-5233-apmail-asterixdb-dev-archive=asterixdb.apache.org@asterixdb.apache.org  Sat Sep 30 08:58:08 2017
                Return-Path: <dev-return-5233-apmail-asterixdb-dev-archive=asterixdb.apache.org@asterixdb.apache.org>
                Received: (qmail 50072 invoked by uid 500); 30 Sep 2017 08:58:08 -0000
                Mailing-List: contact dev-help@asterixdb.apache.org; run by ezmlm
                Precedence: bulk
                List-Help: <mailto:dev-help@asterixdb.apache.org>
                List-Unsubscribe: <mailto:dev-unsubscribe@asterixdb.apache.org>
                List-Post: <mailto:dev@asterixdb.apache.org>
                List-Id: <dev.asterixdb.apache.org>
                Reply-To: dev@asterixdb.apache.org
                Delivered-To: mailing list dev@asterixdb.apache.org
                Received: (qmail 50057 invoked by uid 99); 30 Sep 2017 08:58:07 -0000
                Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142)
                    by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 30 Sep 2017 08:58:07 +0000
                Received: from localhost (localhost [127.0.0.1])
                	by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 3A2C21808B9
                	for <dev@asterixdb.apache.org>; Sat, 30 Sep 2017 08:58:07 +0000 (UTC)
                X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org
                X-Spam-Flag: NO
                X-Spam-Score: 1.5
                X-Spam-Level: *
                X-Spam-Status: No, score=1.5 tagged_above=-999 required=6.31
                	tests=[KAM_LAZY_DOMAIN_SECURITY=1, KAM_LINKBAIT=0.5,
                	RP_MATCHES_RCVD=-0.001, URIBL_BLOCKED=0.001] autolearn=disabled
                Received: from mx1-lw-us.apache.org ([10.40.0.8])
                	by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024)
                	with ESMTP id 3VgxbDG3zW9E for <dev@asterixdb.apache.org>;
                	Sat, 30 Sep 2017 08:58:06 +0000 (UTC)
                Received: from unhygienix.ics.uci.edu (unhygienix.ics.uci.edu [128.195.14.130])
                	by mx1-lw-us.apache.org (ASF Mail Server at mx1-lw-us.apache.org) with ESMTP id 4D7025FCC1
                	for <dev@asterixdb.apache.org>; Sat, 30 Sep 2017 08:58:06 +0000 (UTC)
                Received: from obelix.ics.uci.edu (localhost [127.0.0.1])
                	by unhygienix.ics.uci.edu (Postfix) with ESMTP id 539A4240E6E;
                	Sat, 30 Sep 2017 01:57:19 -0700 (PDT)
                Date: Sat, 30 Sep 2017 01:57:19 -0700 (PDT)
                From: Asterix build server  <jenkins@asterix-jenkins.ics.uci.edu>
                To: dev@asterixdb.apache.org
                Message-ID: <521062724.28.1506761839312.JavaMail.jenkins@unhygienix.ics.uci.edu>
                In-Reply-To: <1538859253.27.1506747931378.JavaMail.jenkins@unhygienix.ics.uci.edu>
                References: <1538859253.27.1506747931378.JavaMail.jenkins@unhygienix.ics.uci.edu>
                Subject: Jenkins build is still unstable: asterix-integration-tests ab8375ea
                MIME-Version: 1.0
                Content-Type: text/plain; charset=UTF-8
                Content-Transfer-Encoding: 7bit
                X-Instance-Identity: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0nz/YYRm0UEuhP+TWwX2ST1fizEpF7HpM4sPcYz2NS87f/HwLueejqBmJC4+jeepHXZ+Jv8mx/RZqsiFpmGNadfrVj5xdvYYYhL+LX6IsquitcGo4czObwwWQ3wInopyASEIqxRi7J6UytN3Fsh6s61qMC7piY42C6FKuqDH3vbnDkTLc8SDdMT9gWSyP9hQTcqcZ76QizLXas6NwvHmUjtNTpxcEsiEcY41b9rUv3810LUs6FQymbPzyZPhTmcRS8841AjfVUbWiSc3ElmKHNxrFA2JmK5S1/xyEeESEaeYHT7daGi2aR1P2G9XtRj5Oj4n7dKo/Xo3cznIN3NNtQIDAQAB
                X-Jenkins-Job: asterix-integration-tests
                X-Jenkins-Result: UNSTABLE
                
                See <https://asterix-jenkins.ics.uci.edu/job/asterix-integration-tests/changes>
          description: 200 Response
        '404':
          content:
            text/plain:
              example: "Email not found!"
          description: 404 response if email not found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Fetches the raw mbox source of an email
  /api/stats.json:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
        description: Search parameters
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
          description: 200 Response
        '500':
          content:
            text/plain:
              example: "The search could not be completed"
      security:
      - cookieAuth: []
      summary: Searches the archives and returns the results that match
  /api/thread.json:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleEmailRequest'
        description: Email details
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadResponse'
          description: 200 Response
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: unexpected error
      security:
      - cookieAuth: []
      summary: Fetches an email thread based on a parent email