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

# Managing suppressions

> Learn how to manage suppressions to protect recipients and your domain reputation.

Suppression list entries can be managed via the [suppression list page](https://dash.mailchannels.com/suppression-lists)
or the API. To create a suppression list entry for all sub-accounts, use an API key that belongs to the parent account,
and set `add_to_sub_accounts` to `true`. Otherwise, **suppression list entries belong to the account of the API key used
to create them.**

## Create a suppression entry

<CodeGroup>
  ```bash cURL theme={null}
  #!/usr/bin/env bash
  # Create a suppression entry for a recipient.
  set -u
  : "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY (parent or sub-account) before running}"
  : "${RECIPIENT:?Set RECIPIENT to the email address to suppress}"

  # SUPPRESSION_TYPES is optional, a comma-separated list (e.g. "transactional,non-transactional").
  # If unset, MailChannels uses the default "non-transactional".
  TYPES_FIELD=""
  if [ -n "${SUPPRESSION_TYPES:-}" ]; then
    IFS=',' read -ra TYPES_ARR <<< "$SUPPRESSION_TYPES"
    TYPES_JSON=""
    for t in "${TYPES_ARR[@]}"; do
      TYPES_JSON+=",\"$t\""
    done
    TYPES_FIELD=", \"suppression_types\": [${TYPES_JSON#,}]"
  fi

  curl -X POST https://api.mailchannels.net/tx/v1/suppression-list \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: $MAILCHANNELS_API_KEY" \
    -d "{ \"suppression_entries\": [{ \"recipient\": \"$RECIPIENT\"$TYPES_FIELD }] }"
  ```

  ```javascript Node.js theme={null}
  // Create a suppression entry for a recipient.
  import { MailChannels } from "mailchannels-sdk";

  const { MAILCHANNELS_API_KEY, RECIPIENT, SUPPRESSION_TYPES } = process.env;
  if (!MAILCHANNELS_API_KEY) throw new Error("Set MAILCHANNELS_API_KEY (parent or sub-account) before running");
  if (!RECIPIENT) throw new Error("Set RECIPIENT to the email address to suppress");

  const mailchannels = new MailChannels(MAILCHANNELS_API_KEY);

  // SUPPRESSION_TYPES is optional, a comma-separated list (e.g. "transactional,non-transactional").
  // If unset, MailChannels uses the default "non-transactional".
  const entry = { recipient: RECIPIENT };
  if (SUPPRESSION_TYPES) {
    entry.types = SUPPRESSION_TYPES.split(",").map((t) => t.trim()).filter(Boolean);
  }

  const { success, error } = await mailchannels.suppressions.create({ entries: [entry] });

  if (!success) {
    console.error("Create suppression failed:", error);
    process.exit(1);
  }
  console.log("Suppression created");
  ```

  ```python Python theme={null}
  import os
  import sys

  import mailchannels

  if not os.environ.get("MAILCHANNELS_API_KEY"):
      sys.exit("Set MAILCHANNELS_API_KEY (parent or sub-account) before running")

  recipient = os.environ.get("RECIPIENT")
  if not recipient:
      sys.exit("Set RECIPIENT to the email address to suppress")

  # SUPPRESSION_TYPES is optional, a comma-separated list (e.g. "transactional,non-transactional").
  # If unset, MailChannels uses the default "non-transactional".
  entry: dict = {"recipient": recipient}
  types_env = os.environ.get("SUPPRESSION_TYPES")
  if types_env:
      entry["suppression_types"] = [t.strip() for t in types_env.split(",") if t.strip()]

  response = mailchannels.Suppressions.create([entry])

  print(response)
  ```

  ```php PHP theme={null}
  <?php

  require_once __DIR__ . '/vendor/autoload.php';

  use MailChannels\Client;

  $api_key   = getenv('MAILCHANNELS_API_KEY') or exit("Error: MAILCHANNELS_API_KEY is not set\n");
  $recipient = getenv('RECIPIENT') or exit("Error: RECIPIENT is not set\n");

  $client = new Client(apiKey: $api_key);

  // SUPPRESSION_TYPES is optional, a comma-separated list (e.g. "transactional,non-transactional").
  // If unset, MailChannels uses the default "non-transactional".
  $entry     = ['recipient' => $recipient];
  $types_env = getenv('SUPPRESSION_TYPES');
  if ($types_env) {
      $entry['suppression_types'] = array_values(array_filter(array_map('trim', explode(',', $types_env))));
  }

  $response = $client->suppressions->create([$entry]);

  print_r($response->toArray());
  ```
</CodeGroup>

Set the following before running:

* `MAILCHANNELS_API_KEY` — a parent or sub-account API key.
* `RECIPIENT` — the email address to suppress.
* `SUPPRESSION_TYPES` — optional, a comma-separated list of suppression types to apply. If omitted, the default is `non-transactional`.
  If both `transactional` and `non-transactional` are included, the recipient will not receive any mail. If only `non-transactional`
  is included, the recipient will still receive necessary transactional messages.

## List suppression entries

<CodeGroup>
  ```bash cURL theme={null}
  #!/usr/bin/env bash
  # Retrieve suppression entries for the account.
  set -u
  : "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY (parent or sub-account) before running}"

  curl -X GET "https://api.mailchannels.net/tx/v1/suppression-list" \
    -H "X-Api-Key: $MAILCHANNELS_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { MailChannels } from "mailchannels-sdk";

  const { MAILCHANNELS_API_KEY } = process.env;
  if (!MAILCHANNELS_API_KEY) throw new Error("Set MAILCHANNELS_API_KEY before running");

  const mailchannels = new MailChannels(MAILCHANNELS_API_KEY);

  const { data, error } = await mailchannels.suppressions.list();

  if (error) {
    console.error("List suppressions failed:", error);
    process.exit(1);
  }
  console.log(data);
  ```

  ```python Python theme={null}
  import os
  import sys

  import mailchannels

  if not os.environ.get("MAILCHANNELS_API_KEY"):
      sys.exit("Set MAILCHANNELS_API_KEY (parent or sub-account) before running")

  # Retrieve suppression entries for the account.
  response = mailchannels.Suppressions.list()

  print(response)
  ```

  ```php PHP theme={null}
  <?php

  require_once __DIR__ . '/vendor/autoload.php';

  use MailChannels\Client;

  $api_key = getenv('MAILCHANNELS_API_KEY') or exit("Error: MAILCHANNELS_API_KEY is not set\n");

  $client = new Client(apiKey: $api_key);

  // Retrieve suppression entries for the account.
  $response = $client->suppressions->list();

  print_r($response->toArray());
  ```
</CodeGroup>

Set `MAILCHANNELS_API_KEY` before running. The list endpoint also accepts optional `recipient`, `source`, `created_before`,
`created_after`, `limit`, and `offset` query parameters for filtering and pagination.

## Delete a suppression entry

<CodeGroup>
  ```bash cURL theme={null}
  #!/usr/bin/env bash
  # Delete a suppression entry for a recipient.
  set -u
  : "${MAILCHANNELS_API_KEY:?Set MAILCHANNELS_API_KEY (parent or sub-account) before running}"
  : "${RECIPIENT:?Set RECIPIENT to the email address whose suppression entry should be removed}"

  # SOURCE is optional. Defaults to "api" if unset. Use "all" to delete every entry for the recipient.
  SOURCE_QUERY=""
  if [ -n "${SOURCE:-}" ]; then
    SOURCE_QUERY="?source=$SOURCE"
  fi

  curl -X DELETE "https://api.mailchannels.net/tx/v1/suppression-list/recipients/$RECIPIENT$SOURCE_QUERY" \
    -H "X-Api-Key: $MAILCHANNELS_API_KEY"
  ```

  ```javascript Node.js theme={null}
  import { MailChannels } from "mailchannels-sdk";

  const { MAILCHANNELS_API_KEY, RECIPIENT } = process.env;
  if (!MAILCHANNELS_API_KEY) throw new Error("Set MAILCHANNELS_API_KEY before running");
  if (!RECIPIENT) throw new Error("Set RECIPIENT to the email address whose suppression entry should be removed");

  const mailchannels = new MailChannels(MAILCHANNELS_API_KEY);

  const { success, error } = await mailchannels.suppressions.delete(RECIPIENT);

  if (!success) {
    console.error("Delete suppression failed:", error);
    process.exit(1);
  }
  console.log("Suppression deleted");
  ```

  ```python Python theme={null}
  import os
  import sys

  import mailchannels

  if not os.environ.get("MAILCHANNELS_API_KEY"):
      sys.exit("Set MAILCHANNELS_API_KEY (parent or sub-account) before running")

  recipient = os.environ.get("RECIPIENT")
  if not recipient:
      sys.exit("Set RECIPIENT to the email address whose suppression entry should be removed")

  # SOURCE is optional. Defaults to "api". Pass "all" to delete every entry for the recipient.
  source = os.environ.get("SOURCE")

  response = mailchannels.Suppressions.delete(recipient, source=source)

  print(response)
  ```

  ```php PHP theme={null}
  <?php

  require_once __DIR__ . '/vendor/autoload.php';

  use MailChannels\Client;

  $api_key   = getenv('MAILCHANNELS_API_KEY') or exit("Error: MAILCHANNELS_API_KEY is not set\n");
  $recipient = getenv('RECIPIENT') or exit("Error: RECIPIENT is not set\n");

  $client = new Client(apiKey: $api_key);

  // SOURCE is optional. Defaults to "api". Pass "all" to delete every entry for the recipient.
  $source = getenv('SOURCE') ?: null;

  $response = $client->suppressions->delete($recipient, $source);

  print_r($response->toArray());
  ```
</CodeGroup>

Set the following before running:

* `MAILCHANNELS_API_KEY` — the API key that owns the suppression entry.
* `RECIPIENT` — the email address whose suppression entry should be removed.
* `SOURCE` — optional, defaults to `api`. Pass `all` to delete every entry for the recipient regardless of source.