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

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


        **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
      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.
                        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
                    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"]}'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your Mailercloud API key (plain text, no Bearer prefix). Create keys in
        Settings → API.

````