feat(api): list the posts of a list with their delivery counters

- GET /api/v1/lists/{id}/posts?limit= returns id, message_id, subject,
  created_at, recipients, sent, failed, dropped and pending, newest
  first; 404 for an unknown list, 400 for a bad limit, token required
- discarding a queued delivery counts it as dropped (store.DropOutbox)
- openapi: the new path and the discard note
This commit is contained in:
tgiachi 2026-11-10 12:40:55 +01:00
commit 2f2ee71f92

View file

@ -287,6 +287,7 @@ paths:
- {name: id, in: path, required: true, schema: {type: integer}}
delete:
summary: Discard a queued delivery
description: A waiting delivery of a post counts as dropped in the post's counters; a failed one stays counted as failed.
responses:
'204': {description: Discarded}
'404': {$ref: '#/components/responses/Error'}
@ -319,3 +320,34 @@ paths:
errors: {type: array, items: {type: string}, description: The first 20 failures}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}
/lists/{id}/posts:
parameters:
- {name: id, in: path, required: true, schema: {type: integer}}
get:
summary: Posts queued to the list with their delivery counters, newest first
description: >
One entry per post queued to the list (delivered or approved), kept for 400 days. Confirmation mail is not a post.
Bodies are never read.
parameters:
- {name: limit, in: query, schema: {type: integer, default: 50, maximum: 200}, description: 0 means the default; more than 200 gives 200}
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
id: {type: integer}
message_id: {type: string, description: The Message-ID header, at most 200 characters; empty when there was none}
subject: {type: string, description: Decoded, at most 200 characters, control characters removed}
created_at: {type: string, format: date-time}
recipients: {type: integer, description: Deliveries queued (members at the time of the post)}
sent: {type: integer, description: Accepted by the relay}
failed: {type: integer, description: Given up for good (refused by the relay, or still failing after 3 days)}
dropped: {type: integer, description: The mailbox does not exist, or the delivery was discarded}
pending: {type: integer, description: "Still in the queue: recipients - sent - failed - dropped"}
'400': {$ref: '#/components/responses/Error'}
'404': {$ref: '#/components/responses/Error'}