API Definitions

[almeiphi]

Proposed Architecture for Microservice API

API Layer:

• Authentication: Utilizes API-Key for secure access.
• Email Services: Offers comprehensive email functionalities.

Web Application Layer:

• Authentication: Employs JWT for robust security.
• Template Management: Enables creation and handling of email templates.
• Group Management: Facilitates the organization and management of user groups.

The API layer focuses on core services and authentication, while the Web Application layer provides specialized management features for enhanced user interaction.

swagger: '2.0'
info:
  description: >-
    This is the Swagger API documentation for the Ethereal Pulse Microservice API. It allows authenticated users to send emails using Azure Communication Services or AWS Simple Email Service.
  version: "1.0.0"
  title: Ethereal Pulse Microservice API
host: api.yourdomain.com
basePath: /v1
schemes:
  - https
paths:
  /auth/login:
    post:
      summary: User login
      description: Authenticates user and returns a JWT token
      tags:
        - Authentication
      parameters:
        - in: body
          name: body
          description: User credentials
          required: true
          schema:
            $ref: '#/definitions/LoginUser'
      responses:
        200:
          description: JWT token
          schema:
            $ref: '#/definitions/TokenResponse'
        401:
          description: Unauthorized

  /email/send:
    post:
      summary: Send email
      description: Sends an email to specified recipients using the selected provider
      tags:
        - Email
      security:
        - ApiKeyAuth: []
      parameters:
        - in: body
          name: body
          description: Email details
          required: true
          schema:
            $ref: '#/definitions/SendEmailRequest'
      responses:
        200:
          description: Email sent successfully
        400:
          description: Bad Request
        401:
          description: Unauthorized

  /email/send-web:
    post:
      summary: Send email (Web)
      description: Sends an email to specified recipients using the selected provider; intended for web app usage
      tags:
        - Email
      security:
        - Bearer: []
      parameters:
        - in: body
          name: body
          description: Email details
          required: true
          schema:
            $ref: '#/definitions/SendEmailRequest'
      responses:
        200:
          description: Email sent successfully
        400:
          description: Bad Request
        401:
          description: Unauthorized

  /templates:
    get:
      summary: Get user templates
      description: Retrieves all email templates for authenticated user
      tags:
        - Template
      security:
        - Bearer: []
      responses:
        200:
          description: List of email templates
          schema:
            type: array
            items:
              $ref: '#/definitions/Template'
        401:
          description: Unauthorized

    post:
      summary: Create new template
      description: Creates a new email template for authenticated user
      tags:
        - Template
      security:
        - Bearer: []
      parameters:
        - in: body
          name: body
          description: Template details
          required: true
          schema:
            $ref: '#/definitions/Template'
      responses:
        201:
          description: Template created successfully
        400:
          description: Bad Request
        401:
          description: Unauthorized

    put:
      summary: Update template
      description: Updates an existing email template for authenticated user
      tags:
        - Template
      security:
        - Bearer: []
      parameters:
        - in: body
          name: body
          description: Template details
          required: true
          schema:
            $ref: '#/definitions/Template'
      responses:
        200:
          description: Template updated successfully
        400:
          description: Bad Request
        401:
          description: Unauthorized

  /groups:
    get:
      summary: Get user groups
      description: Retrieves all recipient groups for authenticated user
      tags:
        - Group
      security:
        - Bearer: []
      responses:
        200:
          description: List of recipient groups
          schema:
            type: array
            items:
              $ref: '#/definitions/Group'
        401:
          description: Unauthorized

    post:
      summary: Create new group
      description: Creates a new recipient group for authenticated user
      tags:
        - Group
      security:
        - Bearer: []
      parameters:
        - in: body
          name: body
          description: Group details
          required: true
          schema:
            $ref: '#/definitions/Group'
      responses:
        201:
          description: Group created successfully
        400:
          description: Bad Request
        401:
          description: Unauthorized

    put:
      summary: Update group
      description: Updates an existing recipient group for authenticated user
      tags:
        - Group
      security:
        - Bearer: []
      parameters:
        - in: body
          name: body
          description: Group details
          required: true
          schema:
            $ref: '#/definitions/Group'
      responses:
        200:
          description: Group updated successfully
        400:
          description: Bad Request
        401:
          description: Unauthorized

  /groups/{groupId}:
    delete:
      summary: Delete group
      description: Deletes a recipient group
      tags:
        - Group
      security:
        - Bearer: []
      parameters:
        - in: path
          name: groupId
          required: true
          type: string
      responses:
        200:
          description: Group deleted successfully
        401:
          description: Unauthorized

