Customer.io ESP Suppression API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Customer.io App ESP Suppression API
  description: Our App API provides ways to trigger messages and retrieve information about people, campaigns, broadcasts, and more.
servers:
- url: https://api.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs. These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
- url: https://api-eu.customer.io
  description: The base URL for broadcasts, transactional messages, and data-retrieval APIs (EU region). These endpoints use bearer authorization, and require a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
tags:
- name: ESP Suppression
  description: 'If you use Customer.io as your email service provider (ESP), these endpoints help you retrieve information about email addresses suppressed directly by the ESP. ESP-based suppressions are different from suppression in Customer.io: these are addresses that the ESP suppressed automatically because a message bounced, a customer requested they not be contacted again, etc. These are _not_ addresses that you deleted and suppressed either in our UI or through the API.'
paths:
  /v1/esp/search_suppression/{email_address}:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - name: email_address
      in: path
      required: true
      description: The email address of the person you want to look up.
      schema:
        type: string
    get:
      summary: Look up an ESP-suppressed address
      operationId: getSuppression
      security:
      - Bearer-Auth: []
      description: Look up an email address to learn if, and why, it was suppressed by the email service provider (ESP).
      tags:
      - ESP Suppression
      responses:
        '200':
          description: Returns an array of suppressed email addresses.
          content:
            application/json:
              schema:
                x-scalar-ignore: true
                type: object
                properties:
                  category:
                    type: string
                    description: The reason the addresses are suppressed.
                    enum:
                    - bounces
                    - spam
                    example: bounces
                  suppressions:
                    type: array
                    description: The addresses suppressed in this category.
                    items:
                      type: object
                      properties:
                        created:
                          type: integer
                          format: Unix timestamp
                          description: The timestamp (in seconds), when the ESP suppressed the address.
                          example: 1650895738
                        email:
                          type: string
                          description: The email address that the ESP suppressed.
                          example: bounced.person@example.com
                        reason:
                          type: string
                          description: The reason for the suppression, as [recorded by Mailgun](https://documentation.mailgun.com/en/latest/api-suppressions.html).
                          example: Uploaded manually via api.customer.io
                        status:
                          type: string
                          description: The status code for the suppression, as [recorded by mailgun](https://documentation.mailgun.com/en/latest/api-suppressions.html). This is normally `550`.
                          example: '550'
        '429':
          description: Your request is over the 10-per-second limit.
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/esp/search_suppression/{email_address}"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"GET\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/esp/search_suppression/%7Bemail_address%7D\",\n  \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/esp/search_suppression/%7Bemail_address%7D")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Get.new(url)


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          conn.request("GET", "/v1/esp/search_suppression/%7Bemail_address%7D")


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/esp/search_suppression/%7Bemail_address%7D\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
  /v1/esp/suppression/{suppression_type}:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - name: suppression_type
      description: The reason a person's email address was suppressed by the email service provider (ESP).
      in: path
      required: true
      schema:
        type: string
        enum:
        - blocks
        - bounces
        - spam_reports
        - invalid_emails
    - name: limit
      in: query
      required: false
      description: The maximum number of results you want to retrieve per page.
      schema:
        type: integer
        default: 100
        maximum: 1000
    - name: offset
      in: query
      required: false
      description: The number of records to skip before retrieving results.
      schema:
        type: integer
        default: 0
    - name: domain
      in: query
      required: false
      description: Filter by sending domain.
      schema:
        type: string
        example: mail.example.com
    get:
      summary: Get ESP-suppressed emails by type
      operationId: getSuppressionByType
      security:
      - Bearer-Auth: []
      description: 'Find addresses suppressed by the Email Service Provider (ESP) for a particular reason—bounces, blocks, spam reports, or invalid email addresses.


        You can get up to 1000 addresses per request. Use the `offset` parameter to get addresses beyond the first 1000.


        If you have multiple sending domains, we recommend querying for each domain separately, as an email address may be suppressed on multiple domains.


        **Note**: If you have a large number of suppressions, consider using the Get ESP-suppressed emails by domain endpoint. It''s more performant for large datasets.'
      tags:
      - ESP Suppression
      responses:
        '200':
          description: Returns an array of suppressed email addresses.
          content:
            application/json:
              schema:
                x-scalar-ignore: true
                type: object
                properties:
                  category:
                    type: string
                    description: The reason the addresses are suppressed.
                    enum:
                    - bounces
                    - spam
                    example: bounces
                  suppressions:
                    type: array
                    description: The addresses suppressed in this category.
                    items:
                      type: object
                      properties:
                        created:
                          type: integer
                          format: Unix timestamp
                          description: The timestamp (in seconds), when the ESP suppressed the address.
                          example: 1650895738
                        email:
                          type: string
                          description: The email address that the ESP suppressed.
                          example: bounced.person@example.com
                        reason:
                          type: string
                          description: The reason for the suppression, as [recorded by Mailgun](https://documentation.mailgun.com/en/latest/api-suppressions.html).
                          example: Uploaded manually via api.customer.io
                        status:
                          type: string
                          description: The status code for the suppression, as [recorded by mailgun](https://documentation.mailgun.com/en/latest/api-suppressions.html). This is normally `550`.
                          example: '550'
        '429':
          description: Your request is over the 10-per-second limit.
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/esp/suppression/{suppression_type}"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"GET\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/esp/suppression/%7Bsuppression_type%7D\",\n  \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/esp/suppression/%7Bsuppression_type%7D")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Get.new(url)


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          conn.request("GET", "/v1/esp/suppression/%7Bsuppression_type%7D")


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/esp/suppression/%7Bsuppression_type%7D\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
  /v1/esp/domains/{domain_name}/suppression/{suppression_type}:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - name: domain_name
      in: path
      required: true
      description: The sending domain you want to look up suppressions for.
      schema:
        type: string
        example: mail.example.com
    - name: suppression_type
      description: The reason a person's email address was suppressed by the email service provider (ESP).
      in: path
      required: true
      schema:
        type: string
        enum:
        - blocks
        - bounces
        - spam_reports
        - invalid_emails
    get:
      summary: Get ESP-suppressed emails by domain
      operationId: getDomainSuppressionsByType
      security:
      - Bearer-Auth: []
      description: 'Find addresses suppressed by the Email Service Provider (ESP) for a particular reason on a specific sending domain.


        You can get up to 1000 addresses per request. Use the `start` parameter with the `next` value from the previous response to paginate through results.'
      tags:
      - ESP Suppression
      parameters:
      - name: limit
        in: query
        required: false
        description: The maximum number of results you want to retrieve per page.
        schema:
          type: integer
          default: 100
          maximum: 1000
      - name: start
        in: query
        required: false
        description: The token for the page of results you want to return. Responses contain a `next` property. Use this property as the `start` value to return the next page of results.
        schema:
          type: string
      - name: email
        in: query
        required: false
        description: Filter results to a specific email address. When provided, returns at most one result and cursor-based pagination does not apply.
        schema:
          type: string
      responses:
        '200':
          description: Returns an array of suppressed email addresses for the domain.
          content:
            application/json:
              schema:
                type: object
                properties:
                  category:
                    type: string
                    description: The reason the addresses are suppressed.
                    enum:
                    - bounces
                    - spam
                    example: bounces
                  suppressions:
                    type: array
                    description: The addresses suppressed in this category.
                    items:
                      type: object
                      properties:
                        created:
                          type: integer
                          format: Unix timestamp
                          description: The timestamp (in seconds), when the ESP suppressed the address.
                          example: 1650895738
                        email:
                          type: string
                          description: The email address that the ESP suppressed.
                          example: bounced.person@example.com
                        reason:
                          type: string
                          description: The reason for the suppression, as [recorded by Mailgun](https://documentation.mailgun.com/en/latest/api-suppressions.html).
                          example: Uploaded manually via api.customer.io
                        status:
                          type: string
                          description: The status code for the suppression, as [recorded by mailgun](https://documentation.mailgun.com/en/latest/api-suppressions.html). This is normally `550`.
                          example: '550'
                  next:
                    type: string
                    description: The `start` value for the next page of results.
        '429':
          description: Your request is over the 10-per-second limit.
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request GET \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url 'https://api.customer.io/v1/esp/domains/{domain_name}/suppression/{suppression_type}?limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE&email=SOME_STRING_VALUE'"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"GET\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/esp/domains/%7Bdomain_name%7D/suppression/%7Bsuppression_type%7D?limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE&email=SOME_STRING_VALUE\",\n  \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/esp/domains/%7Bdomain_name%7D/suppression/%7Bsuppression_type%7D?limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE&email=SOME_STRING_VALUE")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Get.new(url)


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          conn.request("GET", "/v1/esp/domains/%7Bdomain_name%7D/suppression/%7Bsuppression_type%7D?limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE&email=SOME_STRING_VALUE")


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/esp/domains/%7Bdomain_name%7D/suppression/%7Bsuppression_type%7D?limit=SOME_INTEGER_VALUE&start=SOME_STRING_VALUE&email=SOME_STRING_VALUE\"\n\n\treq, _ := http.NewRequest(\"GET\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
  /v1/esp/suppression/{suppression_type}/{email_address}:
    servers:
    - url: https://api.customer.io
      description: This API uses bearer authorization, requiring a [token that you generate in the UI](https://fly.customer.io/settings/api_credentials?keyType=app).
    parameters:
    - name: suppression_type
      description: The reason a person's email address was suppressed by the email service provider (ESP).
      in: path
      required: true
      schema:
        type: string
        enum:
        - blocks
        - bounces
        - spam_reports
        - invalid_emails
    - name: email_address
      in: path
      required: true
      description: The email address of the person you want to look up.
      schema:
        type: string
    delete:
      summary: Un-suppress an ESP-suppressed address
      operationId: deleteSuppression
      security:
      - Bearer-Auth: []
      description: Remove an address from the ESP's suppression list.
      tags:
      - ESP Suppression
      responses:
        '204':
          description: A successful request produces no content.
        '429':
          description: Your request is over the 10-per-second limit.
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request DELETE \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/esp/suppression/{suppression_type}/{email_address}"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"DELETE\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D\",\n  \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Delete.new(url)


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          conn.request("DELETE", "/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D")


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D\"\n\n\treq, _ := http.NewRequest(\"DELETE\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
    post:
      summary: Suppress an email at the ESP
      operationId: postSuppression
      security:
      - Bearer-Auth: []
      description: Suppress an email address at the email service provider (ESP). Addresses suppressed this way are only suppressed through the ESP; these adresses are _not_ suppressed in Customer.io, so the person can remain in your workspace (though emails to the address would be blocked at the ESP).
      tags:
      - ESP Suppression
      responses:
        '200':
          description: A successful request produces an empty response.
          content:
            application/json:
              schema:
                type: object
        '429':
          description: Your request is over the 10-per-second limit.
      x-codeSamples:
      - lang: Shell + Curl
        source: "curl --request POST \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \\\n  --url https://api.customer.io/v1/esp/suppression/{suppression_type}/{email_address}"
      - lang: Node + Native
        source: "const http = require(\"https\");\n\nconst options = {\n  \"method\": \"POST\",\n  \"hostname\": \"api.customer.io\",\n  \"port\": null,\n  \"path\": \"/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D\",\n  \"headers\": {}\n};\n\nconst req = http.request(options, function (res) {\n  const chunks = [];\n\n  res.on(\"data\", function (chunk) {\n    chunks.push(chunk);\n  });\n\n  res.on(\"end\", function () {\n    const body = Buffer.concat(chunks);\n    console.log(body.toString());\n  });\n});\n\nreq.end();"
      - lang: Ruby + Native
        source: 'require ''uri''

          require ''net/http''

          require ''openssl''


          url = URI("https://api.customer.io/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D")


          http = Net::HTTP.new(url.host, url.port)

          http.use_ssl = true

          http.verify_mode = OpenSSL::SSL::VERIFY_NONE


          request = Net::HTTP::Post.new(url)


          response = http.request(request)

          puts response.read_body'
      - lang: Python + Python3
        source: 'import http.client


          conn = http.client.HTTPSConnection("api.customer.io")


          conn.request("POST", "/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D")


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - lang: Go + Native
        source: "package main\n\nimport (\n\t\"fmt\"\n\t\"net/http\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\n\turl := \"https://api.customer.io/v1/esp/suppression/%7Bsuppression_type%7D/%7Bemail_address%7D\"\n\n\treq, _ := http.NewRequest(\"POST\", url, nil)\n\n\tres, _ := http.DefaultClient.Do(req)\n\n\tdefer res.Body.Close()\n\tbody, _ := ioutil.ReadAll(res.Body)\n\n\tfmt.Println(res)\n\tfmt.Println(string(body))\n\n}"
components:
  securitySchemes:
    Bearer-Auth:
      type: http
      scheme: bearer
      description: 'The App API uses a bearer authentication scheme.


        You can generate a bearer token, known as an **App API Key**, with a defined scope in [your account settings](https://fly.customer.io/settings/api_credentials?keyType=app). [Learn more about bearer authorization in Customer.io](/accounts/settings/managing-credentials).

        '
    ServiceAccount-Auth:
      x-scalar-ignore: true
      type: http
      scheme: bearer
      bearerFormat: sa_live_
      description: 'Transactional send endpoints (`/v1/send/email`, `/v1/send/push`, `/v1/send/sms`, `/v1/send/in_app`, `/v1/send/inbox_message`) also accept a service-account bearer token, prefixed with `sa_live_`. Service-account tokens work across workspaces, so you must pass the target workspace as the `X-Workspace-Id` header on each request.


        Service-account tokens are intended for testing and one-off sends—for example, using the Customer.io CLI with an AI agent like Claude to verify that a transactional message renders correctly before wiring it into your production backend. **For the production integration that triggers the message from your application, use an App API Key instead**: it''s workspace-scoped, easier to rotate, and has a smaller blast radius.


        Service-account tokens are server-side credentials. Treat them like any API key—keep them in environment variables or a secret manager, and never embed them in client-side code, mobile apps, or other untrusted contexts.

        '
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token