---
openapi: 3.0.0

info:
  title: Suppression API
  description: "
  
  With this API, you can control your <b>outgoing messages</b> using suppression and allow lists.<br/><br/>
  
   The <b>suppression list</b> helps you with honoring the ISPs’ feedback to preserve sending IP reputation while allow list helps you ensure that you send only to those email addresses which are in the <b>allowed list
</b>, typically to ensure that you don't send mails to customers from your development sandbox."
  version: "1.0.1"

security:
  - BearerAuth: []

servers:
  - url: https://platform-stage.adobe.io/ajo
    description: Stage Environment
  - url: https://platform.adobe.io/ajo
    description: Production Environment

paths:
  /config/suppression/addresses:
    parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    get:
      summary: Query suppressed or allowed emails addresses
      tags:
        - Suppression
      operationId: getAddressesId
      parameters:
        - $ref: '#/components/parameters/type'
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/start'
        - $ref: '#/components/parameters/property'
      responses:
        '200':
          description: A list of suppressed or allowed entities 
          content:
            application/json:
              schema:
                type: object
                properties:
                  _page:
                    $ref: '#/components/schemas/page'
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/suppressionListResponse'
                  _links:
                    $ref: '#/components/schemas/suppressionListLink'
    post:
      parameters:
        - $ref: '#/components/parameters/type'
      
      summary: Add a suppressed or allowed email address
      tags:
        - Suppression
      operationId: addAddressId
      requestBody:
        description: The JSON for the entity
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/addEmailAddress'
      responses:
        '201':
          description: The newly added entity 
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/suppressionListAddResponse'

  /config/suppression/addresses/{email}:
    parameters:
      - in: path
        description: email address sought
        name: email
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/type'
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    get:
      summary: Query a specific suppressed or allowed email address
      tags:
        - Suppression
      operationId: getEmailAddressId
      responses:
        '200':
          description: Returning a specific suppression or allowed entity 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/suppressionListResponse'
    delete:
      summary: Delete a specific suppressed or allowed email address
      tags:
        - Suppression
      operationId: deleteEmailAddressId
      responses:
        '204':
          description: Entity deleted 

  /config/suppression/domains:
    parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    get:
      summary: Query suppressed or allowed domains
      tags:
        - Suppression
      operationId: getDomainsId
      parameters:
        - $ref: '#/components/parameters/type'  
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/start'
        - $ref: '#/components/parameters/property' 
      responses:
        '200':
          description: A list of suppressed or allowed entities 
          content:
            application/json:
              schema:
                type: object
                properties:
                  _page:
                    $ref: '#/components/schemas/page'
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/domainSuppressionListResponse'
                  _links:
                    $ref: '#/components/schemas/suppressionListLink'
    post:
      parameters:
        - $ref: '#/components/parameters/type'
      
      summary: Add a suppressed or allowed domain 
      tags:
        - Suppression
      operationId: addDomainId
      requestBody:
        description: The JSON for the entity
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/addDomain'
      responses:
        '201':
          description: The newly added entity 
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/suppressionListAddResponse'

  /config/suppression/domains/{domain}:
    parameters:
      - in: path
        description: domain sought
        name: domain
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    get:
      summary: Query a specific suppressed or allowed domain
      tags:
        - Suppression
      operationId: getDomainId
      responses:
        '200':
          description: A list of suppressed or allowed entities 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainSuppressionListResponse'
    delete:
      summary: Delete a specific suppressed or allowed domain
      tags:
        - Suppression
      operationId: deleteDomainId
      responses:
        '204':
          description: Entity deleted 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domainSuppressionListResponse'

  /config/suppression/uploads:
    parameters:
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    post:
      parameters:
        - name: Content-Type
          description: The content type of the request body.  Should be 'multipart/form-data'.
          required: true
          in: header
          schema:
            type: string
            example: multipart/form-data     
      summary: Upload a CSV file of suppressed entities 
      tags:
        - Suppression
      operationId: uploadId
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  description: The full path of the file that is to be uploaded.
                  type: string
                  example: mysuppressions.csv
      responses:
        '201':
          description: The CSV file has been accepted.  This is an asynchronous call and will finish sometime in the future.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/uploadPost'
    get:
      summary: Fetch upload jobs
      tags:
        - Suppression
      operationId: getUploadsId
      parameters:
        - $ref: '#/components/parameters/orderby'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/start'
        - $ref: '#/components/parameters/property'
      responses:
        '200':
          description: A list of suppressed or allowed entities 
          content:
            application/json:
              schema:
                type: object
                properties:
                  _page:
                    $ref: '#/components/schemas/uploadPage'
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/uploadListResponse'
                  _links:
                    $ref: '#/components/schemas/uploadListLink'
  
  /config/suppression/uploads/{jobId}:
    parameters:
      - in: path
        description: Upload job to fetch
        name: jobId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    get:
      summary: Query a specific upload job
      tags:
        - Suppression
      operationId: getUploadJobId
      responses:
        '200':
          description: Returns a specific upload job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/uploadJob'
    delete:
      summary: Delete a specific upload job.
      description: The purpose of this operation is to delete the job record created. It does not delete the suppressions created through the job.
      tags:
        - Suppression
      operationId: deleteUploadJobId
      responses:
        '204':
          description: Job deleted 

  /config/suppression/admin/{imsOrgId}/{sandboxId}:
    parameters:
      - in: path
        description: IMS Organization Id
        name: imsOrgId
        required: true
        schema:
          type: string
      - in: path
        description: Sandbox Id
        name: sandboxId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/x-api-key'
      - $ref: '#/components/parameters/x-request-id'
      - $ref: '#/components/parameters/x-gw-ims-org-id'
      - $ref: '#/components/parameters/x-sandbox-name'
    delete:
      summary: Delete all suppressions from a given sandbox-Id and IMS-Org-Id
      tags:
        - Suppression
      operationId: deleteAllSuppressions
      responses:
        '202':
          description: The request has been accepted and will be completed asynchronously

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: The authentication token to access the service.

  parameters:
    type:
      name: type
      description: For suppressed entities use 'client', for allowed entities use 'allowed'.  Default is 'client'
      in: query
      schema:
        type: string
        enum: [client, allowed]
    x-api-key:
      name: x-api-key
      description: The API key belonging to the calling client.
      required: true
      in: header
      schema:
        type: string
    x-request-id:
      name: x-request-id
      description: A unique id generated by Adobe.io.
      required: false
      in: header
      schema:
        type: string
    x-gw-ims-org-id:
      name: x-gw-ims-org-id
      description: The ims org id for which the action is being taken.
      required: true
      in: header
      schema:
        type: string
    x-sandbox-name:
      name: x-sandbox-name
      description: >-
        Provides the platform Sandbox Name
      required: true
      in: header
      schema:
        type: string
    orderby:
      name: orderby
      description: >-
        Sort parameter and direction for sorting the response.
        Add the `-` prefix to sort the responding in descending order. If unspecified, the response will be sorted in ascending order. Ex. orderby=creationdate.
      in: query
      schema:
        type: string
        default: -creationdate
      required: false
    limit:
      name: limit
      description: >-
        Limit response to a specified positive number of objects.
        Ex. limit=10
      in: query
      schema:
        type: integer
        default: 20
      required: false
    start:
      name: start
      description: >-
        Used for pagination. Specifies the criteria for next page
        with respect to the property specified in orderby.
        Ex. start=1631739725150.
      in: query
      schema:
        type: string
      required: false
    property:
      name: property
      description: >-
        <p>Optional property filters. Please refer to <a href="https://git.corp.adobe.com/pages/experience-platform/api-guidelines/5-sorting_paging_and_filtering.html#533-filtering-by-property">api guidelines</a> for filtering support in APIs.
        Filtering is supported on the following properties: creationdate, channel
        Ex. property=creationdate<1631739725150</p>
      in: query
      schema:
        items:
          type: string
        type: array
      required: false
  schemas:  
    uploadPost:
      type: object
      properties:
        success:
          type: object
          properties:
            jobId:
              type: string
              example: 6caaed1b-d7bd-4065-a745-185e9af3b63a
              description: Unique job identifier.

    addEmailAddress:
      type: object
      required:
        - entity
      properties:
        entity:
          properties:
            type: 
              type: string
              example: email
            entityValue:
              type: string
              description: An email address
              example: bademailaddress@domain.com
        comment:
          type: string
          example: Known bad email address
        user:
          type: string
          example: myusername@corp.com
          
    addDomain:
      type: object
      required:
        - entity
      properties:
        entity:
          properties:
            type: 
              type: string
              example: domain
            entityValue:
              type: string
              description: A domain
              example: baddomain.com
        comment:
          type: string
          example: Known bad domain
        user:
          type: string
          example: myusername@corp.com

    uploadJob:
      type: object
      allOf:
        - $ref: '#/components/schemas/uploads'
      properties:
        imsOrgId:
          type: string
          example: 225F37C35E4B776E0A49421B@AdobeOrg
        sandboxId:
          type: string
          example: 70f22060-5d47-11ea-bdff-a5384333ff34
        failedRecords:
          type: array
          items:
            $ref: '#/components/schemas/failedRecord'

    failedRecord:
      type: object
      properties:
        type:
          description: The entity type.  This is value provided in the user's data
          type: string  
          example: Email
        value:
          description: The value of the entity. This is value provided in the user's data
          type: string
          example: examplegmail@com
        comments: 
          description: The comments associated with the failed record. This is value provided in the user's data.
          type: string
          example: This is a known bad email address
        failureReason:
          description: This is the reason the recdord could not be ingested.  This is provided buy the service itself
          type: string
          example: "Invalid format for the entry: examplegmail@com"

    uploads:
      type: object
      properties:
        jobId:
          type: string
          format: uuid
          example: 6caaed1b-d7bd-4065-a745-185e9af3b63a
        user:
          type: string
          example: username@mydomain.com
        filename:
          type: string
          example: mysuppressions.csv
        createTime:
          description: Number of seconds since the epoc since the job was started
          type: number
          example: 1643768895
        endTime:
          description: Number of seconds since the epoc when the job finished
          type: number
          example: 1643768895
        status:
          $ref: '#/components/schemas/uploadStatus'
        responseCode: 
          description: the HTTP response code upon accepting the file and the creation of an upload job
          type: number
          example: 200
        responseText:
          description: in the case of a non-200 responseCode, this field provides more insight as to any failues.  May be null in the case of no error.
          type: string
          example: The file is malformed, only CSV files are allowed.
        recordCount:
          description: The number of entity records found in the provided upload file.
          type: number
          example: 14502
        handledCount:
          type: number
          description: The number of records handled
          example: 12342
        failedCount:
          description: Numebr of records that failed to be imported.  These records are provided for an individual jobId when requesting a single jobId using /upload/{jobId}
          type: number
          example: 17

    uploadStatus:
      description: "The current state of the upload.  Can be one of the following:\n\n_Accepted: The file has been accepted and a jobId has ben created.\n\n"
      type: string
      enum:
        - ACCEPTED
        - PENDING,
        - COMPLETE
        - CANCELED
        - ERROR

    entityObject:
      type: object
      required:
        - id
        - entity
        - suppressed
        - creationDate
        - lastModifiedDate
        - status
        - listType
        - client
        - bounceState

      properties:
        id:
          type: string
          description: The identifier of entity.
          format: uuid
          example: 91acd0b4-753b-4366-8893-d5440c4d9b15
        entity:
          properties:
            type: 
              type: string
              example: email
            entityValue:
              type: string
              description: An email address
              example: bademailaddress@domain.com
        suppressed:
          $ref: '#/components/schemas/suppressed'
        creationDate:
          type: number
          example: '1631739725150'
        lastModifiedDate:
          type: number
          example: '1631739725150'
        status:
          $ref: '#/components/schemas/status'
        listType:
          $ref: '#/components/schemas/listType'
        client:
          $ref: '#/components/schemas/client'
        bounceState:
          $ref: '#/components/schemas/bounceState'

    addEntityObject:
      type: object
      required:
        - id
        - entity
        - suppressed
        - creationDate
        - lastModifiedDate
        - status
        - listType
        - client

      properties:
        id:
          type: string
          description: The identifier of entity.
          format: uuid
          example: 91acd0b4-753b-4366-8893-d5440c4d9b15
        entity:
          properties:
            type: 
              type: string
              example: email
            entityValue:
              type: string
              description: An email address
              example: bademailaddress@domain.com
        suppressed:
          $ref: '#/components/schemas/suppressed'
        creationDate:
          type: number
          example: '1631739725150'
        lastModifiedDate:
          type: number
          example: '1631739725150'
        status:
          $ref: '#/components/schemas/status'
        listType:
          $ref: '#/components/schemas/listType'
        client:
          $ref: '#/components/schemas/client'

    domainEntityObject:
      type: object
      required:
        - id
        - entity
        - suppressed
        - creationDate
        - lastModifiedDate
        - status
        - listType
        - client

      properties:
        id:
          type: string
          description: The identifier of entity.
          format: uuid
          example: 91acd0b4-753b-4366-8893-d5440c4d9b15
        entity:
          properties:
            type: 
              type: string
              example: "domain"
            entityValue:
              type: string
              description: An email domain
              example: baddomain.com
        suppressed:
          $ref: '#/components/schemas/suppressed'
        creationDate:
          type: number
          example: '1631739725150'
        lastModifiedDate:
          type: number
          example: '1631739725150'
        status:
          $ref: '#/components/schemas/status'
        listType:
          $ref: '#/components/schemas/listType'
        client:
          $ref: '#/components/schemas/client'

    client:
      type: object
      properties:
        imsOrgId:
          type: string
          description: The IMS Org id of the calling client
        sandboxId:
          type: string
          description: The sandbox name of the calling client

    listType:
      type: string
      enum:
        - client
        - allowed

    status:
      type: string
      enum:
        - active
        - deleted

    suppressed:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/type'
        user:
          type: string
          description: The name or email address of the user that created the suppression
          example: myemail@myemail.com
        comment:
          type: string
          description: An optional comment about the suppression
          example: deemed to be a fake
        date:
          type: number
          example: '1631739725150'
    
    type:
      type: string
      enum:
        - MANUAL
        - HARD
        - SOFT

    # entityType:
    #   type: string
    #   enum:
    #     - email
    #     - domain

    bounceType:
      type: string
      enum:
        - HARD
        - SOFT
        - SUCCEEDED
        - IGNORED

    bounceState:
      type: object
      properties:
        softCount:
          type: integer
          description: The current soft bounce count
          example: 1
        bounceEvents:
          type: array
          items:
            $ref: '#/components/schemas/bounceEvents'

    bounceEvents:
      properties:
        messageId:
          type: string
          description: The message Id associated with the message execution send attempt.
        date:
          type: string
          format: date-time
          example: '2016-08-29T19:12:33.001Z'
        message:
          type: string
          example: Mailbox is full
        bounceType:
          type: string
          example: SOFT

    hRefLink:
      type: object
      required:
        - href
      properties:
        href:
          type: string

    suppressionListLink:
      type: object
      required:
        - self
      properties:
        self:
          $ref: '#/components/schemas/hRefLink'
        next:
          $ref: '#/components/schemas/hRefLink'
      example:
        self:
          href: '/config/suppression/addresses?type=CLIENT&limit=20&orderby=entityvalue'
        next:
          href: '/config/suppression/addresses?type=CLIENT&limit=20&start=bademailtest10013@bademail.com&orderby=entityvalue'

    page:
      type: object
      properties:
        orderby:
          type: string
          enum:
            - entityvalue
            - entitytype
            - creationdate
            - lastmodifieddate
            - suppresseddate
            - suppresseduser
            - suppressedcomment
          example: '-entityvalue'
        next:
          type: string
          example: bademailtest10013@bademail.com
        count:
          type: integer
          example: 1
    
    suppressionListResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/entityObject'

    suppressionListAddResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/addEntityObject'

    domainSuppressionListResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/domainEntityObject'


    uploadListLink:
      type: object
      required:
        - self
      properties:
        self:
          $ref: '#/components/schemas/hRefLink'
        next:
          $ref: '#/components/schemas/hRefLink'
      example:
        self:
          href: '/upload/jobs?limit=1&orderby=-createtime'
        next:
          href: '/upload/jobs?limit=1&start=1639983247&orderby=-createtime'

    uploadPage:
      type: object
      properties:
        orderby:
          type: string
          enum:
            - jobid
            - user
            - filename
            - createtime
            - endtime
            - status
            - responsecode
            - recordcount
            - handledcount
            - failedcount
            - id
          example: '-createtime'
        next:
          type: string
          example: "1639983247"
        count:
          type: integer
          example: 1
    
    uploadListResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/uploads'

    uploadJobResponse:
      type: object
      allOf:
        - $ref: '#/components/schemas/uploadJob'