securityDefinitions:
  Bearer:
    type: apiKey
    name: Authorization
    in: header
    description: JWT token for webapp authentication

  ApiKeyAuth:
    type: apiKey
    name: x-api-key
    in: header
    description: Multi-tenant API keys for SDK authentication

definitions:
  LoginUser:
    type: object
    properties:
      email:
        type: string
      password:
        type: string
    required:
      - email
      - password

  TokenResponse:
    type: object
    properties:
      token:
        type: string

  SendEmailRequest:
    type: object
    properties:
      provider:
        type: string
        enum:
          - azure
          - aws
      recipients:
        type: array
        items:
          type: string
      subject:
        type: string
      htmlContent:
        type: string
    required:
      - provider
      - recipients
      - subject
      - htmlContent

  Template:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      subject:
        type: string
      htmlContent:
        type: string
    required:
      - name
      - subject
      - htmlContent

  Group:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      recipients:
        type: array
        items:
          type: string
    required:
      - name
      - recipients

Security Definitions Applied:

• Bearer (JWT) Authentication:
  • Endpoints:
    • /email/send-web (POST)
    • /templates (GET, POST, PUT)
    • /groups (GET, POST, PUT)
    • /groups/{groupId} (DELETE)
• ApiKeyAuth (API Key) Authentication:
  • Endpoints:
    • /email/send (POST)

The /auth/login does not require any authentication, as it is used to obtain the JWT token required for accessing the other endpoints secured with Bearer authentication.

[ivanLOliveira]

This is very good 👍

I think you are just missing the Integration Management layer

• Integration Management: Create endpoints to manage different email service integrations (Azure, AWS SES, etc.).

[teixeped]

We won't have this integration management in the web app right? So I don't think there is a need to have endpoints for that.

[ivanLOliveira]

We can refine it but if we follow the examples given they provide a dashboard to allow for the creation and view of the health of those integrations on the webAPP

[teixeped]

Great work!

Some remarks:

Email

• /send endpoint probably needs a from, host and port attribute in body
• Why have a separate endpoint just for web requests?

Groups

As @ivanLOliveira suggested, I think this could be part of a more general endpoint for example /user/groups. And this could be expanded to manage integration configurations

[almeiphi]

/email/send endpoint updated with:

• Renamed htmlContent to html: Reflects the updated field name for the HTML content of the email.

• Removed provider and cloudProviderCredentials: These fields have been removed.

• Added text, bcc, ccc, headers, and attachments:

  • bcc: which can be a string or an array of strings.
  • ccc: which can be a string or an array of strings.
  • text: Plain text version of the email.
  • headers: Custom headers as an object.
  • attachments: Array of attachments, including metadata such as filename and content.

  response for status 200 in the with the ErrorDetail structure**, based on Azure Communication Email Send Response:

  • status: Enum with the possible values [NotStarted, Running, Succeeded, Failed, Canceled].
  • id: The unique id of the operation. Use a UUID.
  • error: Error details when status is a non-success terminal state.

  Also created schema $ref 'ErrorAdditionalInfo' for 'error' field

  • additionalInfo: Additional information array with ErrorAdditionalInfo.
  • code: Error code as a string.
  • details: Nested error details.
  • message: Error message.
  • target: The target of the error.
  • info: Generic error information with key: value as strings.

