Adobe Suite Suppression API

openapi: 3.2.0
info:
  title: Suppression API
  description: 'With this API, you can control your outgoing messages using suppression and allow lists.


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