openapi: 3.0.3 info: title: Parsimony admin API version: 1.0.0 servers: - url: /api/v1 security: - bearer: [] components: securitySchemes: bearer: type: http scheme: bearer schemas: List: type: object properties: id: {type: integer} name: {type: string} domain: {type: string} title: {type: string} address: {type: string} post_policy: {type: string, enum: [members, moderated]} join_policy: {type: string, enum: [open, closed]} archive_policy: {type: string, enum: [public, private, off], description: "public: browsable on the web; private: API only (default); off: not stored"} Message: type: object properties: id: {type: integer} thread_id: {type: integer} message_id: {type: string} in_reply_to: {type: string} subject: {type: string} sender: {type: string, description: Display name of the author} date: {type: string, format: date-time} size: {type: integer} body: {type: string, description: Only when reading a single message} Member: type: object properties: address: {type: string} display_name: {type: string} disabled: {type: boolean, description: Disabled after 3 hard bounces; re-adding the member re-enables it} bounce_count: {type: integer} Held: type: object properties: id: {type: integer} sender: {type: string} subject: {type: string} size: {type: integer} created_at: {type: string, format: date-time} Error: type: object properties: error: {type: string} responses: Error: description: Error content: application/json: schema: {$ref: '#/components/schemas/Error'} paths: /health: get: security: [] summary: Liveness check responses: '200': {description: OK} /lists: get: summary: List all lists responses: '200': description: OK content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/List'}} post: summary: Create a list requestBody: required: true content: application/json: schema: type: object required: [name, domain] properties: name: {type: string} domain: {type: string} title: {type: string} responses: '201': description: Created content: application/json: schema: {$ref: '#/components/schemas/List'} '400': {$ref: '#/components/responses/Error'} '409': {$ref: '#/components/responses/Error'} /lists/{id}: parameters: - {name: id, in: path, required: true, schema: {type: integer}} get: summary: Get a list responses: '200': description: OK content: application/json: schema: {$ref: '#/components/schemas/List'} '404': {$ref: '#/components/responses/Error'} patch: summary: Update title and policies (send only the fields to change) requestBody: required: true content: application/json: schema: type: object properties: title: {type: string} post_policy: {type: string, enum: [members, moderated]} join_policy: {type: string, enum: [open, closed]} archive_policy: {type: string, enum: [public, private, off]} responses: '200': description: OK content: application/json: schema: {$ref: '#/components/schemas/List'} '400': {$ref: '#/components/responses/Error'} '404': {$ref: '#/components/responses/Error'} delete: summary: Delete a list and its members responses: '204': {description: Deleted} '404': {$ref: '#/components/responses/Error'} /lists/{id}/members: parameters: - {name: id, in: path, required: true, schema: {type: integer}} get: summary: List members responses: '200': description: OK content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/Member'}} '404': {$ref: '#/components/responses/Error'} post: summary: Add a member (idempotent) requestBody: required: true content: application/json: schema: type: object required: [address] properties: address: {type: string} display_name: {type: string} responses: '201': description: Created content: application/json: schema: {$ref: '#/components/schemas/Member'} '400': {$ref: '#/components/responses/Error'} '404': {$ref: '#/components/responses/Error'} /lists/{id}/members/{address}: parameters: - {name: id, in: path, required: true, schema: {type: integer}} - {name: address, in: path, required: true, schema: {type: string}} delete: summary: Remove a member responses: '204': {description: Removed} '404': {$ref: '#/components/responses/Error'} /lists/{id}/held: parameters: - {name: id, in: path, required: true, schema: {type: integer}} get: summary: Messages waiting for moderation responses: '200': description: OK content: application/json: schema: {type: array, items: {$ref: '#/components/schemas/Held'}} '404': {$ref: '#/components/responses/Error'} /held/{id}/approve: parameters: - {name: id, in: path, required: true, schema: {type: integer}} post: summary: Approve and deliver a held message responses: '204': {description: Delivered} '404': {$ref: '#/components/responses/Error'} '501': {$ref: '#/components/responses/Error'} /held/{id}: parameters: - {name: id, in: path, required: true, schema: {type: integer}} delete: summary: Discard a held message responses: '204': {description: Discarded} '404': {$ref: '#/components/responses/Error'} /lists/{id}/archive: parameters: - {name: id, in: path, required: true, schema: {type: integer}} get: summary: List or search archived messages, newest first parameters: - {name: q, in: query, schema: {type: string}, description: Full-text search over subject, body and sender; words are ANDed} - {name: limit, in: query, schema: {type: integer, default: 50, maximum: 200}} - {name: offset, in: query, schema: {type: integer, default: 0}} responses: '200': description: OK content: application/json: schema: type: object properties: total: {type: integer} messages: {type: array, items: {$ref: '#/components/schemas/Message'}} '400': {$ref: '#/components/responses/Error'} '404': {$ref: '#/components/responses/Error'} /archive/{id}: parameters: - {name: id, in: path, required: true, schema: {type: integer}} get: summary: Read an archived message with its body responses: '200': description: OK content: application/json: schema: {$ref: '#/components/schemas/Message'} '404': {$ref: '#/components/responses/Error'} delete: summary: Delete an archived message and its search entry responses: '204': {description: Deleted} '404': {$ref: '#/components/responses/Error'}