openapi: 3.0.1
info:
  title: Ethereal Pulse Microservice API
  description: >
    This is the Swagger API documentation for the Ethereal Pulse Microservice API.
    It allows authenticated users to send emails using Azure Communication Services
    or AWS Simple Email Service.
  version: 1.0.0
servers:
  - url: https://api.yourdomain.com/v1

paths:
  /auth/login:
    post:
      tags:
        - Authentication
      summary: User login
      description: Authenticates user and returns a JWT token
      requestBody:
        description: User credentials
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginUser'
        required: true
      responses:
        "200":
          description: JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        "401":
          description: Unauthorized

  /email/send:
    post:
      tags:
        - Email
      summary: Send email
      description: Sends an email to specified recipients using the selected provider with customer credentials
      requestBody:
        description: Email details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
        required: true
      responses:
        "200":
          description: Email sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/ErrorDetail'
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - NotStarted
                      - Running
                      - Succeeded
                      - Failed
                      - Canceled
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - ApiKeyAuth: []
        - Bearer: []

  /templates:
    get:
      tags:
        - Template
      summary: Get user templates
      description: Retrieves all email templates for authenticated user
      responses:
        "200":
          description: List of email templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Template'
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    put:
      tags:
        - Template
      summary: Update template
      description: Updates an existing email template for an authenticated user
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
        required: true
      responses:
        "200":
          description: Template updated successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    post:
      tags:
        - Template
      summary: Create new template
      description: Creates a new email template for authenticated user
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
        required: true
      responses:
        "201":
          description: Template created successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
  /templates/{templateId}:
    delete:
      tags:
        - Template
      summary: Delete template
      description: Deletes a template by ID
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Template deleted successfully
        "401":
          description: Unauthorized
      security:
        - Bearer: []

  /groups:
    get:
      tags:
        - Group
      summary: Get user groups
      description: Retrieves all recipient groups for authenticated user
      responses:
        "200":
          description: List of recipient groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    put:
      tags:
        - Group
      summary: Update group
      description: Updates an existing recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        "200":
          description: Group updated successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    post:
      tags:
        - Group
      summary: Create new group
      description: Creates a new recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        "201":
          description: Group created successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
  /groups/{groupId}:
    delete:
      tags:
        - Group
      summary: Delete group
      description: Deletes a recipient group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Group deleted successfully
        "401":
          description: Unauthorized
      security:
        - Bearer: []

components:
  schemas:
    LoginUser:
      required:
        - email
        - password
      type: object
      properties:
        email:
          type: string
        password:
          type: string
    TokenResponse:
      type: object
      properties:
        token:
          type: string

    SendEmailRequest:
      required:
        - from
        - html
        - recipients
        - subject
      type: object
      properties:
        from:
          type: string
        recipients:
          type: array
          items:
            type: string
        subject:
          type: string
        html:
          type: string
        text:
          type: string
        bcc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        ccc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        headers:
          type: object
          description: Custom headers to add to the email
        attachments:
          type: array
          description: Filename and content of attachments (max 40mb per email)
          items:
            type: object
            properties: {}

    ErrorDetail:
      type: object
      properties:
        additionalInfo:
          type: array
          items:
            $ref: '#/components/schemas/ErrorAdditionalInfo'
        code:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
        message:
          type: string
        target:
          type: string
  
    ErrorAdditionalInfo:
      type: object
      properties:
        info:
          type: object
          additionalProperties: true
        type:
          type: string

    Template:
      required:
        - html
        - name
        - subject
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        subject:
          type: string
        html:
          type: string
    
    Group:
      required:
        - name
        - recipients
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        recipients:
          type: array
          items:
            type: string

  securitySchemes:
    Bearer:
      type: apiKey
      description: JWT token for webapp authentication
      name: Authorization
      in: header
    ApiKeyAuth:
      type: apiKey
      description: Multi-tenant API keys for SDK authentication
      name: x-api-key
      in: header

