openapi: 3.0.4
info:
  title: Email API
  description: |-
    Welcome the Voxtelesys Email API. This API allows you to send emails programmatically using the EmailSendRequest schema.
  version: v1
servers:
  - url: https://emailapi.voxtelesys.net/api/v1
paths:
  /email:
    post:
      tags:
        - Email
      security:
        - OAuth2: ['emailapi:email:manage']
      summary: Send an email
      description: Send an email using the EmailSendRequest schema.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailSendRequest'
      responses:
        '200':
          description: Email sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailSendResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '429':
          description: Too may requests
        '500':
          description: Internal server error
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://authapi.voxtelesys.net/api/v1/oauth/token
          scopes:
            emailapi:email:manage: Ability to send emails
  schemas:
    EmailSendResponse:
      type: object
      properties:
        batch_id:
          type: string
          description: Unique identifier for the batch of sent emails.
          example: "123e4567-e89b-12d3-a456-426614174000"
    EmailSendRequest:
      allOf:
        - $ref: '#/components/schemas/EmailSendRequestBase'
        - oneOf:
            - $ref: '#/components/schemas/EmailSendRequestHtml'
            - $ref: '#/components/schemas/EmailSendRequestProfile'
            - $ref: '#/components/schemas/EmailSendRequestTemplate'

    EmailSendRequestBase:
      type: object
      required:
        - to
        - from
        - subject
      properties:
        to:
          oneOf:
            - $ref: '#/components/schemas/EmailString'
            - $ref: '#/components/schemas/EmailArray'
          description: "Email Address(es) the email should be sent to."
        cc:
          oneOf:
            - $ref: '#/components/schemas/EmailString'
            - $ref: '#/components/schemas/EmailArray'
          description: "CC address(es) to tag onto the email."
        bcc:
          oneOf:
            - $ref: '#/components/schemas/EmailString'
            - $ref: '#/components/schemas/EmailArray'
          description: "BCC address(es) to tag onto the email."
          example: "bcc@example.com"
        from:
          type: string
          description: Sender email address.
          example: "sender@example.com"
        reply_to:
          type: string
          description: Reply-to email address.
          example: "replyto@example.com"
        subject:
          type: string
          description: Email subject.
          example: "Welcome!"
          maxLength: 1000
        html:
          type: string
          description: HTML content of the email.
          example: "<p>Hello!</p>"
          maxLength: 75000
        text:
          type: string
          description: Plain text content of the email.
          example: "Hello!"
        tag:
          type: string
          description: Tag for the email.
          example: "welcome"
        email_profile_guid:
          type: string
          description: Email profile GUID.
          example: "profile-guid"
        email_template_guid:
          type: string
          description: Email template GUID.
          example: "template-guid"
        email_template_version_guid:
          type: string
          description: Email template version GUID. (If not provided with email_template_guid, the default version will be used)
          example: "template-version-guid"
        email_template_variables:
          type: object
          additionalProperties: true
          description: Variables for the email template.
          example: { "firstName": "John" }
        bulk_tag:
          type: string
          description: Used for bulk email sending, allows grouping of emails.
          example: "bulk-group-1"
        status_callback:
          $ref: "#/components/schemas/Client"
          description: Used for external callbacks, allows a single callback.

    EmailString:
      type: string
      maxLength: 255
      example: "example@example.com"
    EmailArray:
      type: array
      items:
        type: string
        example: ["example@example.com"]
        maxLength: 255
        description: "A max of 10 emails may be sent between BCC, TO, and CC."
      maxItems: 10
    EmailSendRequestHtml:
      type: object
      required: [html]
      properties:
        html:
          type: string

    EmailSendRequestProfile:
      type: object
      required: [email_profile_guid]
      properties:
        email_profile_guid:
          type: string

    EmailSendRequestTemplate:
      type: object
      required: [email_template_guid]
      properties:
        email_template_guid:
          type: string
    Client:
      type: object
      required:
        - url
        - method
      properties:
        url:
          type: string
          description: The callback URL.
          example: "https://example.com/callback"
        method:
          type: string
          enum:
            - GET
            - POST
          description: HTTP method to use for the callback.
          example: POST
