Skip to main content
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 }] }"
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"
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"
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.