[almeiphi]

Updating adding new endpoints related to '/apiKeys' path

openapi: 3.0.1
info:
  title: Ethereal Pulse Microservice API
  description: >
    This is the Swagger API documentation for the Ethereal Pulse Microservice API.
    It allows authenticated users to send emails using Azure Communication Services
    or AWS Simple Email Service.
  version: 1.0.0
servers:
  - url: https://api.yourdomain.com/v1

paths:
  /auth/login:
    post:
      tags:
        - Authentication
      summary: User login
      description: Authenticates user and returns a JWT token
      requestBody:
        description: User credentials
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginUser'
        required: true
      responses:
        "200":
          description: JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        "401":
          description: Unauthorized

  /email/send:
    post:
      tags:
        - Email
      summary: Send email
      description: Sends an email to specified recipients using the selected provider with customer credentials
      requestBody:
        description: Email details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
        required: true
      responses:
        "200":
          description: Email sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/ErrorDetail'
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - NotStarted
                      - Running
                      - Succeeded
                      - Failed
                      - Canceled
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - ApiKeyAuth: []
        - Bearer: []

  /templates:
    get:
      tags:
        - Template
      summary: Get user templates
      description: Retrieves all email templates for authenticated user
      responses:
        "200":
          description: List of email templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Template'
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    put:
      tags:
        - Template
      summary: Update template
      description: Updates an existing email template for an authenticated user
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
        required: true
      responses:
        "200":
          description: Template updated successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    post:
      tags:
        - Template
      summary: Create new template
      description: Creates a new email template for authenticated user
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Template'
        required: true
      responses:
        "201":
          description: Template created successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
  /templates/{templateId}:
    delete:
      tags:
        - Template
      summary: Delete template
      description: Deletes a template by ID
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Template deleted successfully
        "401":
          description: Unauthorized
      security:
        - Bearer: []

  /groups:
    get:
      tags:
        - Group
      summary: Get user groups
      description: Retrieves all recipient groups for authenticated user
      responses:
        "200":
          description: List of recipient groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Group'
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    put:
      tags:
        - Group
      summary: Update group
      description: Updates an existing recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        "200":
          description: Group updated successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    post:
      tags:
        - Group
      summary: Create new group
      description: Creates a new recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
        required: true
      responses:
        "201":
          description: Group created successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
  /groups/{groupId}:
    delete:
      tags:
        - Group
      summary: Delete group
      description: Deletes a recipient group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Group deleted successfully
        "401":
          description: Unauthorized
      security:
        - Bearer: []

  /apiKeys:
    post:
      tags:
        - API Keys
      summary: Create an API key
      description: Creates a new API key
      requestBody:
        description: API Key details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
        required: true
      responses:
        "200":
          description: API key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  token:
                    type: string

    get:
      tags:
        - API Keys
      summary: List API keys
      description: Retrieves a list of API keys
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        created_at:
                          type: string
                          format: date-time

  /apiKeys/{apiKeyId}:
    delete:
      tags:
        - API Keys
      summary: Delete API key
      description: Deletes an API key by ID
      parameters:
        - name: apiKeyId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: API key deleted successfully
        "401":
          description: Unauthorized

