Oracle ${suppression Tag} API

openapi: 3.2.0
info:
  description: "Use the Email Delivery API to do the necessary set up to send high-volume and application-generated emails through the OCI Email Delivery service.\nFor more information, see [Overview of the Email Delivery Service](/iaas/Content/Email/Concepts/overview.htm).\n\n **Note:** Write actions (POST, UPDATE, DELETE) may take several minutes to propagate and be reflected by the API.\n If a subsequent read request fails to reflect your changes, wait a few minutes and try again.\n"
  license:
    name: Oracle Corporation
  title: Email Delivery ${suppression Tag} ${suppression Tag} API
  version: '20170907'
  x-provenance:
    method: harvested
    first_party: true
    publisher: Oracle
    source: https://docs.oracle.com/en-us/iaas/api/specs/2b8421e2e819f20bff147090f9d2586190bb5c6d3b8562ffb01d9f9fa99542be.yaml
    harvested: '2026-08-04'
    note: Published by Oracle as the contract for the Email Delivery API OCI service and stored verbatim; API Evangelist added only this provenance block.
  x-evidence:
  - url: https://docs.oracle.com/en-us/iaas/api/specs/index.json
    what: Oracle's own index of every OCI service specification
  - url: https://docs.oracle.com/en-us/iaas/api/specs/2b8421e2e819f20bff147090f9d2586190bb5c6d3b8562ffb01d9f9fa99542be.yaml
    what: the harvested document for Email Delivery API
servers:
- url: https://127.0.0.1/20170907
tags:
- name: ${suppression-tag}
paths:
  /suppressions:
    get:
      description: 'Gets a list of suppressed recipient email addresses for a user. The

        `compartmentId` for suppressions must be a tenancy OCID. The returned list

        is sorted by creation time in descending order.

        '
      operationId: ListSuppressions
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/compartmentIdQueryParam'
      - $ref: '#/components/parameters/suppressionEmailAddressQueryParam'
      - $ref: '#/components/parameters/suppressionStartTimeCreatedQueryParam'
      - $ref: '#/components/parameters/suppressionEndTimeCreatedQueryParam'
      - $ref: '#/components/parameters/PaginationTokenQueryParam'
      - $ref: '#/components/parameters/PaginationLimitQueryParam'
      - $ref: '#/components/parameters/SortByQueryParam'
      - $ref: '#/components/parameters/SortOrderQueryParam'
      responses:
        '200':
          description: The list of suppression summary information.
          headers:
            opc-next-page:
              description: 'For list pagination. When this header appears in the response, additional pages of results remain.

                For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/SuppressionSummary'
                type: array
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/Error'
      summary: Get a summary of suppressed email addresses.
      tags:
      - ${suppression-tag}
      x-example: 'GET /20170907/suppressions/?compartmentId=ocid1.tenancy.oc1...HTTP/1.1

        Host: ctrl.email.us-phoenix-1.oci.oraclecloud.com

        <var>&lt;authorization and other headers&gt;</var>

        '
      x-related-resource: '#/definitions/Suppression'
    post:
      description: 'Adds recipient email addresses to the suppression list for a tenancy.

        Addresses added to the suppression list via the API are denoted as

        "MANUAL" in the `reason` field. *Note:* All email addresses added to the

        suppression list are normalized to include only lowercase letters.

        '
      operationId: CreateSuppression
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      responses:
        '200':
          description: The newly created suppression.
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suppression'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/Error'
      summary: Creates an email suppression for a tenancy.
      tags:
      - ${suppression-tag}
      x-example: "POST /20170907/suppressions HTTP/1.1\nHost: ctrl.email.us-phoenix-1.oci.oraclecloud.com\n<var>&lt;authorization and other headers&gt;</var>\n{\n  \"compartmentId\": \"ocid1.tenancy.oc1..xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n  \"emailAddress\": \"test.user@mydomain.example.com\"\n}\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSuppressionDetails'
        description: 'Adds a single email address to the suppression list for a compartment''s tenancy.

          '
        required: true
  /suppressions/{suppressionId}:
    delete:
      description: 'Removes a suppressed recipient email address from the suppression list

        for a tenancy in a given compartment for a provided `suppressionId`.

        '
      operationId: DeleteSuppression
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/suppressionIdPathParam'
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/Error'
      summary: Deletes a suppressed email address.
      tags:
      - ${suppression-tag}
      x-example: 'DELETE /20170907/suppressions/ocid1.emailsuppression.oc1...HTTP/1.1

        Host: ctrl.email.us-phoenix-1.oci.oraclecloud.com

        <var>&lt;authorization and other headers&gt;</var>

        '
      x-related-resource: '#/definitions/Suppression'
    get:
      description: 'Gets the details of a suppressed recipient email address for a given

        `suppressionId`. Each suppression is given a unique OCID.

        '
      operationId: GetSuppression
      parameters:
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/suppressionIdPathParam'
      responses:
        '200':
          description: The suppression details for the specified OCID.
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Suppression'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
        default:
          $ref: '#/components/responses/Error'
      summary: Get a suppressed email address.
      tags:
      - ${suppression-tag}
      x-example: 'GET /20170907/suppressions/ocid1.emailsuppression.oc1...HTTP/1.1

        Host: ctrl.email.us-phoenix-1.oci.oraclecloud.com

        <var>&lt;authorization and other headers&gt;</var>

        '
