| |
| 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. There are various options for specifying the date range: |
| - a single month: yyyy-mm |
| - gte (greater than or equal) or lte (less than or equal) a number of Months, weeks, years or days (Mwyd) |
| - dfr=yyyy-mm-dd|dto=yyy-mm-dd - a range of days (inclusive) |
| example: | |
| - "2019-01" |
| - "lte=10d", "gte=2y" |
| - "dfr=2021-9-21|dto=2021-10-31" |
| type: string |
| dfrom: |
| description: Optional start date, expressed as days ago. Used with dto. |
| type: string |
| example: 31 |
| dto: |
| description: Optional start date, expressed as days to capture starting from dfrom |
| type: string |
| example: 10 |
| 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" |
| header_to: |
| description: "Optional To: header search for narrowing down results" |
| type: string |
| example: janedoe@example.org |
| required: |
| - list |
| - domain |
| SingleEmailRequest: |
| properties: |
| id: |
| description: The ID (document id or message-id) of the email to fetch |
| example: "5wnbldtbbcog0p259jnhvqbkc7nhjt71" |
| type: string |
| listid: |
| description: The List ID the email must adhere to (only if searching by Message-ID header) |
| example: "<users.httpd.apache.org>" |
| type: string |
| required: |
| - id |
| SingleEmailResponse: |
| properties: |
| attachments: |
| description: List of attachments, if any |
| example: [TBA] |
| type: array |
| cc: |
| description: List of Cc email addresses |
| example: "\"announce@tomcat.apache.org\" <announce@tomcat.apache.org>, \"dev@tomcat.apache.org\" <dev@tomcat.apache.org>, announce@apache.org" |
| type: string |
| 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 |
| body_short: |
| description: The message body of the email, truncated to 201 chars |
| 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, tuncated to 201 chars |
| 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: |
| active_months: |
| description: List of months with activity |
| type: array |
| example: |
| - |
| "2017-01": 1 |
| - |
| "2017-02": 1 |
| 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" |
| searchlist: |
| description: The raw List-ID (if any) of the search parameters |
| type: string |
| example: "<dev.lists.example.org>" |
| name: |
| description: The listname part of the search parameters |
| type: string |
| example: dev |
| 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 |
| unixtime: |
| description: The server time in UNIX epoch format |
| example: 1506761839 |
| type: integer |
| 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 |