components:
  schemas:
    LoginUser:
      required:
        - email
        - password
      type: object
      properties:
        email:
          type: string
        password:
          type: string
    TokenResponse:
      type: object
      properties:
        token:
          type: string

    SendEmailRequest:
      required:
        - from
        - html
        - recipients
        - subject
      type: object
      properties:
        from:
          type: string
        recipients:
          type: array
          items:
            type: string
        subject:
          type: string
        html:
          type: string
        text:
          type: string
        bcc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        ccc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        headers:
          type: object
          description: Custom headers to add to the email
        attachments:
          type: array
          description: Filename and content of attachments (max 40mb per email)
          items:
            type: object
            properties: {}

    ErrorDetail:
      type: object
      properties:
        additionalInfo:
          type: array
          items:
            $ref: '#/components/schemas/ErrorAdditionalInfo'
        code:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
        message:
          type: string
        target:
          type: string
  
    ErrorAdditionalInfo:
      type: object
      properties:
        info:
          type: object
          additionalProperties: true
        type:
          type: string

    CreateApiKeyRequest:
      type: object
      properties:
        name:
          type: string
        permission:
          type: string
          enum:
            - full_access
            - sending_access
        domain_id:
          type: string

    Template:
      required:
        - html
        - name
        - subject
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        subject:
          type: string
        html:
          type: string
    
    Group:
      required:
        - name
        - recipients
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        recipients:
          type: array
          items:
            type: string

  securitySchemes:
    Bearer:
      type: apiKey
      description: JWT token for webapp authentication
      name: Authorization
      in: header
    ApiKeyAuth:
      type: apiKey
      description: Multi-tenant API keys for SDK authentication
      name: x-api-key
      in: header

[ivanLOliveira]

It's looking very good 😁
I'll say the next step would be to have a recipients route.

[almeiphi]

Updating adding '/recipients' ( contacts ) endpoints paths

6 June

• Updating with additional Get and Patch method for '/recipients' endpoints,
• Re-update the SendEmailRequest schema for /send endpoint.
• Adding a new Path method endpoint to recipients: /recipients/{id}

openapi: 3.0.1
info:
  title: Ethereal Pulse Microservice API
  description: >
    This is the Swagger API documentation for the Ethereal Pulse Microservice API.
    It allows authenticated users to send emails using Azure Communication Services
    or AWS Simple Email Service.
  version: 1.0.0
servers:
  - url: https://api.yourdomain.com/v1