components:
  parameters:
    PaginationTokenQueryParam:
      description: 'For list pagination. The value of the opc-next-page response header from the previous "List" call.

        For important details about how pagination works,

        see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

        '
      in: query
      name: page
      x-default-description: 'null'
      schema:
        type: string
        maxLength: 2000
        minLength: 1
    SortByQueryParam:
      description: 'The field to sort by. The `TIMECREATED` value returns the list in in

        descending order by default. The `EMAILADDRESS` value returns the list in

        ascending order by default. Use the `SortOrderQueryParam` to change the

        direction of the returned list of items.

        '
      in: query
      name: sortBy
      required: false
      x-default-description: 'null'
      schema:
        type: string
        enum:
        - TIMECREATED
        - EMAILADDRESS
    compartmentIdQueryParam:
      description: The OCID for the compartment.
      in: query
      name: compartmentId
      required: true
      schema:
        type: string
    PaginationLimitQueryParam:
      description: 'For list pagination. The maximum number of results per page, or items to return in a

        paginated "List" call. `1` is the minimum, `1000` is the maximum. For important details about

        how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

        '
      in: query
      name: limit
      x-default-description: 'null'
      schema:
        type: integer
        maximum: 1000
        minimum: 1
    suppressionEndTimeCreatedQueryParam:
      description: 'Search for suppressions that were created within a specific date range,

        using this parameter to specify the latest creation date for the returned

        list (exclusive). Specifying this parameter without the corresponding

        `timeCreatedGreaterThanOrEqualTo` parameter will retrieve all suppressions created before the

        specified end date, in "YYYY-MM-ddThh:mmZ" format with a Z offset, as

        defined by [RFC 3339](https://tools.ietf.org/html/rfc3339).


        **Example:** 2016-12-19T16:39:57.600Z

        '
      in: query
      name: timeCreatedLessThan
      required: false
      x-default-description: 'null'
      schema:
        type: string
        format: date-time
        maxLength: 254
    SortOrderQueryParam:
      description: 'The sort order to use, either ascending or descending order.

        '
      in: query
      name: sortOrder
      required: false
      x-default-description: 'null'
      x-obmcs-top-level-enum: '#/definitions/SortOrder'
      schema:
        type: string
        enum:
        - ASC
        - DESC
    suppressionEmailAddressQueryParam:
      description: The email address of the suppression.
      in: query
      name: emailAddress
      x-default-description: 'null'
      schema:
        type: string
        format: email
        maxLength: 254
        minLength: 6
    suppressionIdPathParam:
      description: The unique OCID of the suppression.
      in: path
      name: suppressionId
      required: true
      schema:
        type: string
        maxLength: 255
        minLength: 1
    RequestIdHeader:
      description: The request ID for tracing from the system
      in: header
      name: opc-request-id
      schema:
        type: string
    suppressionStartTimeCreatedQueryParam:
      description: 'Search for suppressions that were created within a specific date range,

        using this parameter to specify the earliest creation date for the

        returned list (inclusive). Specifying this parameter without the

        corresponding `timeCreatedLessThan` parameter will retrieve suppressions created from the

        given `timeCreatedGreaterThanOrEqualTo` to the current time, in "YYYY-MM-ddThh:mmZ" format with a

        Z offset, as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339).


        **Example:** 2016-12-19T16:39:57.600Z

        '
      in: query
      name: timeCreatedGreaterThanOrEqualTo
      required: false
      x-default-description: 'null'
      schema:
        type: string
        format: date-time
        maxLength: 254
  responses:
    '400':
      description: Incorrectly formatted request.
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '204':
      description: The operation completed successfully.
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
    '404':
      description: Authorization failed or the requested resource was not found.
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error:
      description: An error has occurred.
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: 'The required information to complete authentication was not provided or

        was incorrect. Extra detail may be provided in the response body.

        '
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '409':
      description: Authorization failed or the requested resource already exists.
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '500':
      description: Internal Server Error.
      headers:
        opc-request-id:
          description: 'Unique Oracle-assigned identifier for the request. If you need to contact

            Oracle about a particular request, please provide the request ID.

            '
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      description: An error has occurred.
      properties:
        code:
          description: 'A short error code that defines the error, meant for programmatic parsing. See

            [API Errors](/Content/API/References/apierrors.htm).

            '
          type: string
        message:
          description: A human-readable error string.
          type: string
      required:
      - code
      - message
    SuppressionSummary:
      description: The full information representing a suppression.
      properties:
        compartmentId:
          description: The OCID for the compartment.
          maxLength: 255
          minLength: 1
          type: string
        emailAddress:
          description: The email address of the suppression.
          format: email
          maxLength: 254
          minLength: 6
          type: string
        id:
          description: The unique OCID of the suppression.
          maxLength: 255
          minLength: 1
          type: string
        reason:
          description: The reason that the email address was suppressed.
          enum:
          - UNKNOWN
          - HARDBOUNCE
          - COMPLAINT
          - MANUAL
          - SOFTBOUNCE
          - UNSUBSCRIBE
          type: string
          x-obmcs-top-level-enum: '#/definitions/SuppressionReason'
        timeCreated:
          description: 'The date and time a recipient''s email address was added to the

            suppression list, in "YYYY-MM-ddThh:mmZ" format with a Z offset, as

            defined by [RFC 3339](https://tools.ietf.org/html/rfc3339).

            '
          format: date-time
          maxLength: 254
          type: string
      required:
      - id
      - compartmentId
      - emailAddress
    Suppression:
      description: The full information representing an email suppression.
      properties:
        compartmentId:
          description: 'The OCID of the compartment to contain the suppression. Since

            suppressions are at the customer level, this must be the tenancy

            OCID.

            '
          maxLength: 255
          minLength: 1
          type: string
        emailAddress:
          description: Email address of the suppression.
          format: email
          maxLength: 254
          minLength: 6
          type: string
        errorDetail:
          description: 'The specific error message returned by a system that resulted in the suppression.

            This message is usually an SMTP error code with additional descriptive text.

            Not provided for all types of suppressions.

            '
          maxLength: 255
          type: string
        errorSource:
          description: 'DNS name of the source of the error that caused the suppression.

            Will be set to either the remote-mta or reporting-mta field from a delivery status notification (RFC 3464) when available.

            Not provided for all types of suppressions, and not always known.


            Note: Most SMTP errors that cause suppressions come from software run by email receiving systems rather than from OCI email delivery itself.

            '
          maxLength: 1024
          type: string
        id:
          description: The unique ID of the suppression.
          maxLength: 255
          minLength: 1
          type: string
        messageId:
          description: 'The value of the Message-ID header from the email that triggered a suppression.

            This value is as defined in RFC 5322 section 3.6.4, excluding angle-brackets.

            Not provided for all types of suppressions.

            '
          maxLength: 255
          type: string
        reason:
          description: The reason that the email address was suppressed. For more information on the types of bounces, see [Suppression List](https://docs.us-phoenix-1.oraclecloud.com/Content/Email/Concepts/overview.htm#components).
          enum:
          - UNKNOWN
          - HARDBOUNCE
          - COMPLAINT
          - MANUAL
          - SOFTBOUNCE
          - UNSUBSCRIBE
          type: string
          x-obmcs-top-level-enum: '#/definitions/SuppressionReason'
        timeCreated:
          description: 'The date and time the suppression was added in "YYYY-MM-ddThh:mmZ"

            format with a Z offset, as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339).

            '
          format: date-time
          maxLength: 254
          type: string
        timeLastSuppressed:
          description: 'The last date and time the suppression prevented submission

            in "YYYY-MM-ddThh:mmZ"

            format with a Z offset, as defined by [RFC 3339](https://tools.ietf.org/html/rfc3339).

            '
          format: date-time
          type: string
      required:
      - id
      - compartmentId
      - emailAddress
    CreateSuppressionDetails:
      description: The details needed for creating a single suppression.
      properties:
        compartmentId:
          description: 'The OCID of the compartment to contain the suppression. Since

            suppressions are at the customer level, this must be the tenancy

            OCID.

            '
          maxLength: 255
          minLength: 1
          type: string
        emailAddress:
          description: The recipient email address of the suppression.
          format: email
          minLength: 6
          type: string
      required:
      - compartmentId
      - emailAddress
x-anchors:
  x-headers:
    etag:
      description: 'For optimistic concurrency control. See `if-match`.

        '
      type: string
    location:
      description: 'The full URI of the resource related to the request

        '
      format: uri-reference
      type: string
    opc-next-page:
      description: 'For list pagination. When this header appears in the response, additional pages of results remain.

        For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

        '
      type: string
    opc-previous-page:
      description: 'For list pagination. When this header appears in the response, previous pages of results remain.

        For important details about how pagination works, see [List Pagination](/iaas/Content/API/Concepts/usingapi.htm#nine).

        '
      type: string
    opc-request-id:
      description: 'Unique Oracle-assigned identifier for the request. If you need to contact

        Oracle about a particular request, please provide the request ID.

        '
      type: string
    opc-total-items:
      description: 'The total number of items returned from the request.

        '
      type: integer
    opc-work-request-id:
      description: 'Unique Oracle-assigned identifier for the asynchronous request. You can use this to query status of the asynchronous operation.

        '
      type: string
    retry-after:
      description: A decimal number representing the number of seconds the client should wait before polling this endpoint again.
      type: integer
  x-properties:
    definedTags:
      additionalProperties:
        additionalProperties:
          description: 'The value of the tag. Only string type is supported as valid value type.

            '
          type: object
        description: 'Key-value pair representing predefined tags'' keys and values scoped to a namespace.


          Example: `{"bar-key": "value"}`

          '
        type: object
      description: 'Defined tags for this resource. Each key is predefined and scoped to a namespace.

        For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).


        Example: `{"Operations": {"CostCenter": "42"}}`

        '
      type: object
    freeformTags:
      additionalProperties:
        type: string
      description: 'Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace.

        For more information, see [Resource Tags](/Content/General/Concepts/resourcetags.htm).


        Example: `{"Department": "Finance"}`

        '
      type: object
    systemTags:
      additionalProperties:
        additionalProperties:
          description: 'The value of the tag. Only string, integer and boolean types are supported.

            '
          type: object
        description: 'Key-value pair representing system tags'' keys and values scoped to a namespace.

          Example: `{"bar-key": "value"}`

          '
        type: object
      description: 'Usage of system tag keys. These predefined keys are scoped to namespaces.

        Example: `{"orcl-cloud": {"free-tier-retained": "true"}}`

        '
      type: object
x-oracle-package: com.oracle.pic.email