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"