diff --git a/server/apiv1/api.go b/server/apiv1/api.go
index c1f64a7..4fb20e1 100644
--- a/server/apiv1/api.go
+++ b/server/apiv1/api.go
@@ -144,11 +144,11 @@ func Search(w http.ResponseWriter, r *http.Request) {
// DeleteSearch will delete all messages matching a search
func DeleteSearch(w http.ResponseWriter, r *http.Request) {
- // swagger:route DELETE /api/v1/search messages MessagesSummary
+ // swagger:route DELETE /api/v1/search messages DeleteSearch
//
// # Delete messages by search
//
- // Deletes messages matching a search.
+ // Delete all messages matching a search.
//
// Produces:
// - application/json
@@ -196,7 +196,7 @@ func GetMessage(w http.ResponseWriter, r *http.Request) {
// Parameters:
// + name: ID
// in: path
- // description: Database ID
+ // description: Message database ID
// required: true
// type: string
//
@@ -237,7 +237,7 @@ func DownloadAttachment(w http.ResponseWriter, r *http.Request) {
// Parameters:
// + name: ID
// in: path
- // description: Database ID
+ // description: Message database ID
// required: true
// type: string
// + name: PartID
@@ -362,11 +362,11 @@ func DownloadRaw(w http.ResponseWriter, r *http.Request) {
// DeleteMessages (method: DELETE) deletes all messages matching IDS.
func DeleteMessages(w http.ResponseWriter, r *http.Request) {
- // swagger:route DELETE /api/v1/messages messages Delete
+ // swagger:route DELETE /api/v1/messages messages DeleteMessages
//
// # Delete messages
//
- // If no IDs are provided then all messages are deleted.
+ // Delete individual or all messages. If no IDs are provided then all messages are deleted.
//
// Consumes:
// - application/json
@@ -376,13 +376,6 @@ func DeleteMessages(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
- // Parameters:
- // + name: ids
- // in: body
- // description: Database IDs to delete
- // required: false
- // type: DeleteRequest
- //
// Responses:
// 200: OKResponse
// default: ErrorResponse
@@ -406,7 +399,7 @@ func DeleteMessages(w http.ResponseWriter, r *http.Request) {
}
}
- w.Header().Add("Content-Type", "application/json")
+ w.Header().Add("Content-Type", "application/plain")
_, _ = w.Write([]byte("ok"))
}
@@ -427,13 +420,6 @@ func SetReadStatus(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
- // Parameters:
- // + name: ids
- // in: body
- // description: Database IDs to update
- // required: false
- // type: SetReadStatusRequest
- //
// Responses:
// 200: OKResponse
// default: ErrorResponse
@@ -491,7 +477,7 @@ func SetReadStatus(w http.ResponseWriter, r *http.Request) {
// GetTags (method: GET) will get all tags currently in use
func GetTags(w http.ResponseWriter, _ *http.Request) {
- // swagger:route GET /api/v1/tags tags SetTags
+ // swagger:route GET /api/v1/tags tags GetTags
//
// # Get all current tags
//
@@ -524,7 +510,7 @@ func SetTags(w http.ResponseWriter, r *http.Request) {
//
// # Set message tags
//
- // To remove all tags from a message, pass an empty tags array.
+ // This will overwrite any existing tags for selected message database IDs. To remove all tags from a message, pass an empty tags array.
//
// Consumes:
// - application/json
@@ -534,13 +520,6 @@ func SetTags(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
- // Parameters:
- // + name: ids
- // in: body
- // description: Database IDs to update
- // required: true
- // type: SetTagsRequest
- //
// Responses:
// 200: OKResponse
// default: ErrorResponse
@@ -576,11 +555,11 @@ func SetTags(w http.ResponseWriter, r *http.Request) {
// ReleaseMessage (method: POST) will release a message via a pre-configured external SMTP server.
// If no IDs are provided then all messages are updated.
func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
- // swagger:route POST /api/v1/message/{ID}/release message Release
+ // swagger:route POST /api/v1/message/{ID}/release message ReleaseMessage
//
// # Release message
//
- // Release a message via a pre-configured external SMTP server..
+ // Release a message via a pre-configured external SMTP server. This is only enabled if message relaying has been configured.
//
// Consumes:
// - application/json
@@ -590,18 +569,6 @@ func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
- // Parameters:
- // + name: ID
- // in: path
- // description: Database ID
- // required: true
- // type: string
- // + name: to
- // in: body
- // description: Array of email addresses to release message to
- // required: true
- // type: ReleaseMessageRequest
- //
// Responses:
// 200: OKResponse
// default: ErrorResponse
@@ -618,7 +585,7 @@ func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
decoder := json.NewDecoder(r.Body)
- data := releaseMessageRequest{}
+ data := releaseMessageRequestBody{}
if err := decoder.Decode(&data); err != nil {
httpError(w, err.Error())
@@ -702,7 +669,7 @@ func ReleaseMessage(w http.ResponseWriter, r *http.Request) {
// HTMLCheck returns a summary of the HTML client support
func HTMLCheck(w http.ResponseWriter, r *http.Request) {
- // swagger:route GET /api/v1/message/{ID}/html-check Other HTMLCheckResponse
+ // swagger:route GET /api/v1/message/{ID}/html-check Other HTMLCheck
//
// # HTML check (beta)
//
@@ -716,13 +683,6 @@ func HTMLCheck(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
- // Parameters:
- // + name: ID
- // in: path
- // description: Database ID
- // required: true
- // type: string
- //
// Responses:
// 200: HTMLCheckResponse
// default: ErrorResponse
@@ -754,7 +714,7 @@ func HTMLCheck(w http.ResponseWriter, r *http.Request) {
// LinkCheck returns a summary of links in the email
func LinkCheck(w http.ResponseWriter, r *http.Request) {
- // swagger:route GET /api/v1/message/{ID}/link-check Other LinkCheckResponse
+ // swagger:route GET /api/v1/message/{ID}/link-check Other LinkCheck
//
// # Link check (beta)
//
@@ -768,19 +728,6 @@ func LinkCheck(w http.ResponseWriter, r *http.Request) {
//
// Schemes: http, https
//
- // Parameters:
- // + name: ID
- // in: path
- // description: Database ID
- // required: true
- // type: string
- // + name: follow
- // in: query
- // description: Follow redirects
- // required: false
- // type: boolean
- // default: false
- //
// Responses:
// 200: LinkCheckResponse
// default: ErrorResponse
diff --git a/server/apiv1/structs.go b/server/apiv1/structs.go
index 318ef69..8bf1290 100644
--- a/server/apiv1/structs.go
+++ b/server/apiv1/structs.go
@@ -22,9 +22,6 @@ type MessagesSummary struct {
// Total number of messages matching current query
MessagesCount int `json:"messages_count"`
- // // Number of results returned on current page
- // Count int `json:"count"`
-
// Pagination offset
Start int `json:"start"`
@@ -32,7 +29,7 @@ type MessagesSummary struct {
Tags []string `json:"tags"`
// Messages summary
- // in:body
+ // in: body
Messages []storage.MessageSummary `json:"messages"`
}
diff --git a/server/apiv1/swagger.go b/server/apiv1/swagger.go
index 43e0646..583714f 100644
--- a/server/apiv1/swagger.go
+++ b/server/apiv1/swagger.go
@@ -6,6 +6,8 @@ package apiv1
// swagger:response InfoResponse
type infoResponse struct {
// Application information
+ //
+ // in: body
Body appInformation
}
@@ -13,6 +15,8 @@ type infoResponse struct {
// swagger:response WebUIConfigurationResponse
type webUIConfigurationResponse struct {
// Web UI configuration settings
+ //
+ // in: body
Body webUIConfiguration
}
@@ -28,81 +32,137 @@ type messagesSummaryResponse struct {
// swagger:model MessageHeaders
type messageHeaders map[string][]string
+// swagger:parameters DeleteMessages
+type deleteMessagesParams struct {
+ // in: body
+ Body *deleteMessagesRequestBody
+}
+
// Delete request
// swagger:model DeleteRequest
-type deleteRequest struct {
- // ids
- // in:body
+type deleteMessagesRequestBody struct {
+ // Array of message database IDs
+ //
+ // required: false
+ // example: ["5dec4247-812e-4b77-9101-e25ad406e9ea", "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"]
IDs []string `json:"ids"`
}
+// swagger:parameters SetReadStatus
+type setReadStatusParams struct {
+ // in: body
+ Body *setReadStatusRequestBody
+}
+
// Set read status request
-// swagger:model SetReadStatusRequest
-type setReadStatusRequest struct {
+// swagger:model setReadStatusRequestBody
+type setReadStatusRequestBody struct {
// Read status
+ //
+ // required: false
+ // default: false
+ // example: true
Read bool `json:"read"`
- // ids
- // in:body
+ // Array of message database IDs
+ //
+ // required: false
+ // example: ["5dec4247-812e-4b77-9101-e25ad406e9ea", "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"]
IDs []string `json:"ids"`
}
+// swagger:parameters SetTags
+type setTagsParams struct {
+ // in: body
+ Body *setTagsRequestBody
+}
+
// Set tags request
-// swagger:model SetTagsRequest
-type setTagsRequest struct {
- // Tags
- // in:body
+// swagger:model setTagsRequestBody
+type setTagsRequestBody struct {
+ // Array of tag names to set
+ //
+ // required: true
+ // example: ["Tag 1", "Tag 2"]
Tags []string `json:"tags"`
- // IDs
- // in:body
+ // Array of message database IDs
+ //
+ // required: true
+ // example: ["5dec4247-812e-4b77-9101-e25ad406e9ea", "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"]
IDs []string `json:"ids"`
}
+// swagger:parameters ReleaseMessage
+type releaseMessageParams struct {
+ // Message database ID
+ //
+ // in: path
+ // description: Message database ID
+ // required: true
+ ID string
+
+ // in: body
+ Body *releaseMessageRequestBody
+}
+
// Release request
-// swagger:model ReleaseMessageRequest
-type releaseMessageRequest struct {
- // To
- // in:body
+// swagger:model releaseMessageRequestBody
+type releaseMessageRequestBody struct {
+ // Array of email addresses to relay the message to
+ //
+ // required: true
+ // example: ["user1@example.com", "user2@example.com"]
To []string `json:"to"`
}
+// swagger:parameters HTMLCheck
+type htmlCheckParams struct {
+ // Message database ID
+ //
+ // in: path
+ // description: Message database ID
+ // required: true
+ ID string
+}
+
+// swagger:parameters LinkCheck
+type linkCheckParams struct {
+ // Message database ID
+ //
+ // in: path
+ // description: Message database ID
+ // required: true
+ ID string
+
+ // Follow redirects
+ //
+ // in: query
+ // description: Follow redirects
+ // required: false
+ // default: false
+ Follow string `json:"follow"`
+}
+
// Binary data response inherits the attachment's content type
// swagger:response BinaryResponse
-type binaryResponse struct {
- // in: body
- Body string
-}
+type binaryResponse string
// Plain text response
// swagger:response TextResponse
-type textResponse struct {
- // in: body
- Body string
-}
+type textResponse string
// HTML response
// swagger:response HTMLResponse
-type htmlResponse struct {
- // in: body
- Body string
-}
+type htmlResponse string
// Error response
// swagger:response ErrorResponse
-type errorResponse struct {
- // The error message
- // in: body
- Body string
-}
+type errorResponse string
// Plain text "ok" response
// swagger:response OKResponse
-type okResponse struct {
- // Default response
- // in: body
- Body string
-}
+type okResponse string
// Plain JSON array response
// swagger:response ArrayResponse
diff --git a/server/ui/api/v1/swagger.json b/server/ui/api/v1/swagger.json
index d0a85a5..c85fff4 100644
--- a/server/ui/api/v1/swagger.json
+++ b/server/ui/api/v1/swagger.json
@@ -66,7 +66,7 @@
"parameters": [
{
"type": "string",
- "description": "Database ID",
+ "description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
@@ -136,11 +136,11 @@
"Other"
],
"summary": "HTML check (beta)",
- "operationId": "HTMLCheckResponse",
+ "operationId": "HTMLCheck",
"parameters": [
{
"type": "string",
- "description": "Database ID",
+ "description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
@@ -173,18 +173,19 @@
"Other"
],
"summary": "Link check (beta)",
- "operationId": "LinkCheckResponse",
+ "operationId": "LinkCheck",
"parameters": [
{
"type": "string",
- "description": "Database ID",
+ "description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
},
{
- "type": "boolean",
- "default": false,
+ "type": "string",
+ "default": "false",
+ "x-go-name": "Follow",
"description": "Follow redirects",
"name": "follow",
"in": "query"
@@ -223,7 +224,7 @@
"parameters": [
{
"type": "string",
- "description": "Database ID",
+ "description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
@@ -323,7 +324,7 @@
},
"/api/v1/message/{ID}/release": {
"post": {
- "description": "Release a message via a pre-configured external SMTP server..",
+ "description": "Release a message via a pre-configured external SMTP server. This is only enabled if message relaying has been configured.",
"consumes": [
"application/json"
],
@@ -338,24 +339,20 @@
"message"
],
"summary": "Release message",
- "operationId": "Release",
+ "operationId": "ReleaseMessage",
"parameters": [
{
"type": "string",
- "description": "Database ID",
+ "description": "Message database ID",
"name": "ID",
"in": "path",
"required": true
},
{
- "description": "Array of email addresses to release message to",
- "name": "to",
+ "name": "Body",
"in": "body",
- "required": true,
"schema": {
- "description": "Array of email addresses to release message to",
- "type": "object",
- "$ref": "#/definitions/ReleaseMessageRequest"
+ "$ref": "#/definitions/releaseMessageRequestBody"
}
}
],
@@ -428,13 +425,10 @@
"operationId": "SetReadStatus",
"parameters": [
{
- "description": "Database IDs to update",
- "name": "ids",
+ "name": "Body",
"in": "body",
"schema": {
- "description": "Database IDs to update",
- "type": "object",
- "$ref": "#/definitions/SetReadStatusRequest"
+ "$ref": "#/definitions/setReadStatusRequestBody"
}
}
],
@@ -448,7 +442,7 @@
}
},
"delete": {
- "description": "If no IDs are provided then all messages are deleted.",
+ "description": "Delete individual or all messages. If no IDs are provided then all messages are deleted.",
"consumes": [
"application/json"
],
@@ -463,15 +457,12 @@
"messages"
],
"summary": "Delete messages",
- "operationId": "Delete",
+ "operationId": "DeleteMessages",
"parameters": [
{
- "description": "Database IDs to delete",
- "name": "ids",
+ "name": "Body",
"in": "body",
"schema": {
- "description": "Database IDs to delete",
- "type": "object",
"$ref": "#/definitions/DeleteRequest"
}
}
@@ -534,7 +525,7 @@
}
},
"delete": {
- "description": "Deletes messages matching a search.",
+ "description": "Delete all messages matching a search.",
"produces": [
"application/json"
],
@@ -546,7 +537,7 @@
"messages"
],
"summary": "Delete messages by search",
- "operationId": "MessagesSummary",
+ "operationId": "DeleteSearch",
"parameters": [
{
"type": "string",
@@ -580,7 +571,7 @@
"tags"
],
"summary": "Get all current tags",
- "operationId": "SetTags",
+ "operationId": "GetTags",
"responses": {
"200": {
"$ref": "#/responses/ArrayResponse"
@@ -591,7 +582,7 @@
}
},
"put": {
- "description": "To remove all tags from a message, pass an empty tags array.",
+ "description": "This will overwrite any existing tags for selected message database IDs. To remove all tags from a message, pass an empty tags array.",
"consumes": [
"application/json"
],
@@ -609,14 +600,10 @@
"operationId": "SetTags",
"parameters": [
{
- "description": "Database IDs to update",
- "name": "ids",
+ "name": "Body",
"in": "body",
- "required": true,
"schema": {
- "description": "Database IDs to update",
- "type": "object",
- "$ref": "#/definitions/SetTagsRequest"
+ "$ref": "#/definitions/setTagsRequestBody"
}
}
],
@@ -807,15 +794,19 @@
"type": "object",
"properties": {
"ids": {
- "description": "ids\nin:body",
+ "description": "Array of message database IDs",
"type": "array",
"items": {
"type": "string"
},
- "x-go-name": "IDs"
+ "x-go-name": "IDs",
+ "example": [
+ "5dec4247-812e-4b77-9101-e25ad406e9ea",
+ "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"
+ ]
}
},
- "x-go-name": "deleteRequest",
+ "x-go-name": "deleteMessagesRequestBody",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
"HTMLCheckResponse": {
@@ -1188,6 +1179,10 @@
"type": "integer",
"format": "int64"
},
+ "Snippet": {
+ "description": "Message snippet includes up to 250 characters",
+ "type": "string"
+ },
"Subject": {
"description": "Email subject",
"type": "string"
@@ -1214,7 +1209,7 @@
"type": "object",
"properties": {
"messages": {
- "description": "Messages summary\nin:body",
+ "description": "Messages summary\nin: body",
"type": "array",
"items": {
"$ref": "#/definitions/MessageSummary"
@@ -1256,67 +1251,6 @@
},
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
},
- "ReleaseMessageRequest": {
- "description": "Release request",
- "type": "object",
- "properties": {
- "to": {
- "description": "To\nin:body",
- "type": "array",
- "items": {
- "type": "string"
- },
- "x-go-name": "To"
- }
- },
- "x-go-name": "releaseMessageRequest",
- "x-go-package": "github.com/axllent/mailpit/server/apiv1"
- },
- "SetReadStatusRequest": {
- "description": "Set read status request",
- "type": "object",
- "properties": {
- "ids": {
- "description": "ids\nin:body",
- "type": "array",
- "items": {
- "type": "string"
- },
- "x-go-name": "IDs"
- },
- "read": {
- "description": "Read status",
- "type": "boolean",
- "x-go-name": "Read"
- }
- },
- "x-go-name": "setReadStatusRequest",
- "x-go-package": "github.com/axllent/mailpit/server/apiv1"
- },
- "SetTagsRequest": {
- "description": "Set tags request",
- "type": "object",
- "properties": {
- "ids": {
- "description": "IDs\nin:body",
- "type": "array",
- "items": {
- "type": "string"
- },
- "x-go-name": "IDs"
- },
- "tags": {
- "description": "Tags\nin:body",
- "type": "array",
- "items": {
- "type": "string"
- },
- "x-go-name": "Tags"
- }
- },
- "x-go-name": "setTagsRequest",
- "x-go-package": "github.com/axllent/mailpit/server/apiv1"
- },
"WebUIConfiguration": {
"description": "Response includes global web UI settings",
"type": "object",
@@ -1350,6 +1284,89 @@
},
"x-go-name": "webUIConfiguration",
"x-go-package": "github.com/axllent/mailpit/server/apiv1"
+ },
+ "releaseMessageRequestBody": {
+ "description": "Release request",
+ "type": "object",
+ "required": [
+ "to"
+ ],
+ "properties": {
+ "to": {
+ "description": "Array of email addresses to relay the message to",
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "x-go-name": "To",
+ "example": [
+ "user1@example.com",
+ "user2@example.com"
+ ]
+ }
+ },
+ "x-go-package": "github.com/axllent/mailpit/server/apiv1"
+ },
+ "setReadStatusRequestBody": {
+ "description": "Set read status request",
+ "type": "object",
+ "properties": {
+ "ids": {
+ "description": "Array of message database IDs",
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "x-go-name": "IDs",
+ "example": [
+ "5dec4247-812e-4b77-9101-e25ad406e9ea",
+ "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"
+ ]
+ },
+ "read": {
+ "description": "Read status",
+ "type": "boolean",
+ "default": false,
+ "x-go-name": "Read",
+ "example": true
+ }
+ },
+ "x-go-package": "github.com/axllent/mailpit/server/apiv1"
+ },
+ "setTagsRequestBody": {
+ "description": "Set tags request",
+ "type": "object",
+ "required": [
+ "tags",
+ "ids"
+ ],
+ "properties": {
+ "ids": {
+ "description": "Array of message database IDs",
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "x-go-name": "IDs",
+ "example": [
+ "5dec4247-812e-4b77-9101-e25ad406e9ea",
+ "8ac66bbc-2d9a-4c41-ad99-00aa75fa674e"
+ ]
+ },
+ "tags": {
+ "description": "Array of tag names to set",
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "x-go-name": "Tags",
+ "example": [
+ "Tag 1",
+ "Tag 2"
+ ]
+ }
+ },
+ "x-go-package": "github.com/axllent/mailpit/server/apiv1"
}
},
"responses": {
@@ -1363,23 +1380,27 @@
}
},
"BinaryResponse": {
- "description": "Binary data response inherits the attachment's content type"
+ "description": "Binary data response inherits the attachment's content type",
+ "schema": {
+ "type": "string"
+ }
},
"ErrorResponse": {
- "description": "Error response"
+ "description": "Error response",
+ "schema": {
+ "type": "string"
+ }
},
"HTMLResponse": {
- "description": "HTML response"
+ "description": "HTML response",
+ "schema": {
+ "type": "string"
+ }
},
"InfoResponse": {
"description": "Application information",
"schema": {
"$ref": "#/definitions/AppInformation"
- },
- "headers": {
- "Body": {
- "description": "Application information"
- }
}
},
"MessagesSummaryResponse": {
@@ -1389,20 +1410,21 @@
}
},
"OKResponse": {
- "description": "Plain text \"ok\" response"
+ "description": "Plain text \"ok\" response",
+ "schema": {
+ "type": "string"
+ }
},
"TextResponse": {
- "description": "Plain text response"
+ "description": "Plain text response",
+ "schema": {
+ "type": "string"
+ }
},
"WebUIConfigurationResponse": {
"description": "Web UI configuration",
"schema": {
"$ref": "#/definitions/WebUIConfiguration"
- },
- "headers": {
- "Body": {
- "description": "Web UI configuration settings"
- }
}
}
}