> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.mailercloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Suppressions

> Returns the recipients on your suppression list, newest first. Narrow the result with a search term, a reason, or a date range, and page through it with `page` or by following `next_cursor`.

A suppressed recipient is rejected on every future send until it is reactivated.

**Sample Code**



## OpenAPI

````yaml /openapi-emailapi.json post /v1/transactional-email/suppressions/search
openapi: 3.1.0
info:
  title: Mailercloud Email API
  version: 1.0.0
  description: Transactional and personalized email sending — the Mailercloud API Platform.
servers:
  - url: https://email-api.mailercloud.com
security:
  - apiKey: []
tags:
  - name: Email
paths:
  /v1/transactional-email/suppressions/search:
    post:
      tags:
        - Email
      summary: Search Suppressions
      description: >-
        Returns the recipients on your suppression list, newest first. Narrow
        the result with a search term, a reason, or a date range, and page
        through it with `page` or by following `next_cursor`.


        A suppressed recipient is rejected on every future send until it is
        reactivated.


        **Sample Code**
      operationId: search-suppressions
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                search:
                  type: string
                  description: Match any part of an email address.
                reason:
                  type: string
                  enum:
                    - all
                    - hard_bounced
                    - spam_complaint
                    - manual
                  default: all
                  description: Limit the result to one reason.
                page:
                  type: integer
                  minimum: 1
                  default: 1
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                  default: 25
                sort_order:
                  type: string
                  enum:
                    - desc
                    - asc
                  default: desc
                  description: Order by the date the recipient was suppressed.
                date_from:
                  type: string
                  example: '2026-08-01'
                  description: >-
                    Start of the range, as `YYYY-MM-DD` in your account's
                    timezone.
                date_to:
                  type: string
                  example: '2026-08-31'
                  description: End of the range.
                counts:
                  type: boolean
                  default: true
                  description: >-
                    Set to `false` to skip the per-reason totals when paging
                    through a large list.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        email:
                          type: string
                          format: email
                          description: The suppressed recipient.
                        reason:
                          type: string
                          enum:
                            - hard_bounced
                            - spam_complaint
                            - manual
                          description: Why the recipient was suppressed.
                        source:
                          type: string
                          enum:
                            - automatic
                            - user
                            - api
                            - csv
                          description: How the entry was created.
                        smtp_response:
                          type: string
                          description: >-
                            The receiving server's response, for automatic
                            suppressions. Empty for manual entries.
                        date_added:
                          type: integer
                          format: int64
                          description: >-
                            When the recipient was suppressed, as a Unix
                            timestamp in UTC.
                        date_added_local:
                          type: string
                          example: '2026-08-19 05:34:10'
                          description: The same moment rendered in your account's timezone.
                  page:
                    type: integer
                  limit:
                    type: integer
                  counts:
                    type: object
                    description: Totals per reason, plus `all`.
                    additionalProperties:
                      type: integer
                  next_cursor:
                    type: object
                    description: >-
                      Pass back as `after` to fetch the following page. Absent
                      on the last page.
              example:
                data:
                  - email: one@example.com
                    reason: hard_bounced
                    source: automatic
                    smtp_response: 5.1.1 (bad destination mailbox address)
                    date_added: 1787204050
                    date_added_local: '2026-08-19 05:34:10'
                page: 1
                limit: 25
                counts:
                  all: 1158
                  hard_bounced: 1156
                  spam_complaint: 2
                  manual: 0
        '400':
          description: A filter value could not be read.
        '401':
          description: Authorization failed.
      servers:
        - url: https://cloudapi.mailercloud.com
          description: Suppression endpoints are served on the main API host.
      x-codeSamples:
        - lang: cURL
          source: >-
            curl -X POST
            https://cloudapi.mailercloud.com/v1/transactional-email/suppressions/search
            \
              -H "Authorization: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"reason": "hard_bounced", "limit": 25}'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your Mailercloud API key (plain text, no Bearer prefix). Create keys in
        Settings → API.

````