> ## 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.

# Add Suppressions

> Adds one or more recipients to your suppression list. They are rejected on every future send until reactivated.

The request is all-or-nothing: if any address is not a valid email address the whole request is rejected and the offending values are named, so a typo cannot leave you believing an address is suppressed when it is not.

Each request can carry a `scope`. A scoped entry only takes effect once your account's suppression policy is stream-scoped; until then every entry blocks all sends.

**Sample Code**



## OpenAPI

````yaml /openapi-emailapi.json post /v1/transactional-email/suppressions
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:
    post:
      tags:
        - Email
      summary: Add Suppressions
      description: >-
        Adds one or more recipients to your suppression list. They are rejected
        on every future send until reactivated.


        The request is all-or-nothing: if any address is not a valid email
        address the whole request is rejected and the offending values are
        named, so a typo cannot leave you believing an address is suppressed
        when it is not.


        Each request can carry a `scope`. A scoped entry only takes effect once
        your account's suppression policy is stream-scoped; until then every
        entry blocks all sends.


        **Sample Code**
      operationId: add-suppressions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: The addresses to suppress.
                  example:
                    - one@example.com
                    - two@example.com
                scope:
                  type: string
                  enum:
                    - global
                    - marketing
                    - transactional
                  default: global
                  description: >-
                    The scope applied to every address in this request. `global`
                    (the default) blocks all sends. `marketing` or
                    `transactional` block only that stream once your account's
                    suppression policy is set to stream-scoped (Settings →
                    Suppression); under the default account-wide policy every
                    entry blocks all sends regardless of scope. An omitted or
                    unrecognised value falls back to `global` — a suppression is
                    never silently narrowed.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  added:
                    type: integer
                    description: Addresses newly added to the list.
                  skipped:
                    type: integer
                    description: Addresses that were already suppressed.
                  duplicates:
                    type: integer
                    description: Addresses that appeared more than once in this request.
                  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.
                        scope:
                          type: string
                          enum:
                            - global
                            - marketing
                            - transactional
                            - all_streams
                          description: >-
                            Which sends this entry blocks when your account uses
                            stream-scoped suppression: `global` blocks every
                            send (hard bounces, and every entry created before
                            scopes existed, are always global), `marketing` and
                            `transactional` block only that stream, and
                            `all_streams` means both streams were recorded
                            separately. Under the default account-wide policy
                            every entry blocks all sends regardless of its
                            scope.
                        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.
              example:
                added: 1
                skipped: 1
                duplicates: 0
                data:
                  - email: one@example.com
                    reason: manual
                    source: api
                    scope: marketing
                    smtp_response: ''
                    date_added: 1787204050
                    date_added_local: '2026-08-19 05:34:10'
        '400':
          description: One or more addresses are not valid email addresses.
        '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
            \
              -H "Authorization: YOUR_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{"emails": ["one@example.com", "two@example.com"], "scope": "marketing"}'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your Mailercloud API key (plain text, no Bearer prefix). Create keys in
        Settings → API.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.