Managing suppressions

Suppression list entries can be managed via the suppression list page 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

#!/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 }] }"

// 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");

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

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());

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

#!/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"

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);

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

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());

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

#!/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"

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");

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

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());

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.

Get Started

API Reference

Authentication & Account Setup

Sending Email

Email Authentication

Webhooks & Delivery Events

Platform & Multi-tenant

Reputation and Abuse Control

Metrics & Monitoring

Operate in production

Migration guides

Integrations

For AI Agents

Create a suppression entry

List suppression entries

Delete a suppression entry

​Create a suppression entry

​List suppression entries

​Delete a suppression entry

Create a suppression entry

List suppression entries

Delete a suppression entry