openapi: 3.2.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
servers:
- url: https://platform-stage.adobe.io/ajo
  description: Stage Environment
- url: https://platform.adobe.io/ajo
  description: Production Environment
security:
- BearerAuth: []
tags:
- name: Suppression
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:
  schemas:
    uploadStatus:
      description: 'The current state of the upload.  Can be one of the following:


        _Accepted: The file has been accepted and a jobId has ben created.


        '
      type: string
      enum:
      - ACCEPTED
      - PENDING,
      - COMPLETE
      - CANCELED
      - ERROR
    bounceState:
      type: object
      properties:
        softCount:
          type: integer
          description: The current soft bounce count
          example: 1
        bounceEvents:
          type: array
          items:
            $ref: '#/components/schemas/bounceEvents'
    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'
    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
    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
    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
    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
    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
    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
    suppressionListResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/entityObject'
    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'
    uploadListResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/uploads'
    listType:
      type: string
      enum:
      - client
      - allowed
    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
    domainSuppressionListResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/domainEntityObject'
    hRefLink:
      type: object
      required:
      - href
      properties:
        href:
          type: string
    status:
      type: string
      enum:
      - active
      - deleted
    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
    type:
      type: string
      enum:
      - MANUAL
      - HARD
      - SOFT
    suppressionListAddResponse:
      type: object
      allOf:
      - $ref: '#/components/schemas/addEntityObject'
    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'
    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'
    uploadPost:
      type: object
      properties:
        success:
          type: object
          properties:
            jobId:
              type: string
              example: 6caaed1b-d7bd-4065-a745-185e9af3b63a
              description: Unique job identifier.
    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'
    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'
    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
  parameters:
    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
    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
    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
    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-api-key:
      name: x-api-key
      description: The API key belonging to the calling client.
      required: true
      in: header
      schema:
        type: string
    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
    x-sandbox-name:
      name: x-sandbox-name
      description: Provides the platform Sandbox Name
      required: true
      in: header
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: The authentication token to access the service.