paths:
  /auth/login:
    post:
      tags:
        - Authentication
      summary: User login
      description: Authenticates user and returns a JWT token
      requestBody:
        description: User credentials
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginUser"
        required: true
      responses:
        "200":
          description: JWT token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenResponse"
        "401":
          description: Unauthorized

  /email/send:
    post:
      tags:
        - Email
      summary: Send email
      description: Sends an email to specified recipients using the selected provider with customer credentials
      requestBody:
        description: Email details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendEmailRequest"
        required: true
      responses:
        "200":
          description: Email sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ErrorDetail"
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - NotStarted
                      - Running
                      - Succeeded
                      - Failed
                      - Canceled
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - ApiKeyAuth: []
        - Bearer: []

  /templates:
    get:
      tags:
        - Template
      summary: Get user templates
      description: Retrieves all email templates for authenticated user
      responses:
        "200":
          description: List of email templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Template"
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    put:
      tags:
        - Template
      summary: Update template
      description: Updates an existing email template for an authenticated user
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Template"
        required: true
      responses:
        "200":
          description: Template updated successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    post:
      tags:
        - Template
      summary: Create new template
      description: Creates a new email template for authenticated user
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Template"
        required: true
      responses:
        "201":
          description: Template created successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
  /templates/{templateId}:
    delete:
      tags:
        - Template
      summary: Delete template
      description: Deletes a template by ID
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Template deleted successfully
        "401":
          description: Unauthorized
      security:
        - Bearer: []

  /groups:
    get:
      tags:
        - Group
      summary: Get user groups
      description: Retrieves all recipient groups for authenticated user
      responses:
        "200":
          description: List of recipient groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Group"
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    put:
      tags:
        - Group
      summary: Update group
      description: Updates an existing recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Group"
        required: true
      responses:
        "200":
          description: Group updated successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
    post:
      tags:
        - Group
      summary: Create new group
      description: Creates a new recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Group"
        required: true
      responses:
        "201":
          description: Group created successfully
        "400":
          description: Bad Request
        "401":
          description: Unauthorized
      security:
        - Bearer: []
  /groups/{groupId}:
    delete:
      tags:
        - Group
      summary: Delete group
      description: Deletes a recipient group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Group deleted successfully
        "401":
          description: Unauthorized
      security:
        - Bearer: []

  /apiKeys:
    post:
      tags:
        - API Keys
      summary: Create an API key
      description: Creates a new API key
      requestBody:
        description: API Key details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateApiKeyRequest"
        required: true
      responses:
        "200":
          description: API key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  token:
                    type: string

    get:
      tags:
        - API Keys
      summary: List API keys
      description: Retrieves a list of API keys
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        created_at:
                          type: string
                          format: date-time

  /apiKeys/{apiKeyId}:
    delete:
      tags:
        - API Keys
      summary: Delete API key
      description: Deletes an API key by ID
      parameters:
        - name: apiKeyId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: API key deleted successfully
        "401":
          description: Unauthorized

  /recipients:
    post:
      tags:
        - Recipient
      summary: Create a recipient
      description: Creates a new recipient
      requestBody:
        description: Recipient details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Recipient"
        required: true
      responses:
        "200":
          description: Recipient created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string

  /recipients/{groupId}:
    get:
      tags:
        - Recipient
      summary: List recipients
      description: Show all recipients from a group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of recipients
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        email:
                          type: string
                        first_name:
                          type: string
                        last_name:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        unsubscribed:
                          type: boolean

    delete:
      tags:
        - Recipient
      summary: Delete a recipient
      description: Delete an existing recipient from a group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: email
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Recipient deleted successfully

  /recipients/{id}:
    patch:
      tags:
        - Recipient
      summary: Update a recipient
      description: Updates an existing recipient by ID for all groups
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Recipient details to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecipientUpdate"
        required: true
      responses:
        "200":
          description: Recipient updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string

  /recipients/{groupId}/{id}:
    get:
      tags:
        - Recipient
      summary: Retrieve a recipient
      description: Retrieves a recipient by ID for a specific group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Recipient retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  first_name:
                    type: string
                  last_name:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  unsubscribed:
                    type: boolean
    patch:
      tags:
        - Recipient
      summary: Update a recipient
      description: Updates an existing recipient by ID for a specific group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Recipient details to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecipientUpdate"
        required: true
      responses:
        "200":
          description: Recipient updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string

components:
  schemas:
    LoginUser:
      required:
        - email
        - password
      type: object
      properties:
        email:
          type: string
        password:
          type: string

    TokenResponse:
      type: object
      properties:
        token:
          type: string

    SendEmailRequest:
      required:
        - from
        - html
        - recipients
        - subject
      type: object
      properties:
        from:
          type: string
        recipients:
          type: array
          items:
            type: string
        subject:
          type: string
        html:
          type: string
        text:
          type: string
        bcc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        ccc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        headers:
          type: object
          description: Custom headers to add to the email
        attachments:
          type: array
          description: Filename and content of attachments (max 40mb per email)
          items:
            type: object
            properties: {}

    ErrorDetail:
      type: object
      properties:
        additionalInfo:
          type: array
          items:
            $ref: "#/components/schemas/ErrorAdditionalInfo"
        code:
          type: string
        details:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetail"
        message:
          type: string
        target:
          type: string

    ErrorAdditionalInfo:
      type: object
      properties:
        info:
          type: object
          additionalProperties: true
        type:
          type: string

    CreateApiKeyRequest:
      type: object
      properties:
        name:
          type: string
        permission:
          type: string
          enum:
            - full_access
            - sending_access
        domain_id:
          type: string

    Template:
      required:
        - name
        - subject
        - html
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        subject:
          type: string
        html:
          type: string

    Group:
      required:
        - name
        - recipients
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        recipients:
          type: array
          items:
            type: string

    Recipient:
      required:
        - email
        - groupId
      type: object
      properties:
        email:
          type: string
        groupId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        unsubscribed:
          type: boolean
          default: false

    RecipientUpdate:
      required:
        - firstName
        - lastName
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        unsubscribed:
          type: boolean
          default: false

  securitySchemes:
    Bearer:
      type: apiKey
      description: JWT token for webapp authentication
      name: Authorization
      in: header
    ApiKeyAuth:
      type: apiKey
      description: Multi-tenant API keys for SDK authentication
      name: x-api-key
      in: header

