- openapi: name, domain and title constraints of POST /lists, title of PATCH - README: the rules, the RFC 2047 List-Id, single-use and re-usable confirmation, rejoin after bounces
321 lines
11 KiB
YAML
321 lines
11 KiB
YAML
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}
|
|
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; re-adding the member re-enables it}
|
|
bounce_count: {type: integer}
|
|
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]}
|
|
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'}
|
|
/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'}
|