openapi: 3.0.1
info:
  title: Elevate Notifications API
  description: >
    ### Elevate notifications

    Provides read-only access to the current status of email notifications sent
    from Elevate. NOTE: this service is only effective if using Amazon SES
    distribution


    #### Definitions

    * Email Status - status of email notification sent e.g. invoice email and
    whether it failed due to a bounce from the email distribution service
  version: '1.0'
servers:
  - url: https://rest.elevatebilling.com/v1
tags:
  - name: email-status
    description: >-
      Status of email notifications sent from Elevate with delivery details as
      provided by the email distribution service
paths:
  /email-status:
    get:
      tags:
        - email-status
      summary: Get the status of recent email notifications sent from Elevate
      operationId: getEmailNotificationsStatus
      x-si-permissions:
        - VIEW_SITE
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: createdDateTime
          in: query
          description: Filter by email notifications created before or after this timestamp
          schema:
            $ref: '#/components/schemas/DateTimeFilterParam'
          required: true
        - name: updatedDateTime
          in: query
          description: >-
            Filter by email notification status updated before or after this
            timestamp
          schema:
            $ref: '#/components/schemas/DateTimeFilterParam'
          required: false
        - name: billRunType
          in: query
          description: Filter by bill run type
          schema:
            $ref: '#/components/schemas/BillRunType'
          required: false
        - name: billRunId
          in: query
          description: Filter by bill run identifier
          schema:
            $ref: '#/components/schemas/IdFilterParam'
          required: false
        - name: status
          in: query
          description: Filter by email notification status
          schema:
            $ref: '#/components/schemas/NotificationStatus'
          required: false
        - name: bounceType
          in: query
          description: >-
            Filter by email bounce type (also filters to BOUNCED email
            notification status)
          schema:
            $ref: '#/components/schemas/BounceType'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailNotificationStatus'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
components:
  schemas:
    EmailNotificationStatus:
      type: object
      properties:
        id:
          description: Email notification status identifier
          type: integer
          readOnly: true
          format: int64
          example: 1
        recipientEmail:
          type: string
          description: Recipient email address
        createdDateTime:
          readOnly: true
          description: Email notification created time
          type: string
          format: date-time
        updatedDateTime:
          readOnly: true
          description: Email notification status last updated time
          type: string
          format: date-time
        status:
          $ref: '#/components/schemas/NotificationStatus'
        message:
          type: string
          description: Status message including any reason for email bounce or complaint
          example: >-
            failed, 5.3.0, smtp; 550 RCPT TO:<xxxxxx@imperatives.co.uk> User
            unknown
        bounceType:
          $ref: '#/components/schemas/BounceType'
        billRunType:
          $ref: '#/components/schemas/BillRunType'
        billRunId:
          description: Bill run identifier that the notification was linked to
          type: integer
          format: int64
          example: 1
        customerId:
          description: Customer identifier
          type: integer
          format: int64
          example: 1
        siteId:
          description: Site identifier
          type: integer
          format: int64
          example: 1
        contactId:
          description: Site contact identifier
          type: integer
          format: int64
          example: 1
    NotificationStatus:
      type: string
      description: Status of email notification
      enum:
        - SENT
        - DELIVERED
        - BOUNCED
        - COMPLAINT
        - ERROR
        - ACKNOWLEDGED
        - RETRY
    BounceType:
      description: Bounce type
      type: string
      enum:
        - PERMANENT
        - TRANSIENT
    BillRunType:
      type: string
      description: Billing run type
      enum:
        - NORMAL
        - ADHOC
    PageParam:
      description: Page of results to show
      minimum: 1
      type: integer
      format: int32
      example: 1
    ResultsPerPageParam:
      description: Results to return per page
      maximum: 1000
      minimum: 1
      type: integer
      format: int32
      example: 100
    SortParam:
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      example: id,name | name:desc
      type: string
    FieldsParam:
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      example: id,name
      type: string
    DateTimeFilterParam:
      description: >-
        Filter by this date/time value where value can optionally be prefixed
        (gt:|lt:)
      example: yyyy-MM-ddTHH:mm:ssZ | lt:yyyy-MM-ddTHH:mm:ssZ | gt:yyyy-MM-ddTHH:mm:ssZ
      type: string
    IdFilterParam:
      description: Filter by this numeric id value
      example: '0'
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    page:
      name: page
      in: query
      description: Page of results to show
      schema:
        $ref: '#/components/schemas/PageParam'
      required: true
    pageSize:
      name: pageSize
      description: Results to return per page
      in: query
      schema:
        $ref: '#/components/schemas/ResultsPerPageParam'
      required: true
    sort:
      name: sort
      in: query
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      schema:
        $ref: '#/components/schemas/SortParam'
      required: false
    fields:
      name: fields
      in: query
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      schema:
        $ref: '#/components/schemas/FieldsParam'
      required: false