[almeiphi]

Updating with:

• Remove /auth endpoint
• All endpoints requiring an API key
• Moved errorCodes to components.responses:
  • Redesigned error responses to align with the constraints of OpenAPI.
  • Defined common error responses under components.responses.
  • Referenced these responses in relevant places in the paths.

openapi: 3.0.1
info:
  title: Ethereal Pulse Microservice API
  description: >
    This is the Swagger API documentation for the Ethereal Pulse Microservice API.
    It allows authenticated users to send emails using Azure Communication Services
    or AWS Simple Email Service.
  version: 1.0.0
servers:
  - url: https://api.yourdomain.com/v1

paths:
  /email/send:
    post:
      tags:
        - Email
      summary: Send email
      description: Sends an email to specified recipients using the selected provider with customer credentials
      requestBody:
        description: Email details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendEmailRequest"
        required: true
      responses:
        "200":
          description: Email sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/ErrorDetail"
                  id:
                    type: string
                  status:
                    type: string
                    enum:
                      - NotStarted
                      - Running
                      - Succeeded
                      - Failed
                      - Canceled
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /templates:
    get:
      tags:
        - Template
      summary: Get user templates
      description: Retrieves all email templates for the authenticated user, including public ones.
      responses:
        "200":
          description: List of email templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Template"
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
    put:
      tags:
        - Template
      summary: Update template
      description: Updates an existing email template for an authenticated user
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Template"
        required: true
      responses:
        "200":
          description: Template updated successfully
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
    post:
      tags:
        - Template
      summary: Create new template
      description: Creates a new email template for authenticated user. Private templates should include `apiKeyId`.
      requestBody:
        description: Template details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Template"
        required: true
      responses:
        "201":
          description: Template created successfully
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
  /templates/{templateId}:
    delete:
      tags:
        - Template
      summary: Delete template
      description: Deletes a template by ID
      parameters:
        - name: templateId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Template deleted successfully
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /groups:
    get:
      tags:
        - Group
      summary: Get user groups
      description: Retrieves all recipient groups for authenticated user
      responses:
        "200":
          description: List of recipient groups
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Group"
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
    put:
      tags:
        - Group
      summary: Update group
      description: Updates an existing recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Group"
        required: true
      responses:
        "200":
          description: Group updated successfully
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
    post:
      tags:
        - Group
      summary: Create new group
      description: Creates a new recipient group for an authenticated user
      requestBody:
        description: Group details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Group"
        required: true
      responses:
        "201":
          description: Group created successfully
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
  /groups/{groupId}:
    delete:
      tags:
        - Group
      summary: Delete group
      description: Deletes a recipient group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Group deleted successfully
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /apiKeys:
    post:
      tags:
        - API Keys
      summary: Create an API key
      description: Creates a new API key
      requestBody:
        description: API Key details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateApiKeyRequest"
        required: true
      responses:
        "200":
          description: API key created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  token:
                    type: string
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

    get:
      tags:
        - API Keys
      summary: List API keys
      description: Retrieves a list of API keys
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        created_at:
                          type: string
                          format: date-time
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /apiKeys/{apiKeyId}:
    delete:
      tags:
        - API Keys
      summary: Delete API key
      description: Deletes an API key by ID
      parameters:
        - name: apiKeyId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: API key deleted successfully
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /recipients:
    post:
      tags:
        - Recipient
      summary: Create a recipient
      description: Creates a new recipient
      requestBody:
        description: Recipient details
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Recipient"
        required: true
      responses:
        "200":
          description: Recipient created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /recipients/{groupId}:
    get:
      tags:
        - Recipient
      summary: List recipients
      description: Show all recipients from a group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of recipients
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        email:
                          type: string
                        first_name:
                          type: string
                        last_name:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        unsubscribed:
                          type: boolean
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

    delete:
      tags:
        - Recipient
      summary: Delete a recipient
      description: Delete an existing recipient from a group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: query
          required: false
          schema:
            type: string
        - name: email
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Recipient deleted successfully
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /recipients/{id}:
    patch:
      tags:
        - Recipient
      summary: Update a recipient
      description: Updates an existing recipient by ID for all groups
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Recipient details to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecipientUpdate"
        required: true
      responses:
        "200":
          description: Recipient updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

  /recipients/{groupId}/{id}:
    get:
      tags:
        - Recipient
      summary: Retrieve a recipient
      description: Retrieves a recipient by ID for a specific group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Recipient retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  email:
                    type: string
                  first_name:
                    type: string
                  last_name:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  unsubscribed:
                    type: boolean
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
    patch:
      tags:
        - Recipient
      summary: Update a recipient
      description: Updates an existing recipient by ID for a specific group
      parameters:
        - name: groupId
          in: path
          required: true
          schema:
            type: string
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        description: Recipient details to update
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecipientUpdate"
        required: true
      responses:
        "200":
          description: Recipient updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        "400":
          $ref: '#/components/responses/BadRequest'
        "401":
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []

components:
  schemas:
    LoginUser:
      required:
        - email
        - password
      type: object
      properties:
        email:
          type: string
        password:
          type: string

    TokenResponse:
      type: object
      properties:
        token:
          type: string

    SendEmailRequest:
      required:
        - from
        - html
        - recipients
        - subject
      type: object
      properties:
        from:
          type: string
        recipients:
          type: array
          items:
            type: string
        subject:
          type: string
        html:
          type: string
        text:
          type: string
        bcc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        ccc:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        headers:
          type: object
          description: Custom headers to add to the email
        attachments:
          type: array
          description: Filename and content of attachments (max 40mb per email)
          items:
            type: object
            properties: {}

    ErrorDetail:
      type: object
      properties:
        additionalInfo:
          type: array
          items:
            $ref: "#/components/schemas/ErrorAdditionalInfo"
        code:
          type: string
        details:
          type: array
          items:
            $ref: "#/components/schemas/ErrorDetail"
        message:
          type: string
        target:
          type: string

    ErrorAdditionalInfo:
      type: object
      properties:
        info:
          type: object
          additionalProperties: true
        type:
          type: string

    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
        error:
          $ref: "#/components/schemas/ErrorDetail"

    CreateApiKeyRequest:
      type: object
      properties:
        name:
          type: string
        permission:
          type: string
          enum:
            - full_access
            - sending_access
        domain_id:
          type: string

    Template:
      required:
        - name
        - subject
        - html
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        subject:
          type: string
        html:
          type: string
        apiKeyId:
          type: string  # Field added to link template to user's API key if it's private

    Group:
      required:
        - name
        - recipients
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        recipients:
          type: array
          items:
            type: string

    Recipient:
      required:
        - email
        - groupId
      type: object
      properties:
        email:
          type: string
        groupId:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        unsubscribed:
          type: boolean
          default: false

    RecipientUpdate:
      required:
        - firstName
        - lastName
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        unsubscribed:
          type: boolean
          default: false

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Multi-tenant API keys for SDK authentication
      name: x-api-key
      in: header

  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

[almeiphi]

1. Error Handling Standardization:

   • A unified ErrorResponse schema has been created for error responses.
   • ErrorDetail and ErrorAdditionalInfo schemas are utilized to provide detailed error information.

2. Common Error Codes:

   • Common error codes like 400, 401, 403, 404, and 500 are defined and their format is standardized across the API.
   • Each error code section points to the ErrorResponse schema which describes the structure of the error response.

3. Security Scheme:

   • Security defined via ApiKeyAuth.