ComplyAdvantage Email Configurations API

openapi: 3.2.0
info:
  title: Mesh Email Configurations API
  version: v2.0
servers:
- description: ComplyAdvantage Mesh API
  url: https://api.mesh.complyadvantage.com
security:
- BearerAuth: []
tags:
- name: Email Configurations
paths:
  /v2/notifications/configurations/email:
    get:
      description: 'Returns all the email notification configurations created for this account. Allows to filter by email notification type.


        You need the "View email notification configurations" permission to use this endpoint.'
      operationId: notificationGetEmailConfigurations
      parameters:
      - example: CASE_ASSIGNED
        in: query
        name: type
        required: false
        schema:
          enum:
          - CASE_ASSIGNED
          type: string
      - description: One-based page index (1..N)
        example: 1
        in: query
        name: page_number
        required: false
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: The size of the page to be returned
        example: 20
        in: query
        name: page_size
        required: false
        schema:
          default: 25
          minimum: 1
          type: integer
      - description: 'Sorting criteria in the format of: `[-]property` (`-` descending modifier).


          * Default sort order is ascending (without `-`).


          * Multiple sort criteria are supported.'
        example:
        - -timestamp
        in: query
        name: sort
        required: false
        schema:
          default: []
          items:
            type: string
          type: array
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ns_PaginatedResponseEmailConfigurationLog'
          description: OK
      summary: Get a list of all email notification configurations
      tags:
      - Email Configurations
    post:
      description: 'This endpoint enables you to create an email notification, by selecting a type of notification that should trigger the sending of this email and specify who the email should be sent to, when the conditions are met.


        At least one recipient should be specified.


        There is one event type which can trigger an email to be sent:


        ### CASE_ASSIGNED


        Sends an email to the assignee, whenever a new case is assigned to that user.

        If that user is configured in the list of recipients and the person assigning the email is not the same user (so only sending an email notification when someone else assigns a case to this user).


        Example:

        ```

        Hi Sophie,


        A case has been assigned to you by Julian

        Type: Customer Onboarding

        Created at: February 10, 2025 at 10:00am

        Stage: In Review

        Assignee: Sophie

        Note: Assigned to you because you are specialized on these scenarios

        Click here to view this case


        Please contact support@complyadvantage.com if you have any questions.


        ```


        You need the "Create and update email notification configurations" permission to use this endpoint.'
      operationId: notificationCreateEmailConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ns_EmailConfigurationPayload'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ns_EmailConfigurationLog'
          description: Email configuration created successfully
        '400':
          content:
            application/problem+json:
              examples:
                invalid email:
                  description: invalid email
                  value:
                    detail: Email configuration requires at least one valid UUID for user or role
                    identifier: 0193ab2b-1be8-7eed-8c20-dae093618aea
                    instance: https://example/v2/notifications/configurations/email/01938f3e-1286-752c-9b52-9210e4b95a14
                    status: 400
                    timestamp: '2024-12-09T11:25:49.416Z'
                    title: Validation Error
                    type: about:blank
              schema:
                $ref: '#/components/schemas/ns_ProblemDetailErrorResponse'
          description: Bad request. Request cannot be processed due to input Email configuration payload error.
      summary: Create a new email notification configuration
      tags:
      - Email Configurations
  /v2/notifications/configurations/email/test:
    post:
      description: 'This is an optional test that will send an example email to the email address you specify.


        Test Email content:


        ```"This is a test email from ComplyAdvantage with identifier=2032e328-c48b-4674-8229-576955df1a79 "```


        You need the "Create and update email notification configurations" permission to use this endpoint.'
      operationId: notificationTestEmailConfiguration
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ns_EmailTestPayload'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ns_TestEmailResponse'
          description: success
        '400':
          content:
            application/problem+json:
              examples:
                missing email:
                  description: missing email
                  value:
                    detail: There were validation errors with your request
                    errors:
                    - field: email
                      reasons:
                      - key: email incorrect type OR required
                        message: email validation error
                        parameters: null
                      rejected: '0'
                    identifier: 0193ac84-8eec-70dc-9747-e3e894095734
                    instance: https://example/v2/notifications/configurations/email/test
                    status: 400
                    timestamp: '2024-12-09T17:43:08.780Z'
                    title: Validation Error
                    type: about:blank
              schema:
                $ref: '#/components/schemas/ns_ProblemDetailErrorResponse'
          description: Bad request. Request cannot be processed due to input error.
      summary: Test an email
      tags:
      - Email Configurations
  /v2/notifications/configurations/email/{identifier}:
    delete:
      description: 'This endpoint allows deleting an email notification configuration.


        You need the "Create and update email notification configurations" permission to use this endpoint.'
      operationId: notificationDeleteEmailConfiguration
      parameters:
      - description: When you create an email config or run “Get list of email configs”, you’ll receive a unique configuration identifier for each email config. Supply that here for the email you wish to delete.
        example: 95913b76-050c-40f3-9075-25f0737ac7d3
        in: path
        name: identifier
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ns_DeletedEmailConfigurationResponse'
          description: Email configuration deleted successfully
        '400':
          content:
            application/problem+json:
              examples:
                Requires at least one valid UUID for user or role:
                  description: Requires at least one valid UUID for user or role
                  value:
                    detail: Email configuration with the provided identifier=0193b5a8-eb33-7af3-a5f1-37d9ec1a14fd does not exist
                    identifier: 0193b5aa-2d94-7cfa-a4d8-2a637ec5d619
                    instance: https://example/v2/notifications/configurations/email/0193b5a8-eb33-7af3-a5f1-37d9ec1a14fd
                    status: 404
                    timestamp: '2024-12-09T18:06:22.711Z'
                    title: Configuration does not exist
                    type: about:blank
              schema:
                $ref: '#/components/schemas/ns_ProblemDetailErrorResponse'
          description: Bad request. Request cannot be processed due to input error.
      summary: Delete an email notification configuration
      tags:
      - Email Configurations
    patch:
      description: 'This endpoint allows updating who the email notification is configured to be sent to.


        You need the "Create and update email notification configurations" permission to use this endpoint.'
      operationId: notificationPatchEmailConfiguration
      parameters:
      - description: The identifier of the email configuration
        example: 95913b76-050c-40f3-9075-25f0737ac7d3
        in: path
        name: identifier
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ns_UpdateEmailConfigurationPayload'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ns_EmailConfigurationLog'
          description: Email configuration updated successfully
        '400':
          content:
            application/problem+json:
              examples:
                Requires at least one valid UUID for user or role:
                  description: Requires at least one valid UUID for user or role
                  value:
                    detail: Email configuration requires at least one valid UUID for user or role
                    identifier: 0193ac99-d3f7-70e5-b8d1-2cd66e6bdf36
                    instance: https://example/v2/notifications/configurations/email/01938f3c-9e8b-7537-b55e-538663b866ca
                    status: 400
                    timestamp: '2024-12-09T18:06:22.711Z'
                    title: Validation Error
                    type: about:blank
              schema:
                $ref: '#/components/schemas/ns_ProblemDetailErrorResponse'
          description: Bad request. Request cannot be processed due to input error.
      summary: Update an email notification configuration
      tags:
      - Email Configurations
