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, publishers], description: "publishers: a newsletter, only members flagged publisher may post"} 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} QueueItem: type: object properties: id: {type: integer} recipient: {type: string} attempts: {type: integer, description: Failed attempts so far} last_error: {type: string} next_attempt: {type: string, format: date-time} created_at: {type: string, format: date-time} failed: {type: boolean, description: Given up for good (refused by the relay, or too old); never retried, listed for a week} Member: type: object properties: address: {type: string} display_name: {type: string} disabled: {type: boolean, description: Disabled after 3 hard bounces within 30 days; re-adding the member re-enables it} bounce_count: {type: integer, description: Recent hard bounces (restarts at 1 when the last one is older than 30 days)} publisher: {type: boolean, description: May post when the list's post_policy is publishers} Held: type: object properties: id: {type: integer} sender: {type: string, description: The SMTP (envelope) sender} from: {type: string, description: "The From header as received: the author readers will see (at most 200 characters)"} mismatch: {type: boolean, description: The From header names someone other than the sender, or no usable address} subject: {type: string, description: Decoded, at most 200 characters} size: {type: integer} reason: {type: string, description: Why the message was held} 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 minLength: 1 maxLength: 30 pattern: '^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$' description: Local part of the list address, stored lowercase. Letters, digits, '.', '_' and '-' only, no dot at either end or two in a row. domain: type: string description: ASCII host name (labels of 1 to 63 letters, digits and hyphens). title: type: string maxLength: 200 description: A single line without control characters. Defaults to the name. 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, minLength: 1, maxLength: 200, description: A single line without control characters.} post_policy: {type: string, enum: [members, moderated, publishers], description: "publishers: a newsletter, only members flagged publisher may post"} 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} publisher: {type: boolean, description: "Absent: an existing member keeps its flag (a new one is not a publisher); true or false: set it"} 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'} patch: summary: Make a member a publisher or a plain subscriber requestBody: required: true content: application/json: schema: type: object required: [publisher] properties: publisher: {type: boolean} responses: '204': {description: Updated} '400': {$ref: '#/components/responses/Error'} '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'} /queue: get: summary: Outbound queue totals and up to 100 deliveries (failing ones first) responses: '200': description: OK content: application/json: schema: type: object properties: pending: {type: integer} retrying: {type: integer, description: Waiting deliveries that failed at least once} failed: {type: integer, description: Deliveries given up for good, kept for a week} oldest: {type: string, format: date-time, nullable: true} items: {type: array, items: {$ref: '#/components/schemas/QueueItem'}} /queue/{id}: parameters: - {name: id, in: path, required: true, schema: {type: integer}} delete: summary: Discard a queued delivery responses: '204': {description: Discarded} '404': {$ref: '#/components/responses/Error'} /lists/{id}/archive/import: parameters: - {name: id, in: path, required: true, schema: {type: integer}} post: summary: Import an mbox file into the archive description: > The request body is the mbox file itself (any content type, `application/mbox` by convention), streamed. Idempotent: a message already archived (same Message-ID) is counted as a duplicate. Threads are rebuilt at the end. Works whatever the list's archive policy. Messages that cannot be read are reported in the summary and do not fail the request; a read error while receiving the body does (400), keeping the messages read so far. requestBody: required: true content: application/mbox: schema: {type: string, format: binary} responses: '200': description: Summary content: application/json: schema: type: object properties: imported: {type: integer} duplicates: {type: integer} failed: {type: integer} errors: {type: array, items: {type: string}, description: The first 20 failures} '400': {$ref: '#/components/responses/Error'} '404': {$ref: '#/components/responses/Error'}