{
  "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"
          }
        }
      }
    }
  }
}