Skip to content

High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.

fix: update OpenAPI specs for routes and correct docs for campaign endpoints (#2179)

Dylan Cetinfce46b2103b1
diff --git a/docs/docs/content/apis/campaigns.md b/docs/docs/content/apis/campaigns.md
index 06140e11..1c7d7bbd 100644
--- a/docs/docs/content/apis/campaigns.md
+++ b/docs/docs/content/apis/campaigns.md
@@ -37,6 +37,7 @@ Retrieve all campaigns.
| tags | []string | | Tags to filter campaigns. Repeat in the query for multiple values. |
| page | number | | Page number for paginated results. |
| per_page | number | | Results per page. Set as 'all' for all results. |
+| no_body | boolean | | When set to true, returns response without body content. |
##### Example Response
@@ -94,6 +95,7 @@ Retrieve a specific campaign.
| Name | Type | Required | Description |
|:------------|:----------|:---------|:-------------|
| campaign_id | number | Yes | Campaign ID. |
+| no_body | boolean | | When set to true, returns response without body content. |
##### Example Request
@@ -201,8 +203,8 @@ Retrieve stats of specified campaigns.
|:------------|:----------|:---------|:----------------------------------------------|
| id |number\[\] | Yes | Campaign IDs to get stats for. |
| type |string | Yes | Analytics type: views, links, clicks, bounces |
-| from |string | Yes | Campaign IDs to get stats for. |
-| to |string | Yes | Campaign IDs to get stats for. |
+| from |string | Yes | Start value of date range. |
+| to |string | Yes | End value of date range. |
##### Example Request
diff --git a/docs/swagger/collections.yaml b/docs/swagger/collections.yaml
index f6b155cd..cec5fc78 100644
--- a/docs/swagger/collections.yaml
+++ b/docs/swagger/collections.yaml
@@ -256,21 +256,56 @@ paths:
parameters:
- in: query
name: page
- description: number of records to skip
+ description: Page number for paginated results.
+ required: false
schema:
type: integer
format: int32
- in: query
name: per_page
- description: max number of records to return per page
+ description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
+ required: false
schema:
- type: integer
- format: int32
+ oneOf:
+ - type: integer
+ description: Number of items to return per page
+ - type: string
+ enum: ["all"]
+ description: Return all results without pagination
- in: query
name: query
description: query subscribers with an SQL expression.
+ required: false
+ schema:
+ type: string
+ - in: query
+ name: order_by
+ description: Result sorting field. Options are name, status, created_at, updated_at
+ required: false
schema:
type: string
+ enum: ["name", "status", "created_at", "updated_at"]
+ - in: query
+ name: order
+ description: ASC|DESC Sort by ascending or descending order.
+ required: false
+ schema:
+ type: string
+ enum: ["ASC", "DESC"]
+ - in: query
+ name: subscription_status
+ description: Subscription status to filter by if there are one or more list_ids.
+ required: false
+ schema:
+ type: string
+ - in: query
+ name: list_id
+ description: ID of lists to filter by. Repeat in the query for multiple values.
+ required: false
+ schema:
+ type: array
+ items:
+ type: integer
responses:
"200":
@@ -719,36 +754,45 @@ paths:
operationId: getBounces
tags:
- Bounces
- requestBody:
- description: output parameters form
- required: true
- content:
- application/x-www-form-urlencoded:
- schema:
- type: object
- properties:
- source:
- type: string
- order_by:
- type: string
- order:
- type: string
parameters:
- in: query
name: campaign_id
- description: bounce record retrieval of particular campaign
+ description: Numeric identifier for retrieving bounce records associated with a specific campaign
schema:
type: integer
- in: query
name: page
- description: total number of pages
+ description: Page number for paginated results. Start from 1 for the first page
schema:
type: integer
- in: query
name: per_page
- description: number of items per page
+ description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
schema:
- type: integer
+ oneOf:
+ - type: integer
+ description: Number of items to return per page
+ - type: string
+ enum:
+ - "all"
+ description: Return all results without pagination
+ - in: query
+ name: source
+ description: Filter bounce records by their source of origin
+ schema:
+ type: string
+ - in: query
+ name: order_by
+ description: Specifies the field by which to sort the bounce records. Available options are 'email', 'campaign_name', 'source', and 'created_at'
+ schema:
+ type: string
+ enum: ["email", "campaign_name", "source", "created_at"]
+ - in: query
+ name: order
+ description: Determines the sort order of results. Use 'asc' for ascending or 'desc' for descending order
+ schema:
+ type: string
+ enum: ["asc", "desc"]
responses:
"200":
description: list of bounce records
@@ -856,32 +900,54 @@ paths:
- in: query
name: page
description: total number of pages
+ required: false
schema:
type: integer
- in: query
name: per_page
description: number of items per page
+ required: false
schema:
- type: integer
- requestBody:
- required: true
- description: output parameters form
- content:
- application/x-www-form-urlencoded:
- schema:
- type: object
- properties:
- query:
- description: Optional string to search a list by name.
- type: string
- order_by:
- description: Field to sort results by. name|status|created_at|updated_at
- type: string
- order:
- description: ASC|DESC Sort by ascending or descending order.
- type: string
- minimal:
- type: boolean
+ oneOf:
+ - type: integer
+ description: Number of items to return per page
+ - type: string
+ enum: ["all"]
+ description: Return all results without pagination
+ - in: query
+ name: query
+ description: Optional string to search a list by name.
+ required: false
+ schema:
+ type: string
+ - in: query
+ name: order_by
+ description: Field to sort results by. name|status|created_at|updated_at
+ required: false
+ schema:
+ type: string
+ enum: ["name", "status", "created_at", "updated_at"]
+ - in: query
+ name: order
+ description: ASC|DESC Sort by ascending or descending order.
+ required: false
+ schema:
+ type: string
+ enum: ["ASC", "DESC"]
+ - in: query
+ name: minimal
+ description: When set to true, returns response without body content
+ required: false
+ schema:
+ type: boolean
+ - in: query
+ name: tag
+ description: Tags to filter lists. Repeat in the query for multiple values.
+ required: false
+ schema:
+ type: array
+ items:
+ type: string
responses:
"200":
description: list of metadata
@@ -1027,14 +1093,18 @@ paths:
requestBody:
description: uploads and bulk imports of compressed CSV files
content:
- application/json:
+ multipart/form-data:
schema:
type: object
properties:
params:
type: string
+ description: JSON string containing import parameters for more detail https://listmonk.app/docs/apis/import/#params-json-string
+ example: '{"mode":"subscribe", "subscription_status":"confirmed", "delim":",", "lists":[1, 2], "overwrite": true}'
file:
type: string
+ format: binary
+ description: File for upload.
responses:
"200":
description: updated import status
@@ -1086,45 +1156,64 @@ paths:
parameters:
- in: query
name: status
- description: status flag of campaign
+ description: Filter campaigns by status. Multiple status values can be specified by repeating the parameter
+ required: false
schema:
type: array
items:
type: string
- enum: [scheduled, running, paused, cancelled]
+ enum: ["scheduled", "running", "paused", "cancelled"]
- in: query
name: no_body
- description: boolean flag for response with/without body
+ description: When set to true, returns response without body content
+ required: false
schema:
type: boolean
- in: query
name: page
- description: total number of pages
+ description: Page number for paginated results.
+ required: false
schema:
type: integer
- in: query
name: per_page
- description: number of items per page
+ description: Number of items per page. Use an integer for specific page size or 'all' to retrieve all results
+ required: false
schema:
- type: integer
- requestBody:
- required: true
- description: output parameters form
- content:
- application/x-www-form-urlencoded:
- schema:
- type: object
- properties:
- query:
- description: Optional string to search a list by name.
- type: string
- order_by:
- description: Field to sort results by. name|status|created_at|updated_at
- type: string
- order:
- description: ASC|DESC Sort by ascending or descending order.
- type: string
-
+ oneOf:
+ - type: integer
+ description: Number of items to return per page
+ - type: string
+ enum: ["all"]
+ description: Return all results without pagination
+ - in: query
+ name: tags
+ description: Filter campaigns by tags. Multiple tags can be specified by repeating the parameter
+ required: false
+ schema:
+ type: array
+ items:
+ type: string
+ - in: query
+ name: order
+ description: Determines the sort order of results. ASC for ascending, DESC for descending order
+ required: false
+ schema:
+ type: string
+ enum: ["ASC", "DESC"]
+ - in: query
+ name: order_by
+ description: Specifies the field by which to sort the campaigns. Available options are 'name', 'status', 'created_at', and 'updated_at'
+ required: false
+ schema:
+ type: string
+ enum: ["name", "status", "created_at", "updated_at"]
+ - in: query
+ name: query
+ description: SQL query expression to filter campaigns by custom criteria
+ required: false
+ schema:
+ type: string
tags:
- Campaigns
responses:
@@ -1262,6 +1351,13 @@ paths:
operationId: getRunningCampaignStats
tags:
- Campaigns
+ parameters:
+ - in: query
+ name: campaign_id
+ description: Campaign IDs to get stats for.
+ required: true
+ schema:
+ type: number
responses:
"200":
description: list of stats for given set of campaign ids
@@ -1295,6 +1391,7 @@ paths:
description: start value of date range
schema:
type: string
+ format: date
- in: query
required: true
name: to
@@ -1304,6 +1401,7 @@ paths:
- in: query
name: id
description: campaign id/s to retrive view counts
+ required: true
schema:
type: string
responses:
@@ -1332,17 +1430,6 @@ paths:
description: The id value of the campaign you want to get the preview of
schema:
type: integer
- requestBody:
- required: true
- description: template id
- content:
- application/x-www-form-urlencoded:
- schema:
- type: object
- properties:
- template_id:
- description: template id
- type: integer
responses:
"200":
description: HTML Preview of requested campaign