diff --git a/doc/swagger.json b/doc/swagger.json index 66186d7..14ebd06 100644 --- a/doc/swagger.json +++ b/doc/swagger.json @@ -1,124 +1,188 @@ -swagger: "2.0" -info: - description: "A simple endpoint to send email messages" - version: "0.1" - title: "EXPMail" - contact: - email: "support@kumi.systems" -host: "expmail.kumi.live" -tags: -- name: "sending" - description: "Sending out an email" -schemes: -- "https" -paths: - /sender.php: - post: - tags: - - "sending" - summary: "Send out an email" - operationId: "sendMail" - consumes: - - "application/json" - produces: - - "application/json" - parameters: - - in: "body" - name: "data" - description: "Object defining the email message to be sent" - required: true - schema: - $ref: "#/definitions/Mail" - responses: - 200: - description: "The request was received and processed." - schema: - type: "object" - properties: - status: - type: "string" - description: "\"Success\" if message was successfully sent, else \"error\"" - error: - type: "string" - description: "Error message, only included if an error has occurred" -definitions: - Placeholder: - type: "object" - required: ["name"] - properties: - name: - type: "string" - description: "Name of the placeholder - will be converted to ALL CAPS by the server if it isn't already" - value: - type: "string" - description: "Value to insert into placeholder" - Attachment: - type: "object" - required: ["url"] - properties: - url: - type: "string" - format: "url" - description: "URL from where to fetch the file to attach" - filename: - type: "string" - description: "File name to use for email attachment. If not set, defaults to name from Content-Disposition header of URL if it exists, else the base name of the URL." - Recipient: - type: "object" - required: ["email"] - properties: - email: - type: "string" - format: "email" - description: "Email address of the recipient" - name: - type: "string" - description: "Name of the recipient" - Mail: - type: "object" - required: ["recipients", "key"] - properties: - subject: - type: "string" - description: "Subject of the email" - html: - type: "string" - description: "String containing the HTML content of the email. Takes precedence over `htmlurl` if provided. If both `html` and `text` or `texturl` are provided, will create a multi-part MIME message." - htmlurl: - type: "string" - description: "String containing the URL to a file containing the HTML content of the email. Ignored (but still validated) if `html` if provided. If both `htmlurl` and `text` or `texturl` are provided, will create a multi-part MIME message." - text: - type: "string" - description: "String containing the plain text content of the email. Takes precedence over `texturl` if provided. If both `text` and `html` or `htmlurl` are provided, will create a multi-part MIME message." - texturl: - type: "string" - description: "String containing the URL to a file containing the plain text content of the email. Ignored (but still validated) if `text` is provided. If both `texturl` and `html` or `htmlurl` are provided, will create a multi-part MIME message." - recipients: - type: "array" - description: "Array of `Recipient` objects to be used as \"To:\" addresses for the email" - items: - $ref: "#/definitions/Recipient" - ccs: - type: "array" - description: "Array of `Recipient` objects to be used as \"CC:\" addresses for the email" - items: - $ref: "#/definitions/Recipient" - bccs: - type: "array" - description: "Array of `Recipient` objects to be used as \"BCC:\" addresses for the email" - items: - $ref: "#/definitions/Recipient" - attachments: - type: "array" - description: "Array of `Attachment` objects to be attached to the email" - items: - $ref: "#/definitions/Attachment" - placeholders: - type: "array" - description: "Array of `Placeholder` objects. Any occurrences of `{PLACEHOLDER_NAME}` (`name` in all caps enclosed with curly brackets) in the email's HTML or plain text will be replaced by `value`." - items: - $ref: "#/definitions/Placeholder" - key: - type: "string" - description: "API key to authenticate request with" - +{ + "openapi": "3.0.0", + "info": { + "description": "A simple endpoint to send email messages", + "version": "0.1", + "title": "EXPMail", + "contact": { + "email": "support@kumi.systems" + } + }, + "tags": [ + { + "name": "sending", + "description": "Sending out an email" + } + ], + "paths": { + "/sender.php": { + "post": { + "tags": [ + "sending" + ], + "summary": "Send out an email", + "operationId": "sendMail", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Mail" + } + } + }, + "description": "Object defining the email message to be sent", + "required": true + }, + "responses": { + "200": { + "description": "The request was received and processed.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "type": "string", + "description": "\"Success\" if message was successfully sent, else \"error\"" + }, + "error": { + "type": "string", + "description": "Error message, only included if an error has occurred" + } + } + } + } + } + } + } + } + } + }, + "servers": [ + { + "url": "https://expmail.kumi.live" + } + ], + "components": { + "schemas": { + "Placeholder": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "Name of the placeholder - will be converted to ALL CAPS by the server if it isn't already" + }, + "value": { + "type": "string", + "description": "Value to insert into placeholder" + } + } + }, + "Attachment": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string", + "format": "url", + "description": "URL from where to fetch the file to attach" + }, + "filename": { + "type": "string", + "description": "File name to use for email attachment. If not set, defaults to name from Content-Disposition header of URL if it exists, else the base name of the URL." + } + } + }, + "Recipient": { + "type": "object", + "required": [ + "email" + ], + "properties": { + "email": { + "type": "string", + "format": "email", + "description": "Email address of the recipient" + }, + "name": { + "type": "string", + "description": "Name of the recipient" + } + } + }, + "Mail": { + "type": "object", + "required": [ + "recipients", + "key" + ], + "properties": { + "subject": { + "type": "string", + "description": "Subject of the email" + }, + "html": { + "type": "string", + "description": "String containing the HTML content of the email. Takes precedence over `htmlurl` if provided. If both `html` and `text` or `texturl` are provided, will create a multi-part MIME message." + }, + "htmlurl": { + "type": "string", + "description": "String containing the URL to a file containing the HTML content of the email. Ignored (but still validated) if `html` if provided. If both `htmlurl` and `text` or `texturl` are provided, will create a multi-part MIME message." + }, + "text": { + "type": "string", + "description": "String containing the plain text content of the email. Takes precedence over `texturl` if provided. If both `text` and `html` or `htmlurl` are provided, will create a multi-part MIME message." + }, + "texturl": { + "type": "string", + "description": "String containing the URL to a file containing the plain text content of the email. Ignored (but still validated) if `text` is provided. If both `texturl` and `html` or `htmlurl` are provided, will create a multi-part MIME message." + }, + "recipients": { + "type": "array", + "description": "Array of `Recipient` objects to be used as \"To:\" addresses for the email", + "items": { + "$ref": "#/components/schemas/Recipient" + } + }, + "ccs": { + "type": "array", + "description": "Array of `Recipient` objects to be used as \"CC:\" addresses for the email", + "items": { + "$ref": "#/components/schemas/Recipient" + } + }, + "bccs": { + "type": "array", + "description": "Array of `Recipient` objects to be used as \"BCC:\" addresses for the email", + "items": { + "$ref": "#/components/schemas/Recipient" + } + }, + "attachments": { + "type": "array", + "description": "Array of `Attachment` objects to be attached to the email", + "items": { + "$ref": "#/components/schemas/Attachment" + } + }, + "placeholders": { + "type": "array", + "description": "Array of `Placeholder` objects. Any occurrences of `{PLACEHOLDER_NAME}` (`name` in all caps enclosed with curly brackets) in the email's HTML or plain text will be replaced by `value`.", + "items": { + "$ref": "#/components/schemas/Placeholder" + } + }, + "key": { + "type": "string", + "description": "API key to authenticate request with" + } + } + } + } + } +} \ No newline at end of file