components:
  schemas:
    ns_EmailTestPayload:
      properties:
        email:
          description: The recipient email address to which the test email will be sent.
          example: me@complyadvantage.com
          format: email
          type: string
      required:
      - email
      type: object
    ns_DeletedEmailConfigurationResponse:
      properties:
        identifier:
          description: Email configuration unique identifier
          example: 6de244da-11f8-479d-aec7-c4d2126b092e
          format: uuid
          type: string
      required:
      - identifier
      type: object
    ns_ProblemDetailErrorResponse:
      additionalProperties: true
      properties:
        detail:
          type:
          - string
          - 'null'
        identifier:
          format: uuid
          type: string
        instance:
          format: uri
          type:
          - string
          - 'null'
        status:
          format: int32
          type:
          - integer
          - 'null'
        timestamp:
          format: date-time
          type: string
        title:
          type:
          - string
          - 'null'
        type:
          format: uri
          type:
          - string
          - 'null'
      required:
      - identifier
      - timestamp
      type: object
    ns_EnabledFor:
      description: Lists of user and role identifiers the email will be sent to
      properties:
        roles:
          description: List of role identifiers the email will be sent to
          format: uuid
          items:
            description: List of role identifiers the email will be sent to
            format: uuid
            type: string
          type: array
        users:
          description: List of user identifiers the email will be sent to
          format: uuid
          items:
            description: List of user identifiers the email will be sent to
            format: uuid
            type: string
          type: array
      required:
      - roles
      - users
      type: object
    ns_EmailConfigurationLog:
      properties:
        created_at:
          description: Timestamp when the configuration was created
          format: date-time
          type: string
        created_by:
          description: Created by the user
          format: uuid
          type: string
        enabled_for:
          $ref: '#/components/schemas/ns_EnabledFor'
        identifier:
          description: Unique identifier for the configuration
          format: uuid
          type: string
        type:
          description: The event type that the user wants to be notified about
          example: CASE_ASSIGNED
          type: string
        updated_at:
          description: Timestamp when the configuration was last updated
          format: date-time
          type: string
        updated_by:
          description: Last updated by the user
          format: uuid
          type:
          - string
          - 'null'
      required:
      - created_at
      - created_by
      - enabled_for
      - identifier
      - type
      - updated_at
      type: object
    ns_UpdateEmailConfigurationPayload:
      properties:
        enabled_for:
          $ref: '#/components/schemas/ns_EnabledFor'
      required:
      - enabled_for
      type: object
    ns_PaginatedResponseEmailConfigurationLog:
      properties:
        email_notification_configurations:
          items:
            $ref: '#/components/schemas/ns_EmailConfigurationLog'
          type: array
        first:
          description: The URL path to the first page.
          example: /v1/resource?page_number=1
          type: string
        next:
          description: The URL path to the next page.
          example: /v1/resource?page_number=4
          type:
          - string
          - 'null'
        prev:
          description: The URL path to the previous page.
          example: /v1/resource?page_number=2
          type:
          - string
          - 'null'
        self:
          description: The URL path to the current page.
          example: /v1/resource?page_number=3
          type: string
        total_count:
          description: Total number of items.
          example: 60
          format: int64
          type:
          - integer
          - 'null'
      required:
      - first
      - self
      - email_notification_configurations
      type: object
    ns_EmailConfigurationPayload:
      properties:
        enabled_for:
          $ref: '#/components/schemas/ns_EnabledFor'
        type:
          description: The event type that the user wants to listen to
          enum:
          - CASE_ASSIGNED
          type:
          - string
          - 'null'
      required:
      - enabled_for
      type: object
    ns_TestEmailResult:
      description: Response from the SMTP email server on the attempt to send
      properties:
        response_type:
          description: Type of response
          enum:
          - SUCCESS
          - SERVER_ERROR
          example: SUCCESS
          format: String
          type: string
        server_response_code:
          description: SMTP server response
          example: 200
          format: int32
          type:
          - integer
          - 'null'
      required:
      - response_type
      type: object
    ns_TestEmailResponse:
      properties:
        identifier:
          description: Test email unique identifier
          example: 6de244da-11f8-479d-aec7-c4d2126b092e
          format: uuid
          type: string
        test_result:
          $ref: '#/components/schemas/ns_TestEmailResult'
      required:
      - identifier
      - test_result
      type: object
  securitySchemes:
    BearerAuth:
      description: HTTP Bearer Token Authentication
      scheme: bearer
      type: http