openapi: 3.0.0
info:
  description: A simple endpoint to send email messages
  version: '0.5'
  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'
                  warning:
                    type: array
                    description: 'Array of warning messages generated during the sending process, if any'
                    items:
                      type: string
                      
servers:
  - url: 'https://expmail.kumi.live'
components:
  schemas:
    Config:
      type: string
    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.'
        cid:
          type: string
          description: 'Content ID for the attachment, needed for embedded images - use something like `<img src="cid:YOUR_CID">` in your HTML code'
    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, or the `noconversion` config key is not 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 if `html` if provided. If both `htmlurl` and `text` or `texturl` are provided, or the `noconversion` config key is not 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 if `text` is provided. If both `texturl` and `html` or `htmlurl` are provided, will create a multi-part MIME message.'
        sender:
          allOf:
            - description: '`Recipient` object to be used as "From:" address for the email'
            - $ref: '#/components/schemas/Recipient'
        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'
        config:
          type: array
          description: >
            Array of `Config` keys to change the default behaviour
              * `allowempty` - Allow messages to have an empty body, would otherwise return an error
              * `ignoredlfails` - If an attachment fails to download, just leave it out and continue processing the message
              * `noconversion` - Do not automatically convert HTML to plain text if no plain text message is explicitly given
              * `urlbeforestring` - If both a string and a URL are given for the HTML or plain text content, prefer URL (else: prefer string)
          items:
            $ref: '#/components/schemas/Config'
        key:
          type: string
          description: API key to authenticate request with